Repository navigation
Releases
v0.2.0-beta.4
The team lives in the repository. A .docket/ directory next to the code (roles, pipeline,
policies, settings, skills) is the team's configuration of record, applied by docket init or
docket pod <p> apply; eighteen shipped recipes cover teams, policy packs, methodology pipelines,
checks and tools. Since v0.2.0-beta.3 docket also gained a provider catalog of fourteen built-in
kind: provider documents, OpenTelemetry and Langfuse export with privacy levels, an operator
loop in which a gated task parks and waits in one inbox with notification channels, agent
consultations and evidence-v1, one git worktree per task, a network lockdown mode and an
execution envelope whose workspace isolation is opt-in (docket gates isolate on).
Breaking changes. docket has no installed base yet, so every compatibility path was removed
outright: docket auth is gone (use docket keys add and docket models provider add), tier
names (economy/standard/premium) are not accepted anywhere, removed commands are ordinary
unknown commands (exit 2), and the serve API is version 3. See Removed below.
Added
-
Console alone tells nobody, and docket now says so.
consoleis a silent channel dialect
(core.channel.SILENT_DIALECTS);Catalog.delivering()names the enabled channels that reach
an operator away from the terminal.docket doctorgains aNotifications:check, counted as
an issue once a pod exists (checks.notifications {ok, delivering}in--json);
docket serve --dispatchwarns once at startup,docket initafter the created summary and
docket pod <p> dispatchafter a flush that found events, all with one text naming
docket channels enable desktopandntfy --set topic=<topic>. On a TTY with a desktop
session,initoffersEnable desktop notifications now? [Y/n]and, on yes, enables it and
sends one test notification; nothing is ever enabled without that yes. The quick start's
"Run unattended" now opens with picking a channel.- Found by the first real park -> flush run: the same parked approval reached
desktopand
ntfytwice, once through its task and once standalone, because_park_callnever
recorded the task on the approval. It now does (context.taskId), and the inbox also folds
an approval whose token a waiting task holds, so one decision is one notification. - A consult's options can be answered from the CLI:
docket pod <p> answer --option <id>,
anddocket chatlists the options and prompts for one (Enter takes the recommended).
docket inboxprints a waiting task's question, its options and thedocket chathint,
and a parked task's held action with thedocket approve/denyhint (what the standalone
approval line showed before it was folded into its task).
Found live: the Lead asked a two-option question that Telegram and HTTP could answer and
the CLI could not, and the inbox showed only the task's description. - The built-in
desktopchannel now fires for a failed task too (on: [needs_you, task.failed]), the subscriptionntfyalready shipped; a task that fails while you are
away is something that needs you. A completed task still notifies nobody by default:
docket inboxlists it under "Done".
- Found by the first real park -> flush run: the same parked approval reached
-
The items carried out of Phases 36-38 (Waves 89-90, no phase).
docket pod <p> worktrees prune [--dry-run] [--force]removes finished tasks' worktrees and
merged branches, keeping (and naming) dirty, unmerged anddispatch --resume-able ones;
--forceremoves the worktree, keeps an unmerged branch and audits it.- A second SIGINT/SIGTERM makes
docket serveabandon in-flight sweeps: it requests
cancellation of each sweep run, exits 130/143, and the task endscancelled. approve_taskgrants a parked pod call for the rest of its task, bound to the role that
asked:docket approve <token> --option approve_task, Telegram/approve <token> task,
POST /approvals/<token>option, MCPapprovals_grant(option=). Each later hop of that role
gets one single-use pre-grant; at most 20 per task, dropped at a terminal status.- Channel notifications at the
conversationlevel carry a question's options and the
recommended id, and Telegram/answer <task> <option id>picks one. - A
run:step can carryenv:(refused forPATH,LD_*,PYTHON*,DOCKET_*and
credential names; the task coordinates win; values never reach the trace). The
anti-tautologyandmutationrecipes declare their overrides there. docket doctorlists every unjailed MCP server, global and per pod, and, when Docker is the
backend, warns if the jail image has nogit;config explainshowsisolateper server and
recipes show --jsonunjailed_mcp_servers.- A harness consult's
question.taskIdis the run token, not the session key.
-
The execution envelope (Phase 38, D-55, ADR 0020). With isolation on, an agent's
processes run in a jail, and nothing docket holds leaks into them.- Workspace isolation is opt-in (
docket gates isolate on; ADR 0021, see Changed). bwrap is
tried first, then Docker (DOCKET_SANDBOX_BACKENDstill forces one). With isolation on and
no usable backend a turn is refused before any model call, naming both fixes (install
bubblewrap, ordocket gates isolate off).docket doctorandgates isolate onprobe the real
backend. Inside the jail a task worktree's git dir and the repository's common dir are
writable, so an agent can commit;.git/hooks,.git/configandconfig.worktreestay
read-only, so the jail cannot plant code the host's nextgitwould run. docket gates network none|openand a podnetworksetting (noneonly narrows) cut the
jail's network: bwrap drops--share-net, Docker runs--network none. The default stays
open.network nonewith isolation off is refused at turn start.- stdio MCP servers start in the same jail as
bash(the turn's roots and network mode) unless
declaredisolate: false(docket mcp servers add --no-isolate, audited, shown bydoctor;
a recipe'skind: mcp-serverdocument may declare it too).code-intel'sast-grepserver
does, becauseuvxcannot write its cache in the jail. fetchresults pass thepre_inputhook like MCP results (fetch.result_blocked/
fetch.result_warn), through one shared screening function.verifyCmd,run:steps and an unjailedbashno longer inherit docket's credentials
(DOCKET_LLM_API_KEY, every provider-catalog credential name,TELEGRAM_BOT_TOKEN, every
stored secret name).docket serve --dispatchsweeps each pod in its own worker (DISPATCH_SWEEP_WORKERS,
default 4), so one pod's blocking hop no longer stalls the others. Stoppingservewaits for
in-flight sweeps.- A refused isolation or network posture settles the task
dispatch_refusedafter one attempt
(it was retried as a transient error).
- Workspace isolation is opt-in (
-
Verification-ready execution (Phase 37, D-54, ADR 0019). What a task brings back is its own,
screened and checkable by something other than docket.- One git worktree per task: at claim, a repo Implementer's task runs in
<implementer workspace>/tasks/<taskId>on branchdocket/<pod>/<taskId>, created from the
codebase HEAD and recorded on the task asworktree {dir, branch, baseCommit}. Evidence
baseCommitis that recorded commit, so a task'sdiffStatno longer counts earlier, unmerged
tasks.docket add/initcreates no worktree, and the per-member worktree and its
worktreeDir/worktreeBranchmeta are gone. Finished worktrees stay until the member is
removed; the operator merges the branch. - MCP tool results pass the
pre_inputhook as untrusted input before they reach the model:
blockrefuses the result naming the policy and server,redactscrubs it,warnpasses it;
each hit is audited (mcp_client.tool_result_blocked/_warn). - Command steps (
run:) receiveDOCKET_TASK_ID,DOCKET_BASE_COMMITand
DOCKET_HEAD_COMMIT, taken from the latest successful Implementer hop's evidence. - A
no_progressstop: a turn ends whenAGENT_LOOP_NO_PROGRESS_ROUNDS(default 3,0
disables) consecutive tool rounds only repeat calls and results already seen in the turn. - Recipes may ship
kind: mcp-serverdocuments undermcp-servers/(read/write declared as
access:).docket pod <p> applyinstalls them for that pod only, and nothing else does. A
turn's stdio MCP servers start in the turn's root. - Five recipes:
anti-tautology(new or changed tests must fail on the base commit),
mutation(mutmut on the changed source files, 80% threshold),spec-writerand
cross-family-review(two pinned models from different providers), andcode-intel
(ast-grep and a language server as read-only MCP servers). docket runs these checks and records
their output; it never scores them. - Known limits:
mutationscopes by file, not line, and is Python-only;anti-tautology
compares whole test files; the check recipes' overrides are read from the docket process
environment; finished task worktrees have no retention policy;fetchresults are not
screened.
- One git worktree per task: at claim, a repo Implementer's task runs in
-
Consultation packs and evidence-v1 (Phase 36, D-53, ADR 0018). An agent can now ask the
operator a structured question and an operator can see what a task did, from one builder on
every surface.consultis a built-inreadtool: the model asks adecision-kind question with options and
an optional recommendation (operator-v1.1QuestionV11, schemas under
docs/contracts/operator-v1.1/). In a single harness turn it is aquestion_askedevent
answered on stdin byquestionIdwith anoptionId; underrefusethe turn endsblocked
with the question on the v1.1 result. In a pod hop it parks the taskwaiting_inputand
...
v0.2.0-beta.3
The first beta with harness mode: docket harness run executes one governed agent turn for an
external plan-of-record and reports it as a versioned NDJSON contract. It also carries the changes
below since v0.2.0-beta.2, including one exit-status change: a pod dispatch or pipeline run whose
task fails now exits 1.
Added
docket harness runanddocket harness status— a non-interactive entry point that runs
one agent for one turn, to completion, in a workspace andDOCKET_HOMEthe caller supplies.
stdout carries newline-delimited events and one versioned result and nothing else; every log goes
to stderr. The wire contract's JSON schema is published atdocs/contracts/harness-v1/schema.json,
generated from the models and pinned byte-for-byte by a test, with NDJSON fixtures for the ok,
blocked, cancelled and refused shapes attests/fixtures/harness-contract/v1/. Exit status is 0
for a completed turn, 1 for one that ran and ended badly, and 2 for a refusal before any turn
began — the one deliberate exception to docket's otherwise
flat return convention, because a program parsing stdout cannot read a printed message.- A synchronous trace subscriber seam.
core/trace.py::subscribehands each sink the exact
record about to be appended, after redaction and before the write. With no subscribers the path
is byte-identical.
Changed
- A tool call that needs approval can now be refused immediately instead of waited on. A
caller with nobody to ask gets a typed, terminalapproval_unavailableresult naming the tool,
the call and the policy that stopped it, in milliseconds rather than after a two-minute timeout
repeated up to three times. The default remains unchanged: an ordinary caller still waits. - Cancellation now reaches an in-flight
bashcommand.docket runs cancelterminalizes a run
whose hop is sitting inside a long-running shell command, killing the process group the way a
timeout already did. Every other tool handler keeps the previous rule that an already-running
handler may finish. docket gates enable/disablehelp text now says what the commands do. They record an
approval-routing posture thatdocket gates statusanddocket doctorreport; nothing on the
live path reads it, and everyaskverdict is answered the same way by the CLI, HTTP, MCP and
Telegram channels regardless of it. The previous text said the flag changed where a verdict was
delivered.docket maintain <id> sessionsno longer says sessions are never compacted. They compact on
the turn path once history exceeds the role budget.docket pod <project> dispatchanddocket pipeline runexit 1 when a task fails. The exit
status now matches the run record: a dispatch whose run endsfailedexits 1, so
docket pod x dispatch && ...no longer continues past a failed task.blockedand
waiting_approvalare expected pauses and still exit 0.- The release build pins its backend to
hatchling==1.32.0. hatchling 1.32.1 writes the
unnormalized version (0.2.0-beta.2) into wheel metadata, where earlier releases carried the
normalized0.2.0b2.
Fixed
- Pod output no longer drops task ids and roles, and model text can no longer crash it. Output
fromdocket pod,docket trace <session>anddocket models presetpassed data through
terminal markup: every[<task-id>]and[<role>]was silently erased, and a task description
or model reply containing a closing tag such as[/bold]aborted the command with a markup
error (fordelegate, after the task was already queued). All of it now prints literally. - The
localpreset's note names the real command,docket models provider add <name> <base-url>; it omittedadd, and its bracketed placeholders were erased on screen.
Removed
- The
security.gatesEnabledkey infleet.jsonis no longer read or written. Nothing had ever
read it. An existingfleet.jsonthat carries the key still loads.
Notes
-
docket harness statuson a finished run reports the outcome but cannot recover the served model
or the blocked rule detail, which existed only in the turn's in-memory result. -
The development history — every closed wave and phase section of
TODO.mdandROADMAP.md,
the roadmap decision changelog, and superseded coordinator handoffs — is archived verbatim under
docs/cycles-ended/ with a SHA-256 manifest
(scripts/maint/split_board.py check). This file remains the user-facing release changelog.
Install
# Homebrew (macOS/Linux)
brew tap yielab/docket-cli https://github.com/yielab/docket
brew install docket-cli
# Or the version-pinned installer, which verifies the tarball's SHA-256 before extracting
curl -fsSL https://raw.githubusercontent.com/yielab/docket/v0.2.0-beta.3/install.sh \
| DOCKET_VERSION=0.2.0-beta.3 bashVerify
Every asset is listed in SHA256SUMS, and the wheel, the sdist, the installer tarball, SHA256SUMS
and the SPDX SBOM carry a GitHub build-provenance attestation:
sha256sum --check SHA256SUMS
gh attestation verify docket-0.2.0b3-py3-none-any.whl -R yielab/docketdocket is beta software. Expect breaking changes between beta releases and verify consequential
outcomes yourself. Cost figures are token-based estimates, not billed spend.
Full changelog: v0.2.0-beta.2...v0.2.0-beta.3
v0.2.0-beta.2
Release v0.2.0-beta.2. See CHANGELOG.md for details.
v0.2.0-beta.1
Release v0.2.0-beta.1. See CHANGELOG.md for details.
v0.1.0 (beta)
⚠️ Beta / early-stage release — use with care
docket v0.1.0 is beta software under active development. It has not reached a stable
release. Every feature is implemented and covered by the automated suite (pytest + golden
parity + ruff/mypy --strict), but passing automated tests is not the same as being
production-ready — most features have not yet had hands-on QA against real fleets, varied
OpenClaw versions, or messy real-world edge cases.
Risks to understand before you run it:
- docket manages autonomous agents that can execute commands. Enforced tool-approval gates,
Docker isolation, and audit logging are opt-in (docket gates enable) — off by default.
Read SECURITY.md and prefer a
trusted/sandboxed host over a public VPS. - No cost figure docket prints is your provider's invoice. Even "recorded spend" is an
accounting calculation derived from token counts and rates; it will not match your bill
exactly. Reconcile against your provider's billing dashboard before trusting any number. - Expect rough edges, breaking changes between versions, and occasional gaps between docs and
behavior. Verify anything important yourself before relying on it.
See CHANGELOG.md for details and the
README for per-feature status.