Changelog
All notable changes to docket are documented here.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased
Fixed
- The Homebrew formula installed docket without its dependencies. Homebrew's pip runs with
--no-deps, sobrew install docket-cliproduced adocketthat died onimport typer. The sixteen packages of the runtime closure are nowresourceblocks (built from sdists;rustis a build dependency for pydantic-core,libyamlfor PyYAML), the release lane checks that every pyproject dependency has one, andscripts/update-homebrew-sha.shrewrites only the asset digest, never a resource's. The formula's owntest doblock also expected0.2.0-beta.4where the package reports its PEP 440 form0.2.0b4; it now normalises. Found on 2026-10-07, same install. - The Homebrew formula downloaded
.../download/v/docket-v.tar.gz(404).urlinterpolated#{version}beforeversionwas declared, so everybrew install docket-clisincev0.2.0-beta.1failed at download. The URL now names the version literally, as Homebrew expects,scripts/update-homebrew-sha.shrewrites it at release time, and the release lane refuses an interpolated version. Found by the first real Homebrew install, 2026-10-07. - Homebrew 7 refuses an untrusted tap.
brew install docket-cliright afterbrew tapfails withRefusing to load formula ... from untrusted tap; the README, the quick start and the installer header now showbrew trust yielab/docket-clibetween the two.
0.2.0-beta.4 - 2026-10-06
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 anddocket pod <p> dispatchafter a flush that found events, all with one text namingdocket 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
desktopandntfytwice, 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". -
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). Theanti-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 andrecipes 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). -
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}. EvidencebaseCommitis that recorded commit, so a task'sdiffStatno longer counts earlier, unmerged tasks.docket add/initcreates no worktree, and the per-member worktree and itsworktreeDir/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_COMMITandDOCKET_HEAD_COMMIT, taken from the latest successful Implementer hop's evidence. - A
no_progressstop: a turn ends whenAGENT_LOOP_NO_PROGRESS_ROUNDS(default 3,0disables) consecutive tool rounds only repeat calls and results already seen in the turn. - Recipes may ship
kind: mcp-serverdocuments undermcp-servers/(read/write declared asaccess:).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-writerandcross-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-tautologycompares 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. -
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 underdocs/contracts/operator-v1.1/). In a single harness turn it is aquestion_askedevent answered on stdin byquestionIdwith anoptionId; underrefusethe turn endsblockedwith the question on the v1.1 result. In a pod hop it parks the taskwaiting_inputandanswer_taskre-enters the same role with the answer.maxConsultationsPerTaskcaps it task-wide.- Approval packs: a gated call carries a screened, 500-character-bounded
rationaletaken from the model's preceding text, and three options (approve_once,approve_task,deny).approve_taskpre-grants identical calls within the turn only.docket approve|deny --reason, HTTPreasonand a harnesscontent.reasonrecord why, with anactor, in the audit entry. - evidence-v1 (
core/evidence.py,docs/contracts/evidence-v1/): per-hop measured usage and a trace link for a task, read throughdocket pod <p> evidence <task> [--json],GET /tasks/<p>/<id>/evidenceand the harness result'stask.evidence. All three come from one builder. Usage isnullwhen the endpoint reports zero. - Corrections ledger: deny reasons, Reviewer
REQUEST-CHANGEStexts and declined answers append to<DOCKET_HOME>/corrections/<project>.jsonl, read withdocket pod <p> corrections. - Escalation metrics:
docket_tasks_started_total,docket_questions_total{kind,outcome}anddocket_decision_latency_secondson/metrics, anddocket metrics --escalation. They are lifetime-of-current-storage counts, not monotonic totals. - Harness
filesno longer lists paths that were already dirty before the run or that the verify command produced (P35-12). -
Known limits: the parked consult question crosses to the answering process through an in-process registry (out of process it fails closed);
approve_taskdoes not survive a parked and resumed hop; a single-turn consult'squestion.taskIdis the session key; options are not rendered in Telegram or channel notifications. -
Harness contract 1.1 is complete for an external supervisor (Phase 35, D-51, ADR 0017).
docket harness run --contract 1.1(opt-in;--contract 1.0stays byte-identical) adds process lifecycle events forbash(process_started/process_exited, withpgidandexitCodeorsignal);--answers stdinwith--answer-timeoutfor approvals and recipe questions;fileson the result (written and edited paths, plusgit statusin a git workspace);--token-file,--max-tokens,--policy;--recipe NAME|DIRwith--verify, reporting the hops in ataskblock; andapprovalson the result, so a denied or timed-out approval is visible without changingstatusor the exit code. The committed schema isdocs/contracts/harness-v1.1/schema.json, and an integration test validates every line of a real subprocess run against it. Approval mode for a recipe run travels as the ephemeral pod's setting, not an environment variable. - Mechanisms for the recipe runner (Phase 35, P35-7).
core/harness_pipeline.pyruns one recipe in place on an ephemeral pod for one task, through the same dispatch the pod uses. -
Fixes (Phase 35). Pod dispatch keeps its evidence (verify output, commit, base and diffstat);
requireVerifymakes a missing verify command fail a hop instead of advancing; aguardrail_blockevent carries the action, not the policy id; pod-scoped roles get their own token budget. Process groups forbashare cancellable bydocket runs canceland by SIGTERM on the harness. -
The operator loop: tasks park instead of blocking, and every human touchpoint speaks one contract (Phase 34, D-50, ADR 0016). An unattended pod's gated tool call no longer blocks a hop for 120s with nobody watching:
approvalMode: park(the default forserve --dispatch's sweep and a non-interactivedispatch; an interactive TTY still resolves towait) records the exact call and moves the task towaiting_approvalso the sweep moves on to the next pod in the same pass, and granting it re-runs the hop carrying a single-use pre-grant matched by a stable argument digest. A pipelineinputstep ({ask: {input: {from: <step>}}}) can instead park a taskwaiting_inputto ask a real question, shaped as an MCP elicitation request/ result; the opt-inintakerecipe wires this to a Lead's typedTaskBrief(objective/acceptance/resources/questions, verdictREADY/NEEDS-INPUT/REJECT) with a deterministic pre-flight check of named secrets/paths/verify commands before the Implementer ever runs.docket inbox(alsoGET /inbox, the MCPinboxtool, and Telegram's/status) is a pure, derived view across every pod's tasks and approvals; nothing is pushed anywhere until an operator enables akind: channeldocument (docket channels list|show|enable|disable|content|test|add|remove|export) — seven dialects ship, all off exceptconsole, each declaringcontent: minimal|actions|conversationunder the same confirmed-and-audited widening shape Phase 33 used for exporter privacy, and every notification is a CloudEvents 1.0 envelope, withwebhooksigning deliveries per Standard Webhooks. Parked work is answered fromdocket pod <p> answer,docket chat <task-id>,POST /tasks/<id>/answer, the MCPtask_answertool, or Telegram's new fifth verb/answer <task-id> <text>(still inbound-only, still screened bypre_input) — every one of these resolves through the singlecore.answers.answer_taskfunction.docket pod <p> explain interruptionsforecasts what could pause a task before it runs, anddocket pod <p> pregrant <task-id> "<command>"pre-approves an exact, whitespace-normalized command (a rephrased one still asks). Every task view now carries ana2aStatealongside docket's ownstatus, mapped onto A2A 1.0.0'sTaskStateenum, though docket does not itself become an A2A server this phase. Measured on the phase's own--scenario operator-looporacle:sweepBlockedSecondsfell from roughly 12-13s to under 1s deterministically onceparkshipped, confirming the blocking wait is gone — though under the local live model the same scenario still measured 138s, because the sweep remains one worker walking pods serially, a different and unfixed cost left deferred with its own trigger. Two known limits:channels-health.jsonrecords delivery counters that no CLI surface reads back yet, and mid-turn session resume (in place of a hop re-run) stays deferred pending a measured trigger. - Export privacy levels: you choose what leaves, and see it first (Phase 33, D-49, ADR 0015).
Each
kind: exporterdocument says what it shares beyond structure:privacy: minimal(the default for every built-in),actions(tool arguments, error text),conversation(prompts, replies, tool results) orfull(plus the system prompt), or an exactshare:list;contentMaxCharsbounds each value. Content leaves only through an allowlist, filtered per message part, and is captured into the local trace only while some enabled exporter grants it, so atminimaleverywhere the local trace is what it was without exporters.docket exporters privacy <name> <level>widens only after listing what starts leaving and to which host (a TTY confirmation, or--yes) and recordsexporter.privacyin the audit log;docket exporters preview <name>shows what a destination would receive from a real local session, offline.listgainsSHARES,showa "Leaves this host" block, and every exported session carriesdocket.privacy. Atconversation, Langfuse shows each generation's Input/Output, each tool's result, and the trace's own Input and Output (the session's task and its last answer, carried on the root and aliased by the built-inlangfusedocument), verified live with canaries at three levels; atminimalno canary reached the collector, Langfuse or the local trace. Compared with the pre-releasepayload: metadatadefault, an approval's command line and error text no longer leave atminimal. Export pipelines start once per process, so a runningdocket serveapplies a level change after a restart. - Traces can go to OpenTelemetry and Langfuse (Phase 32, D-48, ADR 0014). A destination is
a
kind: exporterdocument (core/exporter.py): endpoint, auth (bearer/header/basic/none, credential names only, never values),resource,aliasesand which event types to send. Five ship in the wheel undertemplates/exporters/, all disabled:otel-collector,jaeger,langfuse,honeycomb,phoenix; a global override inherits every field it does not set. The one wire dialect,otlp-http(edges/adapters/exporters/otlp_http.py), is deterministic OTLP JSON hand-rolled over stdliburllibwith a retry on 429/502/503/504 that honoursRetry-After; D-24's cut of the OpenTelemetry SDK stands. Every turn starts the bounded export pipeline lazily, flushes it on every return path (bounded byEXPORT_FLUSH_TIMEOUT_Seven if a destination hangs) and writes per-exporter health counters; zero enabled exporters costs one catalog read.docket exporters list|show|enable|disable|test|add|remove|exportis the CLI surface:enableresolves the declared credentials (prompting on a TTY, namingdocket keys add <NAME>off one), probes the endpoint, and writes only the minimal override.docket config explainanddocket doctorreport each exporter; apod.yamlmay nameexporters:, whichapplyanddocket recipes showreport and never activate. One session is one trace: every hop's model calls keep their own span ids (the key includes the role and the call's timestamp, not only its iteration, which each hop restarts at 1), so does each hop and each verification result, and the root is sent once, when the session ends, so a destination that upserts by span id keeps every generation, every hop and one root, and Langfuse's trace Input/Output show the task and the final answer rather than the first hop's. Verified live: a 4-hop dispatch against a Dockerotel-collectorproduced 29gen_ai.chatspans matchingdocket trace's 29llm_calllines and 39execute_toolspans; replaying that dispatch's trace now gives 29 distinct generation ids and one root, where before the fix Langfuse kept 12; a real dispatch reached Langfuse's own dashboard with timing and token counts. Seeobservability-export.spec.md§"External verification". - The model's own call is a trace event. Every chat-completions exchange (each turn
iteration, plus the compaction summarizer's own call) is a durable
llm_calltrace record carrying model, provider, measured latency and token counts, never a dollar figure.ChatResponsegainsmodel,provider,latency_ms; the trace record gains an optionaltask_id; the store gets its first owning spec,trace-store.spec.md.core/telemetry.pyprojects trace records into a neutral span model with ids derived from the session id, never random, andtrace_ingestnotifies subscribers before appending so a live consumer sees a driver-projected session in order. - A recipe library of three kinds, and a recipe that says what it brings. Twelve recipes
ship: the three teams, four policy packs that change no roster (
git-safety,no-egress,secrets-guard,prod-approval; every rule stated with the structuredtool/path/anyOfpredicates rather than free text, andsecure-build's andops-approval's own policies rewritten the same way), and five methodology pipelines that are the practice (tdd,spec-first,reflexion,dual-review,frugal). What a recipe brings is derived from its directory, never declared:docket validate <dir>,docket pod <p> apply --dry-run,docket init --recipeand the newdocket recipes list|showprint the same summary line.pod.yamlgains an optionaldescription; a recipe name resolves against a directory path, your own~/.docket/recipes/<name>/, then the shipped library;applyrecords the pod'sconfigSourceafter every validated apply, an all-skipone included, so composing recipes and applying the exported.docket/leaves the record naming the repository. The pagedocs/recipes.mdis generated from the recipes and checked in CI. - Skills, in the Agent Skills shape.
skills/<name>/SKILL.md(front mattername+description, the body on demand) is discovered from three scopes, nearest wins by name: the repository's.docket/skills/, the pod's ownconfig/skills/(a recipe'sskills/is applied there and exported back), and~/.docket/skills/. The system prompt carries a# Skillsindex of screened descriptions; a new built-inskilltool of kindreadreturns the body or a file inside the skill's directory through the same chokepoint, deniable per role.secure-buildshipssecurity-review,tddshipstest-first,spec-firstshipswriting-a-spec.docket config explainlists the skills an agent sees. AGENTS.mdis read by default. When a pod'sprojectInstructionsis unset and the codebase root holdsAGENTS.md, the file every other coding agent reads is composed as the project-instructions section: screened throughpre_inputas untrusted, capped, reported; an explicitprojectInstructionslist replaces the default.docket config explainnames the files and their source.docket pod <p> apply <name>takes a shipped recipe by name. The argument resolves as a directory if one exists there, else as one of the shipped recipes (secure-build,research-review,ops-approval), exactly asdocket init --reciperesolves it, so a recipe can be applied onto an existing pod without a path into the installed package.- The team lives in the repo. A repository's
.docket/directory (the same shape every shipped recipe anddocket pod <p> exportwrite:pod.yaml,roles/,pipeline.yaml,policies/,plugins/) is the team's configuration of record.docket initdiscovers it, validates every document before provisioning anything, and applies it after the pod exists;docket init --recipe <name|dir>starts from a shipped or local recipe the same way (mutually exclusive with a present.docket/);--no-applyprovisions only. Nothing is applied without an operator command: dispatch,serve, schedules and the harness never read the directory. - A pod knows where its team came from.
applyrecordsconfigSourceandconfigDigest(written by nothing else;pod config setand apod.yamlsettingsmapping refuse them),docket pod <p> exportdefaults to<codebase>/.docket/likeapply, anddocket config explain <agent>reports the source, the digest anddrift: yes|no. - A pipeline step names its model.
model: cheap|strong|<provider>/<id>on a step, in the canonical and the short form, wins for that hop only and is never written to the agent's metadata;docket pipeline planprints it andvalidate/planrefuse an unknown provider naming the step. - One field says what a role may not do.
editRightsis retired from the role wire format: a stored overlay that still carries it loads and drops it,roles shownever writes it,roles listloses the column, anddocket validateprints anote:for a file that still declares it.deniedTools(cannotin the short form) is the only capability statement. config explainsays where a model goes, anddoctorchecks the provider catalog.docket config explain <agent> --jsoncarries aproviderblock (name, scope, dialect, base URL, the credential's name and source, the exact model row's limits) and the human view prints it under the model line, never a value;docket doctornames a malformed global provider document by file and field, in the human pass and under--json. The configuration guide, model-gateways page, troubleshooting page and quick start describe the catalog,export, theRetry-Afterceiling and the evaluation-only/beta status Anthropic and Google give their OpenAI-compatible layers.- Registration verifies with the credential, and a provider round-trips through the CLI.
docket models provider add <file.yaml>(or theadd <name> <url> --model <id> [--credential NAME]shortcut) probes<url>/modelswith the resolved credential and classifies the answer: only a transport failure refuses; 401/403 registers and names the missing or rejected credential; 404 registers and says the route is unserved; a 200 that advertises ids the document lacks prints them as suggestions.list,show [--json],removeandexportcomplete the round trip (export-> fresh home ->add-> identicalshow --json), anddocket models preset <name>prints one readiness line naming the credential as present or missing. - A provider can authenticate by header and send static headers.
auth: {type: header, header: api-key, credentials: [AZURE_KEY]}sends the credential under that header (Azure OpenAI, a multi-workspace Anthropic key) andheaders:adds static headers to every request;Authorization,Content-TypeandAcceptare refused at load. A bearer document's request is byte-identical to before. - Fourteen providers ship as built-in documents, and every table derives from them.
templates/providers/holdsanthropic,openai,google,openrouter,ai-gateway,groq,mistral,deepseek,xai,cerebras,together,ollama,lmstudioandlocal; presets, prices (withpricesAsOf), key-format prefixes, credential names and base URLs are read from the catalog, sodocket models preset anthropic|openai|googleapplies without a priorprovider addand a stored key alone readies a built-in hosted provider. A provider absent from the catalog resolves only underDOCKET_LLM_BASE_URL. - A retry waits as long as the provider asked, up to a ceiling. A retryable HTTP failure
carries the endpoint's
Retry-After(seconds or HTTP-date) throughTurnResult.retry_after_s; the dispatch backoff ismin(max(2s x attempt, Retry-After), DISPATCH_RETRY_MAX_WAIT_S)(default 60 s) and thehop_retrytrace event records it. - A model provider is a
kind: providerdocument.core/provider.pyholds the catalog: built-in documents undertemplates/providers/and the operator's own in~/.docket/docket-providers.json, nearest-wins by name. A document names its credentials (auth.credentials) and never holds a value;resolve_endpointreads the catalog and the exact model row's limits. A pre-catalogfleet.json -> providersblock is migrated once on first use (a literalapiKeymoves into the secret store under<NAME>_API_KEY, auditedprovider.migrate), anddocket validate <file>acceptskind: provider. - A policy can call a Python predicate the operator applied, never one the agent wrote.
when: {plugin: <name>, with: {...}}runs a@predicatefrom~/.docket/plugins/or the pod's ownconfig/plugins/-- the only two places ever imported; a file in the codebase is invisible untildocket pod <p> applycopies it with its sha256. An unknown name, a raise, a non-bool return or a call over its budget denies, naming the plugin; every call is audited aspolicy.plugin.docket plugins list [--pod <p>]shows name, scope, file and hash. The public API isdocket.plugins(PLUGIN_API_VERSION = "1.0.0"). - Schemas an editor can use, and export in the short form.
docs/contracts/config-v1/holds generated JSON Schemas for the four kinds, pinned byte-for-byte and shipped with the package;docket pod <p> exportnow writes short-form YAML (a.mdbeside each role,kind:andname:onpod.yaml) with a# yaml-language-server: $schema=header and a.schemas/copy, and applying an export plans every itemskip. The shipped recipes and the configuration guide show only the v1 short form. - Outcomes route the pipeline, and every loop has a bound. A step's
on:map sends any gate outcome -- a verdict marker,pass/failof a verify command -- tofail,stop, a later step or an earlier one; a backward edge needsmax, andvalidate/planrefuse a missing bound or an unreachable step.until: verifywithmaxretries a step until its verify command passes. Every routing decision is aroute_takentrace event; the shipped recipes and the one-rework-edge form are byte-identical. - A step can be skipped, and a step can be a command.
when: {changed: "src/**"},when: {var: name, is: value}orwhen: {memberPresent: role}skips a step (step_skippedtrace event, no hop).- lint: {run: "ruff check ."}runs a command in the pod's worktree with no agent turn and no model tokens, classified like any shell-out (an unlisted command asks, or fails underapprovalMode refuse); its exit code, or a single upper-case last output line, is the outcome itson:map reads.planprints both. - Every configuration file can say what it is, and one command validates them all. A
role, pipeline, policy or
pod.yamlmay start withkind:andname:;docket validate [dir|file]checks every document under a directory (default.docket/) and printsfile:line field: message (valid: a, b, c; did you mean "b"?), exit 1 on any invalid file. A file withoutkind:still loads, with one deprecation note per command. - Policies read as "when this, then that". A policy may be short-form YAML (
kind: policy,appliesTo,on: input|toolCall|output,when,then: allow|warn|ask|block|redact) with structured predicates over the call itself --tool,path(glob over the path argument),matches(regex over the rendered text),branch(glob over the worktree branch),anyOffor OR -- evaluated inside the same chokepoint. The six shipped templates are now short-form YAML; every existing JSON policy keeps loading unchanged.docket policies testtakes--arg key=value. - A pipeline step reads as "who, what is checked, where it goes".
- build: implementerplusverify: true,verdict: [APPROVE, REQUEST-CHANGES],approval: <message>oron: {REQUEST-CHANGES: {goto: build, max: 1}}; the canonical form is unchanged and still whatplanprints. The three shipped recipes are written in the short form. - A role file carries only what is enforced.
cannot: [write, edit, bash], one ofverdict/verify/approval,model: cheap|strong, andinstructions: <file.md>whose Markdown becomes the role's prose (an optional## AGENTSsection supplies the red lines);editRightsis derived fromcannot, never authored. - A pod exports its own scope, and the round trip is the proof.
docket pod <p> export <dir> [--force]writes the pod's role overlay, its policies, its bound pipeline and apod.yamlof members and non-default settings, never anything global; applying that directory to a fresh pod in a fresh home reproduces the sameconfig explain --json.applyalso carries a recipe'spolicies/*.jsoninto the pod, so the shipped recipes need no manual copy. - A recipe applies to any pod in one command.
docket pod <p> apply [<dir>] [--dry-run] [--json](default<codebase>/.docket/) readsroles/*.yaml,policies/*.json,pipeline.yamland a three-keypod.yaml(members,settings,pipeline), validates everything before writing anything, is idempotent, and audits once aspod.apply. The three shipped recipes carry apod.yamland their README's "Apply it" is that one command. - Every resolved value says which scope it came from.
docket config explain <agent> --jsonlabels the role, each policy file, each loaded MCP server and each denied tool withscope: built-in | global | pod, anddocket doctornames a malformed pod role overlay entry or an invalid pod policy file by pod, item and reason. - A pod chooses its MCP servers and denies tools for every role in it.
docket pod <p> config set mcpServers a,blimits a pod to those catalog servers (unset means all; an unknown or stale name is refused at write and refuses the dispatch naming it), andset deniedTools fetchremoves a built-in tool from every role of that pod on top of each role's own denials. - The Lead's instruction is data. The
leadarchetype carries ahopInstruction(shown bydocket roles show lead); a global or pod overlay oflead, or a pipeline step's owninstructions, now changes what the Lead is told. Research, content and ops pods' Leads plan for their real next role instead of an Implementer they do not have. - A pod has its own role overlay and its own policies.
docket roles add|list|show --pod <p>write and resolve~/.docket/workspaces/pods/<p>/config/roles.jsonabove the global overlay for that pod alone, anddocket policies list|test|validate --pod <p>fold that pod'sconfig/policies/*.jsoninto the same most-restrictive-wins evaluation, so a pod's policies can only add restrictions. Both reach a member's live turn, including a standalone one. - An MCP server declares its kind and its exposed tools.
docket mcp servers add <name> --kind read|write --tools a,b -- <cmd>: a server declaredreadnow reaches a read-only role instead of being dropped with everything else;--toolslimits which advertised tools register. Undeclared servers keep the fail-closedwritedefault. - A pod's dispatch settings are a typed, validated, writable configuration surface.
docket pod <p> config [get|set|unset] <key> [<value>](with--jsononget) covers nine keys —budgetUsd,maxReworkCycles,turnTimeoutS,verifyTimeoutS,approvalMode,allowCommands,pipeline,scheduleandprojectInstructions— validated at write and audited aspod.config. An invalid stored value now refuses dispatch naming the key, instead of silently falling back to a default, anddocket profile --budgetwritesbudgetUsdas a number, not a string. - An unattended dispatch can refuse instead of waiting on nobody. Setting a pod's
approvalModetorefusemakes a hop that would otherwise block on a human approval fail the task at once, naming the tool and policy, instead of sitting on the approval timeout under an unwatched schedule or serve sweep. The default (wait) is unchanged. - A pod can allow its own tool binaries.
allowCommandsnames extra bash binaries that pod's agents may run without an approval prompt, scoped to that pod and validated at write: a path, a shell metacharacter, an opaque name (eval,source, ...) or a high-risk-class binary (git,npm) is refused, and a redirected call still asks. - A pipeline file can be a pod's default for every trigger.
docket pod <p> config set pipeline <file>validates the file, plans it against the pod's roster, and stores a docket-owned copy with its hash; that pipeline then runs for a manual dispatch, aserve --dispatchsweep, a schedule, and a webhook or MCP dispatch alike, not only a manually-passed--file.unset pipelinerestores the blueprint default, anddocket pipeline planprints aSource:line naming which one would run. - Custom roles can carry their own hop instructions, and pipeline steps can be parameterized.
A role archetype's
hopInstruction(or one generated from its gate contract when unset) now reaches a custom role's hop, and a pipeline step's owninstructionsfield overrides it. Step instructions may reference${name}variables, resolved from repeatabledocket pipeline run --var key=valueflags as well as from a webhook payload; an unresolved variable refuses the run instead of sending the literal placeholder. docket config explain <agent>shows the effective configuration with provenance. One read-only command (with--json) reports the resolved model and endpoint, each prompt section's size and fit status, the agent's tools after role denials plus the configured MCP servers, the policies that apply to the role, the effective pipeline and its source, and budgets, timeouts,approvalModeandallowCommands— each value tagged with what set it (meta, policy, pin, pod setting, env or default).- An operator-owned
INSTRUCTIONS.mdcomposes into every agent's prompt and survives regeneration. docket never writes it.docket pod <p> sync [--dry-run]re-rendersSOUL.md,AGENTS.mdandTOOLS.mdfrom the current role archetype and metadata for any pod member whose template or archetype has gone stale, showing a diff first with--dry-run;docket doctorflags pod members that are out of date. - A pod can opt an agent into reading its own codebase's project instructions. Setting
projectInstructionsto one or more relative paths (for exampleAGENTS.md) composes those files into the prompt right afterINSTRUCTIONS.md; each one is screened as untrusted input by thepre_inputpolicy hook, a missing file shows a visible marker instead of failing silently, and a path that would escape the codebase root is refused when the setting is written. Unset (the default), nothing changes. - Old runs, resolved approvals and closed conversations are pruned automatically and on
demand. The trace-retention window now also bounds
docket-runs.json, the approval store anddocket-conversations.json; only terminal records are removed, and live or pending ones are never touched.docket runs prune [--days N] [--dry-run]anddocket conversations prune [--days N] [--dry-run]run it on demand. - Three shipped recipes —
secure-build(implementer plus a security-vetter verdict gate),research-reviewandops-approval— ship intemplates/recipes/: role, pipeline, an optional policy pack and a README with the exact commands to apply them. Each is validated in CI, andsecure-buildis proven end to end by a dispatch todoneon the fake driver.
Changed
- Workspace isolation is opt-in (ADR 0021). A fresh install runs tools on the host and needs
no sandbox;
docket gates isolate onjailsbashand stdio MCP servers in bwrap (Linux) or Docker, and once on a turn with no backend is still refused.gates statusanddoctorreadoff (default). Requirements are documented indocs/SECURITY-SIMPLE.md. - Unknown
docket gatesanddocket contextsubcommands exit 2.gatesused to print its usage and exit 0, andcontextsilently fell through toshow; both now name the unknown subcommand and exit 2. docket audit verifyreports an unchained line as a break. A line withoutseq/prev_hashused to be counted as "legacy", skipped, and treated as a chain restart; it now fails verification at that line, like any other break.- The
serveAPI version is 3./status.json(and the MCPstatustool) no longer carry agatewayfield,/healthanswers{"status":"ok"}, and thedocket_gateway_upmetric is gone. The undocumented bare/statusroute is gone; use/status.json. - The docs open with the newcomer path. The quick start is rebuilt as install → register a
model → create the team (recipe, plain, or a committed
.docket/) → run a task → read the record → export, edit, validate, apply → run unattended, with the terminal output of one real run; the docs index leads with the tagline and a start-here order; the configuration guide gains a complete.docket/example and the export→validate→apply loop, states that a broken policy fails closed and that a pod selects its MCP servers; the agent-teams guide drops the retired edit-rights column for the denied-tools one; every recipe README prints a command a user can type; the site navigation lists Configuration and the Workflow guide. - The README carries one pitch: agent teams as configuration, your rules, in YAML. The
front door opens with three sections -- the team you define (the
.docket/directory and a role and a pipeline in their short form), the run, and the gate and the record -- each showing an asset captured from one real run, stating its limit beside the capability and ending in the command that proves it, followed by the quick start, which now starts from a shipped recipe and ends by writing the team back to the repository. The five-pain intro, the eight guarantees and the sixteen-bullet feature list are folded into those sections or relocated (best practices to the quick start, the tested adapter list to COMPATIBILITY.md, which is now its only owner). The package, module and site descriptions carry the same tagline. The prose tests that pinned the old headings were rebuilt from the new README's own rules rather than carried forward. - Non-software pods run their blueprint pipeline.
docket pod <p> dispatch,docket pipeline plan|runwithout--file,POST /dispatch/<p>, theserve --dispatchsweep, schedules and Telegram/delegatenow resolve the Lead'sblueprintand run that blueprint's full roster and gates. A research, content or ops pod used to run only its Lead; it now runs more hops and spends more tokens per dispatch pass. Software and agentic-product pods, and any pod whose Lead has no or an unknown blueprint, behave exactly as before. -
docket modelsno longer claims prices can be overridden indocket-models.json; no pricing overlay is read. -
A prompt's context budget follows the resolved model's context window instead of a fixed ~24 KB for every model. A 200k-window endpoint now fits a full identity/memory/task-ledger prompt that a fixed budget used to truncate; a 16k-window endpoint keeps today's behaviour.
CONTEXT_TOKEN_BUDGETand an archetype'stokenBudgetstill work as explicit overrides, anddocket maintain checkplus each turn'sprompt_composedtrace event report the effective budget and what set it. - A truncated or omitted prompt section is always marked, never silent. An oversized
SOUL.mdused to be able to pushHEARTBEAT.md,AGENTS.md,TOOLS.mdandMEMORY.mdout of the prompt with nothing to say so; the runtime contract and task-ledger state are now protected ahead ofSOUL.md, an oversized section is truncated with a visible marker, and every composition'sprompt_composedtrace event lists each section's size and whether it was full, truncated or omitted. - There is one default model of record.
docket-models.json'sdefaultis now the only source; the separate, sometimes-divergingfleet.jsondefault is no longer read. A provider's display name derives from--modelunless--nameis given, instead of every entry showing the shipped local model's caption. - Built-in role templates no longer instruct an agent to do something the runtime forbids.
The generated
AGENTS.mdtext stops telling agents to writeHEARTBEAT.mddirectly (private state is read-only on the live path);WORKFLOW_AUTO.mdis now labelled as the manual-path contract it actually is.
Fixed
- The jail could rewrite git metadata the host later runs: a submodule's hooks and config, a
linked worktree's
.gitfile and itsgitdir/commondir, andinfo/attributesare now read-only, and a missinghooks/dir or attributes file is created empty first so the jail cannot create it. - A jailed
git commitfailed whenever the operator's identity came from the environment or a non-defaultHOME, and always under Docker: the jail now receives the operator's git identity (never a credential). - No inbox view,
/inboxresponse or channel notification ever carried a parked task'squestionorbrief: the fields existed and nothing filled them. - A parked consult whose question lived only in the dispatching process stuck its task in
waiting_approvalwhen answered elsewhere; the question is now persisted (0600) and a missing one fails the taskconsult_question_missing. -
git_branch_mergedread every branch checked out in a worktree as unmerged (it ignored git's+marker). -
globandgrepno longer return or read files outside their roots through a symlink, a symlinked directory, or a..in the pattern. - The key-shaped redaction pattern no longer matches inside a word:
task=<id>was redacted tota[REDACTED]. -
A task paused on a question is a warning, not an error.
docket pod <p> dispatchrenderedwaiting_inputwith the error marker; it now renders likewaiting_approval(found in the Phase 36 live run). -
A canonical role file that says
kind: roleloads as written.load_role_filetreated thekind:key as proof of the short form and normalized a canonical document, dropping itsdeniedTools/gateContract/templates and then failing on a missing<name>.md; a document carrying a canonical-only key now passes through, and one mixing both forms is refused naming the keys. docket initcounts the members a.docket/or--recipeadded. The closingcreated with N membersline and the id list reported the blueprint roster only; they now report the pod as it stands after the apply step.- A recipe's own role no longer routes to the hosted default on a local fleet. A role a
recipe applied into a pod's overlay (
security-vetter,model: strong) was resolved against the global role registry only, so it fell to the compiled-inanthropic/claude-sonnet-4-6while every other member followeddocket models preset local; the first dispatch then hit the hosted vendor with no key (HTTP 401). Found by running the product for the new assets.resolve_role_modelnow looks the archetype up in the member's pod registry and an unknown role falls back to the registry's owndefault.docket pod <p> applyanddocket initalso print the plan's[add]/[replace]/[skip]actions again; Rich had been reading them as style tags and dropping them. - A
cdprefix no longer turns an allowed command into an approval.cd,pwd,echo,true,false,testand[joined the bash allowlist, socd <worktree> && git statusruns likegit status; an unattended implementer hop used to time out three times on exactly that shape and fail.echowith an output redirect still asks, andexport/source/.still ask.docket policies test pre_tool_callnow evaluates through the live gate's own function, so it can no longer reportallowfor a command the gate asks about. GET /traces/<project>delivers every event exactly once across session files. An event written in a second the cursor had already partly delivered, to a session file that sorts earlier, was dropped while another was delivered twice. Events from the still-open second are now held back until it closes; the cursor format is unchanged.docket help <command>prints that command's usage, or exits 1 naming an unknown command.docs/contracts/harness-v1/schema.jsonvalidates as JSON Schema. Its nested$refs pointed at definitions the document did not contain, so a standard validator failed on#/definitions/HarnessResult. The contract stays1.0.0; no field changed.- The HTTP control plane sends
Cache-Control: no-store, as its spec always said; a barePOST /approvals,/tasksor/dispatchis authenticated before it is answered400; and a request body over 1 MiB is refused413without being read. - Resolving an approval the other way answers
409, not404. Denying an approval that was already granted (or the reverse) raised the same error as an unknown token, soPOST /approvals/<token>said the token did not exist. It now answers409naming the decision that won. The same seam made one cancellation test flaky when the in-turn cancellation denied first; the test now accepts either winner and still proves the tool never ran. docket cost <id> --jsonreturns that agent only. It used to return the whole fleet and exit 0 even for an id that does not exist; an unknown id now exits 1 with nothing on stdout.docket roles,gates,keys,policiesandmaintainreject an unrecognised--flagwith exit 2 instead of silently ignoring it.POST /podsanddocket init --fromvalidate the project id. A project id such as../../xused to provision workspaces and fleet registrations outsideDOCKET_HOME/workspaces.core/provisioning.py::validate_project_id(lowercase alphanumeric segments joined by single hyphens, at most 64 characters) now runs first inprovision_pod; the HTTP routes answer400and the declarative file exits 1 for an invalid id.docket mcp servers add <name> -- <command>works from the real CLI. Click consumed the--separator before the handler saw it, so the command's own help example always failed with "Missing '--' separator".- An approval granted or denied over MCP resumes or fails the dispatch task it gated, the same
as
docket approve/docket deny, the HTTP route and Telegram. A task decided over MCP used to staywaiting_approval. docket maintain <id> rebuildno longer deletesmemory/*.md, and refuses a pod member with exit 1 instead of overwriting its role prompt,TOOLS.mdandHEARTBEAT.mdwith the legacy flat-agent templates.- A
verifyCmdthat times out is killed as a whole process group, so a command that backgrounds work no longer leaves orphaned processes behind after the hop moves on. POST /approvals/<token>accepts onlyhttportackaschannel. A Bearer holder used to be able to record a decision ascli,mcp,telegramor eventimeout, forging another surface's provenance in the hash-chained audit log and indocket_approvals_total.docket list --jsonanddocket info --jsonemitbudgetUsdas a number ornull(they emitted the stored string, or""), anddocket snapshotemitslastActivity: "never", the same sentinel/status.jsonuses.docket doctor's budget check anddocket cost's high-cost warning can fire. Both compared recorded spend, whichDocketDriveralways reports as 0.0, so neither ever triggered. They now read the same recorded-or-estimated figure the dispatch budget gate uses, labelled as an estimate when it is one.- A broken policy file now fails closed. An unloadable policy JSON, an uncompilable regex
pattern, or an unknown
actionused to make every call on that hook evaluate toallow; each now makes every call in that file's readable scope (or, if the JSON itself cannot be parsed, all hooks) resolve to a block naming the file — across the live gate anddocket policies test.docket policies validatenow compiles every regex instead of accepting a pattern it never checks,docket policies test pre_tool_calltakes--tool <name>so a non-bashtool is not misclassified against the command allowlist, anddocket doctorreports a broken policy file as an error. docket doctorreports a broken schedule, model-policy entry or overlay role by name instead of silently skipping it, andservelogs a skipped schedule once per sweep.docket pod <p> config set schedule "<spec>"validates and writes a schedule (previously writable only by hand-editing the file), andunsetremoves it.docket deleteremoves a pod member's merged branch and its provisioning lock directory. A mergeddocket/<pod>/<member>branch and stale lock entries used to survive teardown; an unmerged branch is still kept, with the command to remove it printed. Newly created workspace and pod directories are now0700.- A deterministic dispatch refusal now fails the task instead of orphaning it. A refusal
raised inside a claimed task — an unknown pod member, an invalid stored setting, a membership
mismatch — used to leave the task
runningwith no process behind it and no way to resume; it now ends that taskfailedwith the refusal as its reason, and--resumepicks it up from its last persisted hop. A pod's membership is now read from each agent's own recorded metadata rather than guessed from its id string, which is what could raise that refusal for a hyphenated custom role name in the first place. - An approval's trace event is now filed under its pod, not the individual agent id —
matching where
docket trace <project>anddocket metricsalready look for one.
Removed
fleet.json'ssecurity.isolationEnabledfield andcore.fleet.get_isolation_mode();security.isolationModeis the only isolation state.- Every compatibility path is gone. docket has no installed base to migrate, so code that only kept an old name, flag, route or file shape working was deleted.
- Command aliases:
show,rm,remove,telegram,key,secret,log,usage,check,security,export,completionandpolicyare unknown commands. Useinfo,delete,wire,keys,logs,cost,doctor,gates,snapshot,completionsandpolicies. - Removed-command notices:
auth,team,workflow/wf,eval/evals,model,tier,billing,credits,monitor/mon,memory/mem,smart,ai,mode,terminal/termand the top-levelreset,repair,fix,cleanupandcleanno longer print a notice; they are plain unknown commands. - Flags and subcommands: the hidden
--debugflag and hidden_jsoncommand;docket gates enable/disableandgates ... --force;docket init --gates/--no-gatesandinit --path(use--codebase);docket profile <id> policy(usedefault);docket models ls(uselist); the trailing count indocket pod <p> add <role> <N>(use--count/-n);docket maintain --distill-first(distilling first is the default;--no-distill-firstremains);--jsonin place ofdocket audit's count argument (the--jsonflag is unchanged);programmeras a pod role alias forimplementer(programmerstays a role-policy key fordocket models set). - Approval-routing posture: the
approvalRoutingState/approvalRoutingModeflag that nothing on the live path read, and the "Approval routing" line indocket gates status. The tool-call gate is always on;docket gatesmanages only isolation (status,isolate,classes). - Migrations of old files: a
defaults.modelorprovidersblock infleet.json, aprofiles:key indocket-models.json, the old Anthropic model-id aliases (claude-3.xto4.x), and an exporter'spayload/payloadMaxCharskeys are no longer read or converted. docket doctorchecks: stale model names, theprofiles:key, a stray workspace.env, leftover global specialist workspaces, metadata backfill, and quarantining a model-writtenIDENTITY.md/BOOTSTRAP.mdinto.docket-archive/.doctor --jsondrops thefzf,approvalRouting,routingMode,modelConfigandmodelRegistrykeys. The doctor footer now points atdocket maintain [id] checkinstead of the removeddocket repair.- The
gatewayfield indocket snapshot,/status.jsonand the MCPstatustool, which always readinactive. - fzf: the agent picker is the numbered one; fzf was never invoked and is no longer an optional Homebrew dependency.
SITES_DIRandDOCKET_LOG_DIR:docket initno longer creates~/Sitesor/tmp/docket; nothing wrote there.docket installin the install script and Homebrew caveats: there is no such command; first-time setup isdocket init.docket authis gone. Store a key withdocket keys add <NAME>; register an endpoint withdocket models provider add.docket keys setupwalks the provider catalog instead of a fixed five-provider list.- docket no longer writes an API key into every workspace's
.envfile. Stored keys are resolved only where they are read;keys addunder thekeyringbackend either stores throughsecret-toolor refuses with an honest message instead of silently doing nothing.
0.2.0-beta.3 - 2026-09-18
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, terminal
approval_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, sodocket pod x dispatch && ...no longer continues past a failed task.blockedandwaiting_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
from
docket 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. - Trace redaction no longer slows quadratically on long repetitive text. Two of the
secret-shape patterns behind
core/trace.py's redaction backtracked on a long run of alphanumeric characters (base64, a hex dump, a minified bundle), the shape a tool result takes near the default output ceiling: 40,000 characters took about ten seconds to redact. The patterns are now bounded and match exactly the same secrets. - 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.
0.2.0-beta.2 - 2026-09-07
This provenance-complete beta publishes the current root wheel, source distribution, versioned installer archive, checksums, SPDX SBOM, and GitHub build provenance attestation. It includes the Wave 29 recovery, starter, adoption-evidence, governance, and public-release work described below.
Added
- Reproducible adoption evidence (W29-C6). An exact-commit generator builds and installs the
root wheel on Python 3.11, repeats the starter and seven governance/recovery fixtures three times,
and publishes canonical attempts, aggregates, provenance, privacy checks, and an explicitly
limited public report under
benchmarks/results/wave29/anddocs/ADOPTION-EVIDENCE.md. Its JSON Schema publication oracle is a declared test-only dependency installed by the floor harness, without expanding Docket's runtime dependency set. CI jobs that validate the pinned source fetch complete Git history so provenance remains resolvable. The exact-artifact builder pins its managed Python and Hatchling closure, then canonicalizes wheel compression with checksum-verified zlib-ng so clean environments reproduce the published hash. - Provisioning startup contract (
core/memory.py): every agent workspace is now seeded with the files the OpenClaw runtime re-reads after each compaction —WORKFLOW_AUTO.md(anchors the codebase path, the read order, and a "answer about the product, not your scaffolding" directive) plus a curatedMEMORY.md(with a What this project is product summary) and today's dated memory log. Fixes agents that looped after compaction demanding files that never existed, and that answered "what is this project about" with their own pod/workspace metadata. docket doctornow heals any agent whose startup contract is missing or stale (detected via an embedded contract-version marker), not just absent.- docket takes the runtime (Phase 19, decision D-19). docket now owns the whole agent turn,
not just what happens between turns.
core/llm.py+edges/adapters/llm.py(P19-1) is a zero-new-dependency OpenAI-compatible chat-completions client (stdliburllib) — any endpoint that speaks that wire format works, hosted or local.core/tools.py(P19-2/P19-3) is the gated tool registry and the single chokepoint every tool call now passes through (an AST test enforces it), withpre_input/pre_tool_call/pre_outputpolicy hooks all actually evaluated — four templates shipped since Phase 11 and never once evaluated finally run.core/session.py(P19-4) gives every session durable turn history with compaction that never splits a tool-call/tool-result pair.core/agent_loop.py(P19-5), wired to dispatch through a newDocketDriver(edges/adapters/docket_runtime.py), is the bounded turn loop itself: max iterations, max tool calls, wall-clock timeout, and a measured-token budget. - Sandboxed exec (P19-9) — the
bashtool gained an opt-in sandbox (dockerorbwrapbackend,ToolContext.sandbox, default"off"), never true of the daemon's own exec path. - MCP client (P19-10,
core/mcp_tools.py+edges/adapters/mcp_client.py) — external MCP tool servers adapt into ordinary registry entries, gated exactly like a built-in and namespacedmcp__<server>__<tool>so a remote server cannot shadowbash.docket mcp servers add/list/remove(P19-13) makes configuring one just data, not code. fetchtool (P19-11) — a domain-allowlisted, size-capped, timeout-bounded HTTP fetch, refusing every domain by default until it is opted in (FETCH_ALLOWED_DOMAINS); the inspectable half of the network-egress story (bashcan still reach the network through interpreters and package managers on the curated allowlist — a documented, open gap, not a closed one).- Per-role tool sets + docket-owned identity (P19-12) — a role's tool registry is composed
from its archetype via
ToolRegistry.without(), so e.g. a Reviewer's registry has nowrite/edit/bashto call at all — structural, not instruction-level. - docket-owned Telegram channel (P19-8,
core/telegram.py) — docket itself is now the bot, long-polling the Bot API and routing/approve,/deny,/status,/delegatethrough the existing approval store and pod-delegation APIs. Closes a real gap: previously a Telegram reply answered the daemon's own, separate exec-approval prompt, which docket never saw and could not audit (Phase 15 G-5 spiked a bridge and found none). Every Telegram decision now writes the same audit entry a CLI or HTTP one does, taggedchannel="telegram". - Guardrail + loop metrics (Phase 20, P20-2) — four new families on the existing Prometheus
surface:
docket_tool_calls_total{decision},docket_policy_hits_total{policy_id,hook,action},docket_approvals_total{channel,outcome},docket_turn_duration_seconds. Recomputed from durable records at scrape time rather than an in-memory counter, so adocket serverestart never zeroes them and there is no second, driftable source of truth. docket-runtime, a standalone embeddable package (Phase 21,packages/docket-runtime/) — the turn loop, the gated tool registry, the policy engine, the approval store and the audit chain, packaged separately from the CLI so a product can embed the guardrails instead of reinventing them. Builds from the same source tree as the control plane, so the two cannot drift apart; a clean install pulls onlypydanticandfilelock. Deliberately not a hosted runtime — no multi-tenancy, external-caller auth, queues, or streaming; the embedding product owns its own serving layer.agentic-productpod blueprint (P21-5) — a fifth named pod shape alongside software/research/content/ops, added as a row in the existing blueprint registry.
Changed
- Documentation: the Telegram channel is a command surface, not a chat. The README
advertised "conversational dispatch — message the Lead directly", which never existed: plain
prose is answered with an "unrecognized command" reply. Two further claims in the same section
were also false — that a gated action "pings the wired group" (nothing is ever pushed;
send_messagehas exactly one call site, the reply insidepoll_once, andcore/approval.pyholds no reference to the module), and a setup snippet usingdocket servewhen the poll loop only starts under--telegram. Corrected acrossREADME.md,docs/commands.mdanddocs/QUICK-START-DOCKET.md. The functional spec was accurate throughout — it has always required "exactly four verbs" and that any other text be treated as unrecognized — so this was prose drifting from a correct spec, not a spec gap. specs/functional/telegram-integration.spec.mdnow states the inbound-only property as a requirement rather than leaving it implicit, plus that/delegateanswers with a task id and not the pipeline's output, with both added to Non-Goals. Pinned by an AST guard (TestInboundOnly) that fails if any module outside the reply path callssend_message, or if the approval store ever reaches the Telegram module — the boundary can still be moved, but not silently.- License: MIT → Apache 2.0. Sole-copyright-holder relicense, effective from this commit forward; applies to the current state of the repository, not a rewrite of historical commits.
docket addis repo-only and detects the codebase from the current directory (or apathargument /--codebase, not re-prompted), suggesting the project name from the codebase directory. GeneratedAGENTS.mduses the runtime-recognizedSession Startup/Red Linessection headings so the post-compaction re-injection actually fires. Memory day math is UTC.- The external OpenClaw daemon is deleted, not abstracted (Phase 19 P19-6/P19-7, decision
D-19). A clean break with no compatibility layer and no migration:
~/.openclaw/,openclaw.json, auth-profiles, the Anti-Corruption Layer module (edges/adapters/openclaw.py), everyopenclawbinary shell-out, and theopenclaw-gateway.servicesystemd unit are all gone. docket's own state root is now~/.docket/(DOCKET_HOME), holding a docket-ownedfleet.json(agent registration, channel bindings, gate/isolation flags, provider endpoints) in place ofopenclaw.json. A pre-existing install's files at the old daemon-relative paths are simply not read again —docket installre-creates a docket-native home from scratch.edges/adapters/system.py'sgateway_active/restart_gatewayare kept as honest, always-inactive/no-op stubs so the ~20 call sites that used to restart the gateway after a mutating command need no individual rewrite. - Approval routing gained a fourth channel. Approvals are answerable via CLI, HTTP, MCP
(a client answering through
docket mcp serve), or Telegram — all four audit-logged with the channel they came from, closing the Telegram gap described above. - The high-risk command classifier is now argument-aware (
core/security.py'sclassify_command, wired intocore/tools.py's chokepoint) — it reads the whole command line, including every segment behind a;,&&,||, or pipe, sogit statusis allowed whilegit push origin productionasks. This resolves, on every path docket itself dispatches, the previously-documented limitation that a binary-path-only allowlist could not distinguish the two; per-argument enforcement had been an explicit, tracked backlog item since Phase 13.
Removed
- The
repovstaskagent-type concept (theAgentTypeenum, the metatypefield, and everytypeecho inlist/info/serve/snapshotoutput and the read-API spec). Every project agent is a repo agent. docket contextsearch/index/snapshot/compresssubcommands and their artifacts (.memory-index.json, per-agentSNAPSHOT.md,memory/archive/). The OpenClaw runtime does semantic memory search itself;contextis now justshow/project.docket workflow— the Lobster YAML surface (core/lobster.py,cli/_workflow.py) — and itswfalias (ROADMAP D-16). docket was linting a dialect it could not fully execute: the validator silently ignored four constructs its own generated template emitted. Runningdocket workflow/wfnow prints a removed-command notice pointing at the eventualdocket pipeline validate/plan/runsurface (core/pipeline.py, Phase 16 W-1/W-2); existing<workspace>/workflows/*.lobster.ymlfiles are left on disk, untouched but no longer read.- The OpenClaw daemon dependency itself (Phase 19). No external
openclawbinary, no daemon process, no daemon-owned exec-approval prompt docket could not see. docket runs the agent turn itself now — see Changed, above, for what replaced each piece of daemon-owned state. docket eval— the specialist-role eval harness (tests/evals/,cli/_eval.py) (CL-J). It was dead code: wired to the deleted OpenClaw daemon (WORKSPACEunder$HOME/.openclaw/workspaces/<role>,openclaw agent --local --json) and skipped silently rather than failing, which is why the drift went unnoticed. Unlikedocket workflow/docket team, there is no replacement command — no CLI entry point runs a single agent turn to repoint the harness at, so it was deleted outright rather than redesigned. Runningdocket eval/docket evalsnow prints a removed-command notice.docket doctorno longer prints an eval-results advisory section, and thedocket eval --tiercarve-out in the tier-name removal rule (model-profiles.spec.md) no longer applies — tier names now have zero surviving user-facing use anywhere.
0.2.0-beta.1 - 2026-07-03
Four feature waves land together in this release, none of which had been cut before now:
Phase 10 (agent pods — provisioning, real dispatch, the opt-in Portfolio Manager), Phase 11
(competitive differentiation, CD-1…CD-8 — runtime-resource isolation, a mechanical verify
gate, governance/HITL, the scheduled/webhook control plane, the versioned read API),
Phase 12 (Consolidation & hardening) — the audit-driven pass that closed gaps the other two
left behind: a single enforced JSON-writer chokepoint, ACL-only OpenClaw shell-outs, no UI
printing from core/edges, retirement of the never-dispatched docket team command, a hard
exit on the deprecated tier-name vocabulary, deletion of an unused role-drift engine, a
4,194→1,702-line split of the CLI's largest module, a re-armed CI drift guard, and a spec/docs
truth pass — and Phase 13 (Close the differentiation gaps) — a second audit-driven pass
that found Phase 11's CD-1/CD-2/CD-3/CD-4 had already built most of what a fresh competitive
read asked for, and closed the five real residual gaps instead of rebuilding: pod resources now
reach the Implementer's actual process environment (not just TOOLS.md prose), verifyCmd is
settable via a public flag, the Tester hop is structurally gated on PASS/FAIL, a built-in
high-risk action-class policy always routes money-movement/secret-access actions to approval,
every approval (any channel) is now audit-logged, and exec-approval gates are on by default
for new installs. Full detail: ROADMAP.md (Phase 10/11/12/13 sections),
internal-docs/architecture-audit.md, and TODO.md's CH-0…CH-13 / FD-0…FD-7 cards.
Section consolidated 2026-07-02, extended 2026-07-03: duplicate
Added/Changedheadings merged, and the Phase 10 (agent pods) + Phase 11 (competitive differentiation, CD-1…CD-8) feature waves — previously missing entirely — backfilled. Two stale Bash-era claims corrected in place (noted inline). Phase 13 (FD-0…FD-7) folded in on 2026-07-03, the day this version was actually tagged.
Added
- Agent pods (Phase 10).
docket add <project>now provisions an isolated pod of project-scoped agents — Lead + Implementer by default;--pod fullor--with reviewer,testerfor the rest — each member with its own workspace and.docket-meta.json.docket pod <project>manages members (add <role> [--count N]/remove <member-id>/ listing). programmer/reviewer/tester are no longer global shared specialists — they are per-pod roles;scope(org vs project) is a first-class metadata axis, anddocket doctorflags leftover pre-pod global role workspaces and backfillsscopeon legacy metadata. - Real pod dispatch.
docket pod <project> delegate "<task>"/queue/dispatchrun a per-pod task queue (one queue per Lead — never shared across pods) through a hop pipeline (Implementer, then optional Reviewer/Tester) with per-hop cost recorded;docket serve --dispatchruns it as a background loop. - Org Portfolio Manager (opt-in).
docket install --portfolioprovisions a singlescope: orgplanning/visibility agent over fleet metadata (never project code). - Pod runtime-resource isolation (CD-1, completed by Phase 13's FD-0) — each pod gets a
disjoint port range and a private scratch dir, injected into the Implementer's real
dispatch subprocess environment (
DOCKET_PORT_BASE,DOCKET_PORT_COUNT,DOCKET_SCRATCH_DIR) — not just documented as TOOLS.md prose the agent has to read and remember to follow — shown bydocket pod <p>, and reclaimed ondocket delete/pod remove. - Git-worktree Implementer isolation for repo pods (CD-5) — the Implementer works in a
dedicated
git worktree/branch, torn down with the pod; documented fallback when the daemon can't target a worktree. - Deterministic pre-merge verification gate (CD-2, completed by Phase 13's FD-1/FD-2) — an
opt-in per-pod
verifyCmd— now settable via a publicdocket pod <project> add --verify "<cmd>"/set-verify <member-id> "<cmd>"(previously only an internal debug command could set it) — runs in the Implementer's workspace before a dispatched task can be marked done; non-zero exit blocks completion and emits a redactedverification_failedtrace event; unset ⇒ visibly logged skip. If the pod has a Tester, its hop is now also gated: the first non-blank line of its report must readPASS/FAIL(case-insensitive);FAILor unparseable output blocks the pipeline (tester_verdict_failed) instead of the Tester's word being taken on faith. - Policy template presets (CD-3) —
templates/policies/*.jsonships curated, human-reviewable policy presets (block-destructive,high-risk-payment,high-risk-deploy,high-risk-credentials,prompt-injection,secret-pii-redact) an operator can inspect/apply viadocket policies show/policies test. - Built-in high-risk action-class policy (Phase 13's FD-3 — distinct from the CD-3 policy
templates above) —
core/security.py'sHIGH_RISK_PATTERNS(money-movement, prod-deploy, secret-access) is wired directly into whatdocket gates enableseeds, visible read-only viadocket gates classes. Money-movement and secret-access are fully enforced today (their bins were never on the curated allowlist to begin with). Prod-deploy's overlap withgit/npmis documented policy, not daemon-enforced — the OpenClaw exec-allowlist gates by binary path only, so excluding those two constantly-used bins wholesale to force enforcement would also block benign use (git status,npm test); per-argument enforcement is a tracked backlog item, not shipped behavior. - Headless approval channel (CD-4, completed by Phase 13's FD-4/FD-5) — token-guarded
GET /approvals+POST /approvals/<token>ondocket serve(local-bind by default) alongsidedocket approve/deny; fail-closed expiry preserved. Every grant/deny, on any channel (CLI, HTTP, Telegram), now writes anaudit_log()entry tagged with the channel — previously only a trace event was recorded. This closed condition is what unblocked gates-on-by-default for new installs (docket install,--no-gatesto opt out) — see Changed, below. - Scheduled & webhook-triggered dispatch (CD-6) — cron-like schedules and a token-guarded
POST /dispatch/<project>endpoint turn theserve --dispatchpoller into an event-driven control plane. - Versioned read-only API (CD-8) —
/status.json,/metrics(Prometheus text format),/healthdocumented and contract-pinned inspecs/data/serve-read-api.spec.md, so external dashboards can consume docket state; mutation stays in the CLI. - Lobster workflow
validate+plan(CD-7) — schema/lint a workflow and render the resolved pipeline docket would hand the daemon, explicitly without executing it. docket eval [--live] [--tier <t>] [--role <r>] [--recommend]— real specialist-role eval harness. Each of the six roles has a structural mode (fast SOUL.md contract check) and a live mode (DOCKET_EVAL_LIVE=1) that sends a golden task viaopenclaw agent --local --jsonand checks the response against acceptance criteria. Results are stored intests/evals/results/YYYY-MM-DD.jsonl;docket eval --recommendanddocket doctorsurface per-role suggestions. Infrastructure failures (quota, auth, timeout) are SKIP — evals stay non-blocking in CI.docket cost --history [id] [--days N] [--json]— daily per-agent cost/turn/token series bucketed by session timestamp, cached in.cost-history.json, with a regression flag for any day costing more than 2× its trailing 3-day average.- Template/prompt versioning —
_create_workspacestampsTEMPLATE_VERSIONinto each agent's.docket-meta.json;docket doctorflags agents on stale templates and points atdocket maintain <id> rebuild. - Declarative provisioning —
docket add --from <agents.yaml|agents.json>provisions a whole fleet from a spec file; idempotent, so a fleet file can be re-applied and kept in git. Example specs inexamples/configs/. docket completions <bash|zsh>— emits a shell completion script (eval "$(docket completions bash)") completing commands, subcommands, and live agent ids. Generated at runtime from the live Typer command registry (Phase 12 CH-8), so it cannot silently desync from the router the way the original hand-maintained literals did.scripts/metrics.py— LOC / command / test / spec counters with--jsonand--check(a CI step fails the build when the README's quoted numbers drift from the tree). Replaces the originalscripts/metrics.sh, which counted the Bashlib/tree deleted at the M6 cutover and had been silently blind ever since (Phase 12 CH-9).NOTICE— trademark/affiliation statement ("Independent project. Not affiliated with or endorsed by OpenClaw or the OpenClaw Foundation"), mirrored at the top of the README.COMPATIBILITY.md— OpenClaw version / schema support matrix, platform requirements, and break-reporting policy; linked from the README's Compatibility section.
Changed
- Exec-approval gates are now on by default for new installs (Phase 13, FD-5) —
docket installapplies conservative exec-approval defaults + a curated allowlist automatically;--no-gatesis the explicit opt-out (previously--gateswas required to opt in). The security-gates spec's own blocking condition — a headless (non-Telegram) approval channel — was already met by CD-4's CLI/HTTP channels; this flip and the FD-4 audit-log parity above are what closed the remaining gap honestly before flipping the default. Docker workspace isolation (docket gates isolate on) remains a separate, still-opt-in layer. - Bash → Python rewrite (M6 cutover). docket is now a Python package (
src/docket/) built on Typer + Rich + Pydantic (plus pydantic-settings and filelock), installed viauv/pip.bin/docketis now a thin Bash launcher that execspython -m docket "$@"; all command logic moved to Python and the entire Bashlib/(commands, helpers, core) was removed. The code is organized in three layers —cli/(Typer commands) →core/(Pydantic models + pure services) →edges/(atomic JSON store + adapters) — withedges/adapters/openclaw.pyas an Anti-Corruption Layer: the single module allowed to know theopenclaw.json/ auth-profiles / provider-config formats. Templates moved fromlib/templates/tosrc/docket/templates/and ship in the wheel. Command aliases and removed-command notices live insrc/docket/__main__.py. - User-facing behavior is unchanged. A golden suite (
tests/golden/run.sh verify-all, 17 cases at the M6 cutover, 16 as of this release — Phase 12 CH-4 retired one command) diffs CLI output byte-for-byte against frozen goldens, and every surviving command and alias still works exactly as before. - Testing/tooling: the Bash unit/lifecycle tests are replaced by a
pytestsuite (tests/python/— 416 tests at cutover, 739 as of this release), the golden parity suite, and the eval harness. New quality gatesruff check+ruff format --check+mypy --strictrun in CI. CI jobs are nowpython,golden,shell, andmacos. -
The remaining shell surface is just the launcher,
install.sh/uninstall.sh,scripts/*.sh, and the golden/eval harnesses (all ShellCheck-linted). -
README repositioned around the ops layer — leads with the one-line positioning ("cost-aware ops layer for OpenClaw agent fleets"), a pain-first Why, a 60-second tour, and a How it relates to OpenClaw differentiation table, with the command reference demoted below the fold. Replaces the prior feature-firehose ordering. The "actively used in real environments" line is replaced with an honest authorship note.
-
sync_session_keynow warns and skips (instead of aborting) whenopenclaw.jsonis absent, so one missing config can't halt a multi-agent provision. - CI lint gate raised from
-S errorto-S warning(with curated excludes for cross-file shared vars and dynamicsource), and theSC2155/SC2188/SC2164/SC2076/SC2010/SC2011/SC2046/SC2115/SC2050warning backlog cleared so the gate stays green. - Test harness hardened — counter increments use
n=$((n + 1))instead of((n++))(which returns non-zero at 0 and would abort aset -eharness); direct unit tests added for theload_model_registryoverlay. (Bash-era entry; the harness is now pytest.) docket doctor --jsonis now a usable health probe — exits non-zero when the report is unhealthy (previously always exited 0), so it can gate monitoring/CI. JSON payload unchanged (healthy/issueswere already present).- docket-owned JSON now has a single writer (Phase 12 CH-1) — every write goes through
edges/store.py's atomic + filelocked + 0600 chokepoint (append-only JSONL logs incore/trace.py/core/audit.pyare the sole, documented exemption). Closes 8+ places that had hand-rolled their own atomic-write logic, several without the filelock or.bakrotation the chokepoint provides. openclawbinary shell-outs now go through the Anti-Corruption Layer (Phase 12 CH-2) —edges/adapters/openclaw.pygained typed wrappers (openclaw_version,agents_add,auth_setup_token,auth_paste_token,onboard);core/utils.pyno longer importssubprocessat all.core/andedges/no longer print (Phase 12 CH-3) —core/provider.pyandsystem.restart_gateway()return typed results (ProviderRegistration,RestartResult); thecli/layer renders them. A newcli/_provider.pyhosts the interactive provider flow that used to live incore/.cli/__init__.pysplit from 4,194 to 1,702 lines (Phase 12 CH-7) —keys/authmoved tocli/_keys.py,contexttocli/_context.py,workflowtocli/_workflow.py,costtocli/_cost.py, and agent add/info/delete/maintain tocli/_agents.py. No behavior change; goldens stayed byte-identical through every extraction stage.
Removed
docket team(Phase 12 CH-4, D-11) — the org-wide manual task queue never had a dispatcher; nothing ever executed a queued task. Running anydocket team <subcommand>now prints a removed-command notice mapping to the real, executing replacement:docket pod <project> delegate/queue/dispatch. Any pre-existing~/.openclaw/workspaces/manager/TASK_LIST.jsonis left on disk, untouched but no longer read. The opt-in Portfolio Manager (docket install --portfolio) covers the cross-pod viewteamused to gesture at.- Tier names as model input (Phase 12 CH-6, D-2 exit) —
economy/standard/premiumare no longer accepted anywhere a model or role value is expected;docket profile <id> premiumanddocket models set premium <model>now fail with an error naming a fullprovider/modelid. A legacyprofiles:key in~/.openclaw/docket-models.jsonauto-migrates toroles:once on load (docket doctorflags a residualprofiles:key ifroles:was already present and the migration left it alone). core/drift.py(Phase 12 CH-5) — the role-success-rate drift engine had exactly one caller (the opt-inserve --dispatchsweep) and fed a Telegram notification that was never implemented. Deleted along with its 3 dedicated config knobs. Unrelated to, and does not affect,docket doctor's config-drift check (meta ↔openclaw.json) or template-version staleness detection, both of which are unchanged.
Security docs
SECURITY.mdexpanded — explicit threat model (what runs with what privileges), the approval-gate model, a homelab-vs-public-VPS guidance box, secret-storage backends as first-class safety features, a "what docket does NOT protect against" list, and a 90-day responsible-disclosure timeline.
Fixed
docket --versionafter install — the installer never copiedVERSIONto the install prefix, so installed users gotdocket (version unknown).VERSIONis now shipped besidelib/and the launcher checks$LIB_DIR/VERSIONin the installed layout.- Brittle installer source-patching —
install.shno longer rewrites theLIB_DIR=line withsed(which broke silently on any whitespace change).bin/docketnow auto-detects the installed (<prefix>/lib/docket-cli) vs repo (<repo>/lib) layout at runtime, and honors aDOCKET_LIB_DIRoverride for packagers/tests. uninstall.shleft files behind — it removedlib/docketwhileinstall.shinstalled tolib/docket-cli. Paths now match; legacylib/docketis also cleaned up, andDOCKET_PREFIXis honored to mirror the installer.docket team upgradein installed layout — read templates from$DOCKET_CLI_ROOT/lib/templates, which doesn't exist once installed; now uses$LIB_DIR/templates.- README-numbers CI drift guard re-armed (Phase 12 CH-9) —
scripts/spec-coverage.shand the originalscripts/metrics.shboth counted the deleted Bashlib/tree and had been silently broken since the M6 cutover, masked by a|| trueon the CI step. The newscripts/metrics.py --checkcounts the real Python tree and Typer registry and now actually fails CI on drift;spec-coverage.shwas deleted outright rather than rewritten, since a faithful rewrite would immediately red-flag documentation gaps that a later fix (CH-11) closed separately. - Documentation and specification drift (Phase 12 CH-0, CH-10, CH-11) — a full-repo audit
found and fixed a batch of stale claims accumulated across Phases 10–11:
docs/commands.mdwas missing sections for 8 real commands (keys,auth,gates,audit,eval,snapshot,completions,context); its alias table had drifted from__main__.py's real_ALIASES/_REMOVEDdicts;docket doctorwas described as read-only despite having--fix;specs/functional/workflow-integration.spec.mddocumented a.yamlextension that was never real (the actual extension is.lobster.yml) and invented return codes the command never used; several docs (AGENT-TEAMS.md,WORKFLOW-GUIDE.md,DOCKET.md) still described the retireddocket teamas live;QUICK-START-DOCKET.mdandDOCKET.mdhad thedocket contextargument order backwards. All corrected; seeinternal-docs/architecture-audit.mdfor the full findings this phase worked from. - Spec/data truth pass for Phase 13's changes (FD-6) —
specs/data/docket-meta.spec.mdandspecs/api/cli-interface.spec.mdupdated for the--verify/set-verifysurface and env-injection behavior; a newspecs/functional/pod-dispatch.spec.mddocuments the dispatch pipeline's hop order, gates, and failure semantics — no spec previously owned that contract;specs/functional/security-gates.spec.mdbrought current for the real approval-channel set, the high-risk action-class policy's honest (partial) enforcement scope, and the gates-on-by-default status.
0.1.0 - 2026-06-10
First tagged release. Establishes the security and write-safety baseline ("a tool I'd run on a real machine") on top of the existing agent-lifecycle CLI.
Added
docket gatescommand (status/enable/disable/isolate) — opt-in exec-approval enforcement on the OpenClaw daemon's native primitives: conservative defaults (security: allowlist,ask: on-miss,askFallback: deny) with a curated safe-bin allowlist, plusdocket install --gates.- Approval routing —
docket gates enablewritesapprovals.exec(mode: session) so an agent's gated prompts reach its own channel, answerable via/approve. - Workspace isolation —
docket gates isolate onapplies the daemon's Docker sandbox (agents.defaults.sandbox), Docker-gated and reversible. - Secret storage backends — pluggable
file(default, 0600 JSON) orkeyring(DOCKET_SECRETS_BACKEND=keyring, libsecret); keyring keeps no plaintext values at rest. docket keys rotateand key-age hygiene (0600secrets.meta.jsonsidecar);docket doctorflags keys past the rotation threshold (DOCKET_KEY_MAX_AGE_DAYS, default 90d).docket doctorsecurity section — exec-approval policy, approval routing, isolation, config-permission hardening, theopenclaw security auditsummary, and the active secret backend.docket --version/-V, aVERSIONfile, and this changelog.- Write-safety primitives
json_atomic_writeandwith_docket_lock(flock).
Changed
- Scoped secret distribution —
docket keyssyncs only the provider key an agent's model needs (not every key to every agent); custom/shared secrets still fan out. Atomic.envwrites that preserve user-authored lines. - All JSON writers (
meta_set,upsert_binding,remove_binding,remove_agent_config,oc_set) now write atomically (validate →.bak→ tmp →os.replace→ 0600) under an exclusiveflock, so a crash or concurrent invocation can't corrupt or lose state. meta_get/oc_getwarn loudly when a state file exists but won't parse, instead of silently returning the default.docket installStep 6 hardensopenclaw.json/secrets.jsonpermissions to600.
Fixed
- Code injection in
keys.sh— secret values are never interpolated into Python source (passed via env/argv/stdin); regression-tested with a hostile value. docket doctoraborted before later checks underset -e/pipefail when no sandbox browser process was running; all sections now run to completion.- Cleared one
shellcheckerror (SC2199, array membership test inmaintain).
Security
- Phase 0 (security hardening) and Phase 1 (write-safety) of the ROADMAP are
complete. Exec-approval enforcement and Docker isolation ship opt-in by design; on-by-default
is deferred pending per-agent headless approval routing (see
specs/functional/security-gates.spec.md).