# pi-docket v0.8.0 A trust-boundary release: every worker is human-started, Worker Kinds describe authority instead of hidden spend, and each launch resolves model, thinking, context, and workspace visibly before work begins. Approved output now survives the worker that produced it, and tmux sits behind a boundary narrow enough that an operator layout can never break a worker. ## Highlights ### Human-started workers only Workers no longer receive `docket_spawn_child`. `can_spawn` is ignored with a migration warning, `worker.maxSpawnDepth` has no effect, and persisted workers are independent lanes. Listing and respawn are flat; deleting or pruning one worker never cascades to another. Parallel work remains supported. Start each worker explicitly with `/docket spawn`, or approve an immutable Worker Deliverable and choose Use → Worker for one reviewed, human-confirmed handoff. ### Intent-only Worker Kinds Worker Kinds now state task authority and output guidance: read-only posture, plan gate, decision rights, soft limits, and focused instructions. Workspace derives from intent: writable workers use isolated workspaces; read-only workers share the parent directory unless `--worktree` is explicit. Legacy `model`, `thinking`, `parent_seed`, `default_worktree`, and `layout` fields remain readable through the next major release. Docket warns when they contribute. New kinds should omit them. ### Explicit, validated execution `/docket spawn` now accepts: ```text /docket spawn --model --thinking [--seed|--fresh] [--as ] [--worktree] [--] ``` Model references must exactly match an available Pi `provider/model`; model ids may contain additional slashes. Thinking supports `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Invalid execution aborts before worker filesystem or tmux work. Bare spawn inherits current parent model/thinking. Interactive launches confirm changed spend or contributing legacy defaults; noninteractive launches never wait for UI. Launch details, status, heartbeat, and respawn preserve canonical model plus effective thinking. ### Immutable reviewed handoffs Worker output is frozen as a versioned Worker Deliverable before `ready`. Verdict, Report, diff/Hunk, promotion, and approval bind to that exact version. Approval alone changes no context and starts no work. Use → Parent queues the approved bytes for the next human prompt. Use → Worker starts one fresh worker with exact `source-deliverable.md` input and approving-decision provenance, after confirmation and a final approval check. ### Durable deliverables `/docket save` writes an immutable record to `~/.pi/agent/docket/deliverables//v.json` instead of assembling a mutable bundle. Each record keeps the exact body bytes, structured outcome, evidence, recommendations, artifact refs, an optional frozen change set, ordered generation-bound review notes, approval, and inherited handoff provenance. A worker source is accepted only when its current Worker Deliverable holds an exact terminal approval, so approval is never widened from one generation to another. Writes serialize through a per-deliverable lock and an atomic no-replace version claim: a claimed or corrupt version is never overwritten, and saving the same worker generation twice is idempotent. Each record carries a `schemaVersion` read before structural validation. Older versions run a registered upgrade chain; a record this build cannot load stays visible in `/docket list` as `deliverable:unreadable` with its reason and path, keeps its bytes, and refuses to load — rather than silently disappearing while still holding its slot. Existing bundles remain readable through the compatibility path. ### tmux behind a narrow core boundary Core creates one ordinary window per worker in one shared session and persists the stable window **and pane** IDs. Tell, multiline paste, peek, dead-pane probing, and harvesting target the recorded pane first, so a companion-created pane can never redirect input or evidence capture. Split-event layouts, `status-right` rendering, `pipe-pane` terminal capture, and `pane.log` leave core. One exclusive `registerTmuxAdapter` seam lets a companion own operator layouts; Docket dispatches it after IDs are persisted and never awaits it, so a slow or failing adapter cannot delay or roll back a launch. ### Review and navigation fixes - Arrow keys work in every Docket overlay. Raw key sequences were lowercased before lookup, so `↑`/`↓`, Home/End, and PgUp/PgDn never resolved and only the `j`/`k` aliases beside them in the footer worked. - A verdict card cannot resolve in the wrong family. A plan-gated worker can answer its own `docket_wait` and publish while you are still reading the card; answering it then reached a finished worker, demoting it out of `ready`, and `accept` could record an approval of a Deliverable nobody reviewed. Docket now sends nothing and reopens the current state. - Staleness measures liveness, not progress. Statuses carry `heartbeatAt`, so a worker reasoning through one long turn is no longer shown as `stale`. - The end-of-turn protocol reminder is queued as a follow-up instead of failing with `Agent is already processing` when a parent message lands at the same moment. - `/docket kinds` groups kinds by source with one block each: name and authority as the heading, description, decision rights, and migration warnings under it. ## Breaking changes and migration - Replace autonomous child dispatch with explicit `/docket spawn` or approved Use → Worker. - Remove `can_spawn` from kind files; it is ignored immediately. - Remove `worker.maxSpawnDepth`; old JSON keys are harmless. - Move model/thinking choices to spawn flags. - Move persistent parent seeding to `worker.parentSeedPolicy`, or use `--seed` per launch. - Remove `default_worktree` from new kinds and rely on authority-derived workspace. - `/docket save` takes `--from >`. The `--once`, `--summarize`, `--model`, and `--max-output` flags are gone; saving no longer selects an artifact pool or calls a model. - `bundleArtifacts`, `checkpointArtifacts`, `consumedRetentionDays`, and `summarizer.*` are diagnosed once and ignored. - `worker.tmuxStatusLine`, `worker.captureTerminal`, and kind `layout` declarations are diagnosed once and ignored; operator layouts move to a tmux adapter companion. Legacy hierarchy fields in existing `status.json` remain readable and safe to delete. Existing bundle files stay listable, loadable, and deletable. No storage migration runs and no stored record is rewritten. ## Upgrade ```bash npm install -g @roodriigoooo/pi-docket@0.8.0 ``` Publishing is handled by the `Release` GitHub Actions workflow. It verifies `package.json` matches `v0.8.0`, publishes to npm with provenance, packs the npm artifact, and creates the GitHub Release from this file.