Skip to content

Releases

v0.2.0-beta.4

v0.2.0-beta.4 Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 06 Oct 21:53

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
      ...
Read more

v0.2.0-beta.3

v0.2.0-beta.3 Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 18 Sep 14:57

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

Install

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

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

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.0b3-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.2...v0.2.0-beta.3

v0.2.0-beta.2

v0.2.0-beta.2 Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 07 Sep 23:32

Release v0.2.0-beta.2. See CHANGELOG.md for details.

v0.2.0-beta.1

v0.2.0-beta.1 Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 03 Jul 13:08

Release v0.2.0-beta.1. See CHANGELOG.md for details.

v0.1.0 (beta)

v0.1.0 (beta) Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 18 Jun 19:37

⚠️ Beta / early-stage release — use with care

docket v0.1.0 is beta software under active development. It has not reached a stable
release. Every feature is implemented and covered by the automated suite (pytest + golden
parity + ruff/mypy --strict), but passing automated tests is not the same as being
production-ready
— most features have not yet had hands-on QA against real fleets, varied
OpenClaw versions, or messy real-world edge cases.

Risks to understand before you run it:

  • docket manages autonomous agents that can execute commands. Enforced tool-approval gates,
    Docker isolation, and audit logging are opt-in (docket gates enable) — off by default.
    Read SECURITY.md and prefer a
    trusted/sandboxed host over a public VPS.
  • No cost figure docket prints is your provider's invoice. Even "recorded spend" is an
    accounting calculation derived from token counts and rates; it will not match your bill
    exactly. Reconcile against your provider's billing dashboard before trusting any number.
  • Expect rough edges, breaking changes between versions, and occasional gaps between docs and
    behavior. Verify anything important yourself before relying on it.

See CHANGELOG.md for details and the
README for per-feature status.