Skip to content

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, so brew install docket-cli produced a docket that died on import typer. The sixteen packages of the runtime closure are now resource blocks (built from sdists; rust is a build dependency for pydantic-core, libyaml for PyYAML), the release lane checks that every pyproject dependency has one, and scripts/update-homebrew-sha.sh rewrites only the asset digest, never a resource's. The formula's own test do block also expected 0.2.0-beta.4 where the package reports its PEP 440 form 0.2.0b4; it now normalises. Found on 2026-10-07, same install.
  • The Homebrew formula downloaded .../download/v/docket-v.tar.gz (404). url interpolated #{version} before version was declared, so every brew install docket-cli since v0.2.0-beta.1 failed at download. The URL now names the version literally, as Homebrew expects, scripts/update-homebrew-sha.sh rewrites 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-cli right after brew tap fails with Refusing to load formula ... from untrusted tap; the README, the quick start and the installer header now show brew trust yielab/docket-cli between 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. console is a silent channel dialect (core.channel.SILENT_DIALECTS); Catalog.delivering() names the enabled channels that reach an operator away from the terminal. docket doctor gains a Notifications: check, counted as an issue once a pod exists (checks.notifications {ok, delivering} in --json); docket serve --dispatch warns once at startup, docket init after the created summary and docket pod <p> dispatch after a flush that found events, all with one text naming docket channels enable desktop and ntfy --set topic=<topic>. On a TTY with a desktop session, init offers Enable 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 desktop and ntfy twice, once through its task and once standalone, because _park_call never 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>, and docket chat lists the options and prompts for one (Enter takes the recommended). docket inbox prints a waiting task's question, its options and the docket chat hint, and a parked task's held action with the docket approve/deny hint (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 desktop channel now fires for a failed task too (on: [needs_you, task.failed]), the subscription ntfy already shipped; a task that fails while you are away is something that needs you. A completed task still notifies nobody by default: docket inbox lists 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 and dispatch --resume-able ones; --force removes the worktree, keeps an unmerged branch and audits it.
  • A second SIGINT/SIGTERM makes docket serve abandon in-flight sweeps: it requests cancellation of each sweep run, exits 130/143, and the task ends cancelled.
  • approve_task grants 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, MCP approvals_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 conversation level carry a question's options and the recommended id, and Telegram /answer <task> <option id> picks one.
  • A run: step can carry env: (refused for PATH, LD_*, PYTHON*, DOCKET_* and credential names; the task coordinates win; values never reach the trace). The anti-tautology and mutation recipes declare their overrides there.
  • docket doctor lists every unjailed MCP server, global and per pod, and, when Docker is the backend, warns if the jail image has no git; config explain shows isolate per server and recipes show --json unjailed_mcp_servers.
  • A harness consult's question.taskId is 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_BACKEND still forces one). With isolation on and no usable backend a turn is refused before any model call, naming both fixes (install bubblewrap, or docket gates isolate off). docket doctor and gates isolate on probe 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/config and config.worktree stay read-only, so the jail cannot plant code the host's next git would run.
  • docket gates network none|open and a pod network setting (none only narrows) cut the jail's network: bwrap drops --share-net, Docker runs --network none. The default stays open. network none with 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 declared isolate: false (docket mcp servers add --no-isolate, audited, shown by doctor; a recipe's kind: mcp-server document may declare it too). code-intel's ast-grep server does, because uvx cannot write its cache in the jail.
  • fetch results pass the pre_input hook like MCP results (fetch.result_blocked / fetch.result_warn), through one shared screening function.
  • verifyCmd, run: steps and an unjailed bash no longer inherit docket's credentials (DOCKET_LLM_API_KEY, every provider-catalog credential name, TELEGRAM_BOT_TOKEN, every stored secret name).
  • docket serve --dispatch sweeps each pod in its own worker (DISPATCH_SWEEP_WORKERS, default 4), so one pod's blocking hop no longer stalls the others. Stopping serve waits for in-flight sweeps.
  • A refused isolation or network posture settles the task dispatch_refused after 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 branch docket/<pod>/<taskId>, created from the codebase HEAD and recorded on the task as worktree {dir, branch, baseCommit}. Evidence baseCommit is that recorded commit, so a task's diffStat no longer counts earlier, unmerged tasks. docket add/init creates no worktree, and the per-member worktree and its worktreeDir/worktreeBranch meta are gone. Finished worktrees stay until the member is removed; the operator merges the branch.
  • MCP tool results pass the pre_input hook as untrusted input before they reach the model: block refuses the result naming the policy and server, redact scrubs it, warn passes it; each hit is audited (mcp_client.tool_result_blocked / _warn).
  • Command steps (run:) receive DOCKET_TASK_ID, DOCKET_BASE_COMMIT and DOCKET_HEAD_COMMIT, taken from the latest successful Implementer hop's evidence.
  • A no_progress stop: a turn ends when AGENT_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-server documents under mcp-servers/ (read/write declared as access:). docket pod <p> apply installs 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-writer and cross-family-review (two pinned models from different providers), and code-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: mutation scopes 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; fetch results 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.

  • consult is a built-in read tool: the model asks a decision-kind question with options and an optional recommendation (operator-v1.1 QuestionV11, schemas under docs/contracts/operator-v1.1/). In a single harness turn it is a question_asked event answered on stdin by questionId with an optionId; under refuse the turn ends blocked with the question on the v1.1 result. In a pod hop it parks the task waiting_input and answer_task re-enters the same role with the answer. maxConsultationsPerTask caps it task-wide.
  • Approval packs: a gated call carries a screened, 500-character-bounded rationale taken from the model's preceding text, and three options (approve_once, approve_task, deny). approve_task pre-grants identical calls within the turn only. docket approve|deny --reason, HTTP reason and a harness content.reason record why, with an actor, 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 through docket pod <p> evidence <task> [--json], GET /tasks/<p>/<id>/evidence and the harness result's task.evidence. All three come from one builder. Usage is null when the endpoint reports zero.
  • Corrections ledger: deny reasons, Reviewer REQUEST-CHANGES texts and declined answers append to <DOCKET_HOME>/corrections/<project>.jsonl, read with docket pod <p> corrections.
  • Escalation metrics: docket_tasks_started_total, docket_questions_total{kind,outcome} and docket_decision_latency_seconds on /metrics, and docket metrics --escalation. They are lifetime-of-current-storage counts, not monotonic totals.
  • Harness files no 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_task does not survive a parked and resumed hop; a single-turn consult's question.taskId is 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.0 stays byte-identical) adds process lifecycle events for bash (process_started/process_exited, with pgid and exitCode or signal); --answers stdin with --answer-timeout for approvals and recipe questions; files on the result (written and edited paths, plus git status in a git workspace); --token-file, --max-tokens, --policy; --recipe NAME|DIR with --verify, reporting the hops in a task block; and approvals on the result, so a denied or timed-out approval is visible without changing status or the exit code. The committed schema is docs/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.py runs 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); requireVerify makes a missing verify command fail a hop instead of advancing; a guardrail_block event carries the action, not the policy id; pod-scoped roles get their own token budget. Process groups for bash are cancellable by docket runs cancel and 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 for serve --dispatch's sweep and a non-interactive dispatch; an interactive TTY still resolves to wait) records the exact call and moves the task to waiting_approval so 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 pipeline input step ({ask: {input: {from: <step>}}}) can instead park a task waiting_input to ask a real question, shaped as an MCP elicitation request/ result; the opt-in intake recipe wires this to a Lead's typed TaskBrief (objective/acceptance/resources/questions, verdict READY/NEEDS-INPUT/REJECT) with a deterministic pre-flight check of named secrets/paths/verify commands before the Implementer ever runs. docket inbox (also GET /inbox, the MCP inbox tool, and Telegram's /status) is a pure, derived view across every pod's tasks and approvals; nothing is pushed anywhere until an operator enables a kind: channel document (docket channels list|show|enable|disable|content|test|add|remove|export) — seven dialects ship, all off except console, each declaring content: minimal|actions|conversation under the same confirmed-and-audited widening shape Phase 33 used for exporter privacy, and every notification is a CloudEvents 1.0 envelope, with webhook signing deliveries per Standard Webhooks. Parked work is answered from docket pod <p> answer, docket chat <task-id>, POST /tasks/<id>/answer, the MCP task_answer tool, or Telegram's new fifth verb /answer <task-id> <text> (still inbound-only, still screened by pre_input) — every one of these resolves through the single core.answers.answer_task function. docket pod <p> explain interruptions forecasts what could pause a task before it runs, and docket pod <p> pregrant <task-id> "<command>" pre-approves an exact, whitespace-normalized command (a rephrased one still asks). Every task view now carries an a2aState alongside docket's own status, mapped onto A2A 1.0.0's TaskState enum, though docket does not itself become an A2A server this phase. Measured on the phase's own --scenario operator-loop oracle: sweepBlockedSeconds fell from roughly 12-13s to under 1s deterministically once park shipped, 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.json records 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: exporter document says what it shares beyond structure: privacy: minimal (the default for every built-in), actions (tool arguments, error text), conversation (prompts, replies, tool results) or full (plus the system prompt), or an exact share: list; contentMaxChars bounds 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 at minimal everywhere 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 records exporter.privacy in the audit log; docket exporters preview <name> shows what a destination would receive from a real local session, offline. list gains SHARES, show a "Leaves this host" block, and every exported session carries docket.privacy. At conversation, 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-in langfuse document), verified live with canaries at three levels; at minimal no canary reached the collector, Langfuse or the local trace. Compared with the pre-release payload: metadata default, an approval's command line and error text no longer leave at minimal. Export pipelines start once per process, so a running docket serve applies a level change after a restart.
  • Traces can go to OpenTelemetry and Langfuse (Phase 32, D-48, ADR 0014). A destination is a kind: exporter document (core/exporter.py): endpoint, auth (bearer/header/basic/ none, credential names only, never values), resource, aliases and which event types to send. Five ship in the wheel under templates/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 stdlib urllib with a retry on 429/502/503/504 that honours Retry-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 by EXPORT_FLUSH_TIMEOUT_S even 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|export is the CLI surface: enable resolves the declared credentials (prompting on a TTY, naming docket keys add <NAME> off one), probes the endpoint, and writes only the minimal override. docket config explain and docket doctor report each exporter; a pod.yaml may name exporters:, which apply and docket recipes show report 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 Docker otel-collector produced 29 gen_ai.chat spans matching docket trace's 29 llm_call lines and 39 execute_tool spans; 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. See observability-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_call trace record carrying model, provider, measured latency and token counts, never a dollar figure. ChatResponse gains model, provider, latency_ms; the trace record gains an optional task_id; the store gets its first owning spec, trace-store.spec.md. core/telemetry.py projects trace records into a neutral span model with ids derived from the session id, never random, and trace_ingest notifies 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 structured tool/path/anyOf predicates rather than free text, and secure-build's and ops-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 --recipe and the new docket recipes list|show print the same summary line. pod.yaml gains an optional description; a recipe name resolves against a directory path, your own ~/.docket/recipes/<name>/, then the shipped library; apply records the pod's configSource after every validated apply, an all-skip one included, so composing recipes and applying the exported .docket/ leaves the record naming the repository. The page docs/recipes.md is generated from the recipes and checked in CI.
  • Skills, in the Agent Skills shape. skills/<name>/SKILL.md (front matter name + description, the body on demand) is discovered from three scopes, nearest wins by name: the repository's .docket/skills/, the pod's own config/skills/ (a recipe's skills/ is applied there and exported back), and ~/.docket/skills/. The system prompt carries a # Skills index of screened descriptions; a new built-in skill tool of kind read returns the body or a file inside the skill's directory through the same chokepoint, deniable per role. secure-build ships security-review, tdd ships test-first, spec-first ships writing-a-spec. docket config explain lists the skills an agent sees.
  • AGENTS.md is read by default. When a pod's projectInstructions is unset and the codebase root holds AGENTS.md, the file every other coding agent reads is composed as the project-instructions section: screened through pre_input as untrusted, capped, reported; an explicit projectInstructions list replaces the default. docket config explain names 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 as docket init --recipe resolves 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 and docket pod <p> export write: pod.yaml, roles/, pipeline.yaml, policies/, plugins/) is the team's configuration of record. docket init discovers 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-apply provisions 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. apply records configSource and configDigest (written by nothing else; pod config set and a pod.yaml settings mapping refuse them), docket pod <p> export defaults to <codebase>/.docket/ like apply, and docket config explain <agent> reports the source, the digest and drift: 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 plan prints it and validate/plan refuse an unknown provider naming the step.
  • One field says what a role may not do. editRights is retired from the role wire format: a stored overlay that still carries it loads and drops it, roles show never writes it, roles list loses the column, and docket validate prints a note: for a file that still declares it. deniedTools (cannot in the short form) is the only capability statement.
  • config explain says where a model goes, and doctor checks the provider catalog. docket config explain <agent> --json carries a provider block (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 doctor names 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, the Retry-After ceiling 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 the add <name> <url> --model <id> [--credential NAME] shortcut) probes <url>/models with 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], remove and export complete the round trip (export -> fresh home -> add -> identical show --json), and docket 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) and headers: adds static headers to every request; Authorization, Content-Type and Accept are 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/ holds anthropic, openai, google, openrouter, ai-gateway, groq, mistral, deepseek, xai, cerebras, together, ollama, lmstudio and local; presets, prices (with pricesAsOf), key-format prefixes, credential names and base URLs are read from the catalog, so docket models preset anthropic|openai|google applies without a prior provider add and a stored key alone readies a built-in hosted provider. A provider absent from the catalog resolves only under DOCKET_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) through TurnResult.retry_after_s; the dispatch backoff is min(max(2s x attempt, Retry-After), DISPATCH_RETRY_MAX_WAIT_S) (default 60 s) and the hop_retry trace event records it.
  • A model provider is a kind: provider document. core/provider.py holds the catalog: built-in documents under templates/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_endpoint reads the catalog and the exact model row's limits. A pre-catalog fleet.json -> providers block is migrated once on first use (a literal apiKey moves into the secret store under <NAME>_API_KEY, audited provider.migrate), and docket validate <file> accepts kind: provider.
  • A policy can call a Python predicate the operator applied, never one the agent wrote. when: {plugin: <name>, with: {...}} runs a @predicate from ~/.docket/plugins/ or the pod's own config/plugins/ -- the only two places ever imported; a file in the codebase is invisible until docket pod <p> apply copies 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 as policy.plugin. docket plugins list [--pod <p>] shows name, scope, file and hash. The public API is docket.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> export now writes short-form YAML (a .md beside each role, kind: and name: on pod.yaml) with a # yaml-language-server: $schema= header and a .schemas/ copy, and applying an export plans every item skip. 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/fail of a verify command -- to fail, stop, a later step or an earlier one; a backward edge needs max, and validate/plan refuse a missing bound or an unreachable step. until: verify with max retries a step until its verify command passes. Every routing decision is a route_taken trace 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} or when: {memberPresent: role} skips a step (step_skipped trace 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 under approvalMode refuse); its exit code, or a single upper-case last output line, is the outcome its on: map reads. plan prints both.
  • Every configuration file can say what it is, and one command validates them all. A role, pipeline, policy or pod.yaml may start with kind: and name:; docket validate [dir|file] checks every document under a directory (default .docket/) and prints file:line field: message (valid: a, b, c; did you mean "b"?), exit 1 on any invalid file. A file without kind: 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), anyOf for OR -- evaluated inside the same chokepoint. The six shipped templates are now short-form YAML; every existing JSON policy keeps loading unchanged. docket policies test takes --arg key=value.
  • A pipeline step reads as "who, what is checked, where it goes". - build: implementer plus verify: true, verdict: [APPROVE, REQUEST-CHANGES], approval: <message> or on: {REQUEST-CHANGES: {goto: build, max: 1}}; the canonical form is unchanged and still what plan prints. The three shipped recipes are written in the short form.
  • A role file carries only what is enforced. cannot: [write, edit, bash], one of verdict/verify/approval, model: cheap|strong, and instructions: <file.md> whose Markdown becomes the role's prose (an optional ## AGENTS section supplies the red lines); editRights is derived from cannot, 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 a pod.yaml of members and non-default settings, never anything global; applying that directory to a fresh pod in a fresh home reproduces the same config explain --json. apply also carries a recipe's policies/*.json into 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/) reads roles/*.yaml, policies/*.json, pipeline.yaml and a three-key pod.yaml (members, settings, pipeline), validates everything before writing anything, is idempotent, and audits once as pod.apply. The three shipped recipes carry a pod.yaml and their README's "Apply it" is that one command.
  • Every resolved value says which scope it came from. docket config explain <agent> --json labels the role, each policy file, each loaded MCP server and each denied tool with scope: built-in | global | pod, and docket doctor names 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,b limits a pod to those catalog servers (unset means all; an unknown or stale name is refused at write and refuses the dispatch naming it), and set deniedTools fetch removes 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 lead archetype carries a hopInstruction (shown by docket roles show lead); a global or pod overlay of lead, or a pipeline step's own instructions, 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.json above the global overlay for that pod alone, and docket policies list|test|validate --pod <p> fold that pod's config/policies/*.json into 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 declared read now reaches a read-only role instead of being dropped with everything else; --tools limits which advertised tools register. Undeclared servers keep the fail-closed write default.
  • A pod's dispatch settings are a typed, validated, writable configuration surface. docket pod <p> config [get|set|unset] <key> [<value>] (with --json on get) covers nine keys — budgetUsd, maxReworkCycles, turnTimeoutS, verifyTimeoutS, approvalMode, allowCommands, pipeline, schedule and projectInstructions — validated at write and audited as pod.config. An invalid stored value now refuses dispatch naming the key, instead of silently falling back to a default, and docket profile --budget writes budgetUsd as a number, not a string.
  • An unattended dispatch can refuse instead of waiting on nobody. Setting a pod's approvalMode to refuse makes 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. allowCommands names 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, a serve --dispatch sweep, a schedule, and a webhook or MCP dispatch alike, not only a manually-passed --file. unset pipeline restores the blueprint default, and docket pipeline plan prints a Source: 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 own instructions field overrides it. Step instructions may reference ${name} variables, resolved from repeatable docket pipeline run --var key=value flags 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, approvalMode and allowCommands — each value tagged with what set it (meta, policy, pin, pod setting, env or default).
  • An operator-owned INSTRUCTIONS.md composes into every agent's prompt and survives regeneration. docket never writes it. docket pod <p> sync [--dry-run] re-renders SOUL.md, AGENTS.md and TOOLS.md from 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 doctor flags pod members that are out of date.
  • A pod can opt an agent into reading its own codebase's project instructions. Setting projectInstructions to one or more relative paths (for example AGENTS.md) composes those files into the prompt right after INSTRUCTIONS.md; each one is screened as untrusted input by the pre_input policy 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 and docket-conversations.json; only terminal records are removed, and live or pending ones are never touched. docket runs prune [--days N] [--dry-run] and docket conversations prune [--days N] [--dry-run] run it on demand.
  • Three shipped recipes — secure-build (implementer plus a security-vetter verdict gate), research-review and ops-approval — ship in templates/recipes/: role, pipeline, an optional policy pack and a README with the exact commands to apply them. Each is validated in CI, and secure-build is proven end to end by a dispatch to done on 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 on jails bash and stdio MCP servers in bwrap (Linux) or Docker, and once on a turn with no backend is still refused. gates status and doctor read off (default). Requirements are documented in docs/SECURITY-SIMPLE.md.
  • Unknown docket gates and docket context subcommands exit 2. gates used to print its usage and exit 0, and context silently fell through to show; both now name the unknown subcommand and exit 2.
  • docket audit verify reports an unchained line as a break. A line without seq/ prev_hash used to be counted as "legacy", skipped, and treated as a chain restart; it now fails verification at that line, like any other break.
  • The serve API version is 3. /status.json (and the MCP status tool) no longer carry a gateway field, /health answers {"status":"ok"}, and the docket_gateway_up metric is gone. The undocumented bare /status route 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|run without --file, POST /dispatch/<p>, the serve --dispatch sweep, schedules and Telegram /delegate now resolve the Lead's blueprint and 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 models no longer claims prices can be overridden in docket-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_BUDGET and an archetype's tokenBudget still work as explicit overrides, and docket maintain check plus each turn's prompt_composed trace event report the effective budget and what set it.

  • A truncated or omitted prompt section is always marked, never silent. An oversized SOUL.md used to be able to push HEARTBEAT.md, AGENTS.md, TOOLS.md and MEMORY.md out of the prompt with nothing to say so; the runtime contract and task-ledger state are now protected ahead of SOUL.md, an oversized section is truncated with a visible marker, and every composition's prompt_composed trace event lists each section's size and whether it was full, truncated or omitted.
  • There is one default model of record. docket-models.json's default is now the only source; the separate, sometimes-diverging fleet.json default is no longer read. A provider's display name derives from --model unless --name is 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.md text stops telling agents to write HEARTBEAT.md directly (private state is read-only on the live path); WORKFLOW_AUTO.md is 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 .git file and its gitdir/commondir, and info/attributes are now read-only, and a missing hooks/ dir or attributes file is created empty first so the jail cannot create it.
  • A jailed git commit failed whenever the operator's identity came from the environment or a non-default HOME, and always under Docker: the jail now receives the operator's git identity (never a credential).
  • No inbox view, /inbox response or channel notification ever carried a parked task's question or brief: the fields existed and nothing filled them.
  • A parked consult whose question lived only in the dispatching process stuck its task in waiting_approval when answered elsewhere; the question is now persisted (0600) and a missing one fails the task consult_question_missing.
  • git_branch_merged read every branch checked out in a worktree as unmerged (it ignored git's + marker).

  • glob and grep no 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 to ta[REDACTED].
  • A task paused on a question is a warning, not an error. docket pod <p> dispatch rendered waiting_input with the error marker; it now renders like waiting_approval (found in the Phase 36 live run).

  • A canonical role file that says kind: role loads as written. load_role_file treated the kind: key as proof of the short form and normalized a canonical document, dropping its deniedTools/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 init counts the members a .docket/ or --recipe added. The closing created with N members line 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-in anthropic/claude-sonnet-4-6 while every other member followed docket 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_model now looks the archetype up in the member's pod registry and an unknown role falls back to the registry's own default. docket pod <p> apply and docket init also print the plan's [add]/[replace]/[skip] actions again; Rich had been reading them as style tags and dropping them.
  • A cd prefix no longer turns an allowed command into an approval. cd, pwd, echo, true, false, test and [ joined the bash allowlist, so cd <worktree> && git status runs like git status; an unattended implementer hop used to time out three times on exactly that shape and fail. echo with an output redirect still asks, and export/source/. still ask. docket policies test pre_tool_call now evaluates through the live gate's own function, so it can no longer report allow for 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.json validates as JSON Schema. Its nested $refs pointed at definitions the document did not contain, so a standard validator failed on #/definitions/HarnessResult. The contract stays 1.0.0; no field changed.
  • The HTTP control plane sends Cache-Control: no-store, as its spec always said; a bare POST /approvals, /tasks or /dispatch is authenticated before it is answered 400; and a request body over 1 MiB is refused 413 without being read.
  • Resolving an approval the other way answers 409, not 404. Denying an approval that was already granted (or the reverse) raised the same error as an unknown token, so POST /approvals/<token> said the token did not exist. It now answers 409 naming 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> --json returns 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, policies and maintain reject an unrecognised --flag with exit 2 instead of silently ignoring it.
  • POST /pods and docket init --from validate the project id. A project id such as ../../x used to provision workspaces and fleet registrations outside DOCKET_HOME/workspaces. core/provisioning.py::validate_project_id (lowercase alphanumeric segments joined by single hyphens, at most 64 characters) now runs first in provision_pod; the HTTP routes answer 400 and 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 stay waiting_approval.
  • docket maintain <id> rebuild no longer deletes memory/*.md, and refuses a pod member with exit 1 instead of overwriting its role prompt, TOOLS.md and HEARTBEAT.md with the legacy flat-agent templates.
  • A verifyCmd that 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 only http or tack as channel. A Bearer holder used to be able to record a decision as cli, mcp, telegram or even timeout, forging another surface's provenance in the hash-chained audit log and in docket_approvals_total.
  • docket list --json and docket info --json emit budgetUsd as a number or null (they emitted the stored string, or ""), and docket snapshot emits lastActivity: "never", the same sentinel /status.json uses.
  • docket doctor's budget check and docket cost's high-cost warning can fire. Both compared recorded spend, which DocketDriver always 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 action used to make every call on that hook evaluate to allow; 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 and docket policies test. docket policies validate now compiles every regex instead of accepting a pattern it never checks, docket policies test pre_tool_call takes --tool <name> so a non-bash tool is not misclassified against the command allowlist, and docket doctor reports a broken policy file as an error.
  • docket doctor reports a broken schedule, model-policy entry or overlay role by name instead of silently skipping it, and serve logs 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), and unset removes it.
  • docket delete removes a pod member's merged branch and its provisioning lock directory. A merged docket/<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 now 0700.
  • 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 running with no process behind it and no way to resume; it now ends that task failed with the refusal as its reason, and --resume picks 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> and docket metrics already look for one.

Removed

  • fleet.json's security.isolationEnabled field and core.fleet.get_isolation_mode(); security.isolationMode is 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, completion and policy are unknown commands. Use info, delete, wire, keys, logs, cost, doctor, gates, snapshot, completions and policies.
  • Removed-command notices: auth, team, workflow/wf, eval/evals, model, tier, billing, credits, monitor/mon, memory/mem, smart, ai, mode, terminal/term and the top-level reset, repair, fix, cleanup and clean no longer print a notice; they are plain unknown commands.
  • Flags and subcommands: the hidden --debug flag and hidden _json command; docket gates enable/disable and gates ... --force; docket init --gates/--no-gates and init --path (use --codebase); docket profile <id> policy (use default); docket models ls (use list); the trailing count in docket pod <p> add <role> <N> (use --count/-n); docket maintain --distill-first (distilling first is the default; --no-distill-first remains); --json in place of docket audit's count argument (the --json flag is unchanged); programmer as a pod role alias for implementer (programmer stays a role-policy key for docket models set).
  • Approval-routing posture: the approvalRoutingState/approvalRoutingMode flag that nothing on the live path read, and the "Approval routing" line in docket gates status. The tool-call gate is always on; docket gates manages only isolation (status, isolate, classes).
  • Migrations of old files: a defaults.model or providers block in fleet.json, a profiles: key in docket-models.json, the old Anthropic model-id aliases (claude-3.x to 4.x), and an exporter's payload/payloadMaxChars keys are no longer read or converted.
  • docket doctor checks: stale model names, the profiles: key, a stray workspace .env, leftover global specialist workspaces, metadata backfill, and quarantining a model-written IDENTITY.md/BOOTSTRAP.md into .docket-archive/. doctor --json drops the fzf, approvalRouting, routingMode, modelConfig and modelRegistry keys. The doctor footer now points at docket maintain [id] check instead of the removed docket repair.
  • The gateway field in docket snapshot, /status.json and the MCP status tool, which always read inactive.
  • fzf: the agent picker is the numbered one; fzf was never invoked and is no longer an optional Homebrew dependency.
  • SITES_DIR and DOCKET_LOG_DIR: docket init no longer creates ~/Sites or /tmp/docket; nothing wrote there.
  • docket install in the install script and Homebrew caveats: there is no such command; first-time setup is docket init.
  • docket auth is gone. Store a key with docket keys add <NAME>; register an endpoint with docket models provider add. docket keys setup walks the provider catalog instead of a fixed five-provider list.
  • docket no longer writes an API key into every workspace's .env file. Stored keys are resolved only where they are read; keys add under the keyring backend either stores through secret-tool or 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 run and docket harness status — a non-interactive entry point that runs one agent for one turn, to completion, in a workspace and DOCKET_HOME the 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 at docs/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 at tests/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::subscribe hands 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_unavailable result 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 bash command. docket runs cancel terminalizes 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/disable help text now says what the commands do. They record an approval-routing posture that docket gates status and docket doctor report; nothing on the live path reads it, and every ask verdict 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> sessions no longer says sessions are never compacted. They compact on the turn path once history exceeds the role budget.
  • docket pod <project> dispatch and docket pipeline run exit 1 when a task fails. The exit status now matches the run record: a dispatch whose run ends failed exits 1, so docket pod x dispatch && ... no longer continues past a failed task. blocked and waiting_approval are 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 normalized 0.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> and docket models preset passed 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 (for delegate, 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 local preset's note names the real command, docket models provider add <name> <base-url>; it omitted add, and its bracketed placeholders were erased on screen.

Removed

  • The security.gatesEnabled key in fleet.json is no longer read or written. Nothing had ever read it. An existing fleet.json that carries the key still loads.

Notes

  • docket harness status on 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.md and ROADMAP.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/ and docs/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 curated MEMORY.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 doctor now 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 (stdlib urllib) — 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), with pre_input/pre_tool_call/pre_output policy 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 new DocketDriver (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 bash tool gained an opt-in sandbox (docker or bwrap backend, 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 namespaced mcp__<server>__<tool> so a remote server cannot shadow bash. docket mcp servers add/list/remove (P19-13) makes configuring one just data, not code.
  • fetch tool (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 (bash can 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 no write/edit/bash to 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, /delegate through 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, tagged channel="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 a docket serve restart 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 only pydantic and filelock. Deliberately not a hosted runtime — no multi-tenancy, external-caller auth, queues, or streaming; the embedding product owns its own serving layer.
  • agentic-product pod 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_message has exactly one call site, the reply inside poll_once, and core/approval.py holds no reference to the module), and a setup snippet using docket serve when the poll loop only starts under --telegram. Corrected across README.md, docs/commands.md and docs/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.md now states the inbound-only property as a requirement rather than leaving it implicit, plus that /delegate answers 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 calls send_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 add is repo-only and detects the codebase from the current directory (or a path argument / --codebase, not re-prompted), suggesting the project name from the codebase directory. Generated AGENTS.md uses the runtime-recognized Session Startup / Red Lines section 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), every openclaw binary shell-out, and the openclaw-gateway.service systemd unit are all gone. docket's own state root is now ~/.docket/ (DOCKET_HOME), holding a docket-owned fleet.json (agent registration, channel bindings, gate/isolation flags, provider endpoints) in place of openclaw.json. A pre-existing install's files at the old daemon-relative paths are simply not read again — docket install re-creates a docket-native home from scratch. edges/adapters/system.py's gateway_active/restart_gateway are 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's classify_command, wired into core/tools.py's chokepoint) — it reads the whole command line, including every segment behind a ;, &&, ||, or pipe, so git status is allowed while git push origin production asks. 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 repo vs task agent-type concept (the AgentType enum, the meta type field, and every type echo in list/info/serve/snapshot output and the read-API spec). Every project agent is a repo agent.
  • docket context search / index / snapshot / compress subcommands and their artifacts (.memory-index.json, per-agent SNAPSHOT.md, memory/archive/). The OpenClaw runtime does semantic memory search itself; context is now just show / project.
  • docket workflow — the Lobster YAML surface (core/lobster.py, cli/_workflow.py) — and its wf alias (ROADMAP D-16). docket was linting a dialect it could not fully execute: the validator silently ignored four constructs its own generated template emitted. Running docket workflow/wf now prints a removed-command notice pointing at the eventual docket pipeline validate/plan/run surface (core/pipeline.py, Phase 16 W-1/W-2); existing <workspace>/workflows/*.lobster.yml files are left on disk, untouched but no longer read.
  • The OpenClaw daemon dependency itself (Phase 19). No external openclaw binary, 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 (WORKSPACE under $HOME/.openclaw/workspaces/<role>, openclaw agent --local --json) and skipped silently rather than failing, which is why the drift went unnoticed. Unlike docket 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. Running docket eval/docket evals now prints a removed-command notice. docket doctor no longer prints an eval-results advisory section, and the docket eval --tier carve-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/Changed headings 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 full or --with reviewer,tester for 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, and docket doctor flags leftover pre-pod global role workspaces and backfills scope on legacy metadata.
  • Real pod dispatch. docket pod <project> delegate "<task>" / queue / dispatch run 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 --dispatch runs it as a background loop.
  • Org Portfolio Manager (opt-in). docket install --portfolio provisions a single scope: org planning/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 by docket pod <p>, and reclaimed on docket 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 public docket 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 redacted verification_failed trace 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 read PASS/FAIL (case-insensitive); FAIL or 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/*.json ships 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 via docket 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's HIGH_RISK_PATTERNS (money-movement, prod-deploy, secret-access) is wired directly into what docket gates enable seeds, visible read-only via docket 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 with git/npm is 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> on docket serve (local-bind by default) alongside docket approve/deny; fail-closed expiry preserved. Every grant/deny, on any channel (CLI, HTTP, Telegram), now writes an audit_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-gates to opt out) — see Changed, below.
  • Scheduled & webhook-triggered dispatch (CD-6) — cron-like schedules and a token-guarded POST /dispatch/<project> endpoint turn the serve --dispatch poller into an event-driven control plane.
  • Versioned read-only API (CD-8) — /status.json, /metrics (Prometheus text format), /health documented and contract-pinned in specs/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 via openclaw agent --local --json and checks the response against acceptance criteria. Results are stored in tests/evals/results/YYYY-MM-DD.jsonl; docket eval --recommend and docket doctor surface 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_workspace stamps TEMPLATE_VERSION into each agent's .docket-meta.json; docket doctor flags agents on stale templates and points at docket 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 in examples/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 --json and --check (a CI step fails the build when the README's quoted numbers drift from the tree). Replaces the original scripts/metrics.sh, which counted the Bash lib/ 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 install applies conservative exec-approval defaults + a curated allowlist automatically; --no-gates is the explicit opt-out (previously --gates was 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 via uv/pip. bin/docket is now a thin Bash launcher that execs python -m docket "$@"; all command logic moved to Python and the entire Bash lib/ (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) — with edges/adapters/openclaw.py as an Anti-Corruption Layer: the single module allowed to know the openclaw.json / auth-profiles / provider-config formats. Templates moved from lib/templates/ to src/docket/templates/ and ship in the wheel. Command aliases and removed-command notices live in src/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 pytest suite (tests/python/ — 416 tests at cutover, 739 as of this release), the golden parity suite, and the eval harness. New quality gates ruff check + ruff format --check + mypy --strict run in CI. CI jobs are now python, golden, shell, and macos.
  • 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_key now warns and skips (instead of aborting) when openclaw.json is absent, so one missing config can't halt a multi-agent provision.

  • CI lint gate raised from -S error to -S warning (with curated excludes for cross-file shared vars and dynamic source), and the SC2155/SC2188/SC2164/SC2076/ SC2010/SC2011/SC2046/SC2115/SC2050 warning 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 a set -e harness); direct unit tests added for the load_model_registry overlay. (Bash-era entry; the harness is now pytest.)
  • docket doctor --json is 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/issues were 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 in core/trace.py/core/audit.py are the sole, documented exemption). Closes 8+ places that had hand-rolled their own atomic-write logic, several without the filelock or .bak rotation the chokepoint provides.
  • openclaw binary shell-outs now go through the Anti-Corruption Layer (Phase 12 CH-2) — edges/adapters/openclaw.py gained typed wrappers (openclaw_version, agents_add, auth_setup_token, auth_paste_token, onboard); core/utils.py no longer imports subprocess at all.
  • core/ and edges/ no longer print (Phase 12 CH-3) — core/provider.py and system.restart_gateway() return typed results (ProviderRegistration, RestartResult); the cli/ layer renders them. A new cli/_provider.py hosts the interactive provider flow that used to live in core/.
  • cli/__init__.py split from 4,194 to 1,702 lines (Phase 12 CH-7) — keys/auth moved to cli/_keys.py, context to cli/_context.py, workflow to cli/_workflow.py, cost to cli/_cost.py, and agent add/info/delete/maintain to cli/_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 any docket 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.json is left on disk, untouched but no longer read. The opt-in Portfolio Manager (docket install --portfolio) covers the cross-pod view team used to gesture at.
  • Tier names as model input (Phase 12 CH-6, D-2 exit) — economy/standard/premium are no longer accepted anywhere a model or role value is expected; docket profile <id> premium and docket models set premium <model> now fail with an error naming a full provider/model id. A legacy profiles: key in ~/.openclaw/docket-models.json auto-migrates to roles: once on load (docket doctor flags a residual profiles: key if roles: 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-in serve --dispatch sweep) 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.md expanded — 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 --version after install — the installer never copied VERSION to the install prefix, so installed users got docket (version unknown). VERSION is now shipped beside lib/ and the launcher checks $LIB_DIR/VERSION in the installed layout.
  • Brittle installer source-patching — install.sh no longer rewrites the LIB_DIR= line with sed (which broke silently on any whitespace change). bin/docket now auto-detects the installed (<prefix>/lib/docket-cli) vs repo (<repo>/lib) layout at runtime, and honors a DOCKET_LIB_DIR override for packagers/tests.
  • uninstall.sh left files behind — it removed lib/docket while install.sh installed to lib/docket-cli. Paths now match; legacy lib/docket is also cleaned up, and DOCKET_PREFIX is honored to mirror the installer.
  • docket team upgrade in 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.sh and the original scripts/metrics.sh both counted the deleted Bash lib/ tree and had been silently broken since the M6 cutover, masked by a || true on the CI step. The new scripts/metrics.py --check counts the real Python tree and Typer registry and now actually fails CI on drift; spec-coverage.sh was 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.md was 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/_REMOVED dicts; docket doctor was described as read-only despite having --fix; specs/functional/workflow-integration.spec.md documented a .yaml extension 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 retired docket team as live; QUICK-START-DOCKET.md and DOCKET.md had the docket context argument order backwards. All corrected; see internal-docs/architecture-audit.md for the full findings this phase worked from.
  • Spec/data truth pass for Phase 13's changes (FD-6) — specs/data/docket-meta.spec.md and specs/api/cli-interface.spec.md updated for the --verify/set-verify surface and env-injection behavior; a new specs/functional/pod-dispatch.spec.md documents the dispatch pipeline's hop order, gates, and failure semantics — no spec previously owned that contract; specs/functional/security-gates.spec.md brought 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 gates command (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, plus docket install --gates.
  • Approval routing — docket gates enable writes approvals.exec (mode: session) so an agent's gated prompts reach its own channel, answerable via /approve.
  • Workspace isolation — docket gates isolate on applies the daemon's Docker sandbox (agents.defaults.sandbox), Docker-gated and reversible.
  • Secret storage backends — pluggable file (default, 0600 JSON) or keyring (DOCKET_SECRETS_BACKEND=keyring, libsecret); keyring keeps no plaintext values at rest.
  • docket keys rotate and key-age hygiene (0600 secrets.meta.json sidecar); docket doctor flags keys past the rotation threshold (DOCKET_KEY_MAX_AGE_DAYS, default 90d).
  • docket doctor security section — exec-approval policy, approval routing, isolation, config-permission hardening, the openclaw security audit summary, and the active secret backend.
  • docket --version / -V, a VERSION file, and this changelog.
  • Write-safety primitives json_atomic_write and with_docket_lock (flock).

Changed

  • Scoped secret distribution — docket keys syncs only the provider key an agent's model needs (not every key to every agent); custom/shared secrets still fan out. Atomic .env writes 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 exclusive flock, so a crash or concurrent invocation can't corrupt or lose state.
  • meta_get / oc_get warn loudly when a state file exists but won't parse, instead of silently returning the default.
  • docket install Step 6 hardens openclaw.json / secrets.json permissions to 600.

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 doctor aborted before later checks under set -e/pipefail when no sandbox browser process was running; all sections now run to completion.
  • Cleared one shellcheck error (SC2199, array membership test in maintain).

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).