Skip to content

v0.2.0-beta.4

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 06 Oct 21:53
· 4 commits to main since this release

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.

Install

# Homebrew (macOS/Linux)
brew tap yielab/docket-cli https://github.com/yielab/docket
brew install docket-cli

# Or the version-pinned installer, which verifies the tarball's SHA-256 before extracting
curl -fsSL https://raw.githubusercontent.com/yielab/docket/v0.2.0-beta.4/install.sh \
  | DOCKET_VERSION=0.2.0-beta.4 bash

Workspace isolation is opt-in: docket gates isolate on needs bubblewrap (Linux) or a running
Docker. See Workspace isolation.

Verify

Every asset is listed in SHA256SUMS, and the wheel, the sdist, the installer tarball, SHA256SUMS
and the SPDX SBOM carry a GitHub build-provenance attestation:

sha256sum --check SHA256SUMS
gh attestation verify docket-0.2.0b4-py3-none-any.whl -R yielab/docket

docket is beta software. Expect breaking changes between beta releases and verify consequential
outcomes yourself. Cost figures are token-based estimates, not billed spend.

Full changelog: v0.2.0-beta.3...v0.2.0-beta.4