pi-claude-supervisor 0.6.0 → 0.7.0

package/README.md

@@ -6,90 +6,237 @@
 
 English · [简体中文](README.cn.md)
 
-A policy-gated [Pi](https://pi.dev) extension for supervising a Claude Code worker.
-The MVP keeps Pi in control of lifecycle, state, policy and verification while the
-worker remains an explicitly started child process.
-
-> **Release status:** `v0.5.3` is the released single-Worker recovery baseline. The
-> default manual transport is dependency-free process pipes, not PTY. Automatic
-> supervision uses Claude JSONL or the Supervisor-owned tmux bridge; adopted tmux
-> sessions remain manual-only. Repairable-vs-persistent capabilities,
-> cancellable verification, evidence completeness gates, startup preflight and phase
-> progress reporting. A real edit-capable Claude Code `2.1.270` repair/reacceptance
-> drill passed in an isolated temporary worktree. Real-Claude validation resolves the
-> current executable from `PATH` and accepts Claude Code `2.1.270` or newer. The
-> confirmed product target is unattended local development; see [the autonomy target](docs/autonomy-target.md).
-> Remote push and merge into the main/integration branch remain outside Worker authority
-> and must cross an independent boundary.
->
-> **Autonomy status:** automatic mode continues local editing, testing, bounded repair,
-> acceptance, independent Review and local-commit enforcement without a synchronous human
-> callback. Unresolvable work is parked as a non-publishable candidate; optional outbound
-> notifications do not approve actions.
-
-## Safety boundary
-
-- The extension never starts a worker automatically.
-- Worker commands are launched without a shell.
-- Manual workers retain the small inherited environment unless the caller supplies explicit variables. Automatic Claude workers inherit the supervisor environment unchanged except for `CLAUDECODE`, which must be removed so Claude can intentionally launch nested Claude sessions; credentials, Git/package helpers, custom settings and network configuration are not filtered.
-- The full Claude Code tool surface is available in automatic mode, including agents, background tasks, plugins and MCP. Automatic mode refuses CLI/settings rules that pre-authorize `Bash`, and adds Claude's safe `default` permission mode when none is supplied, so Bash requests remain visible to the Supervisor; it does not remove the Bash tool. The adapter also adds stream-json transport framing and keeps every Worker descendant inside the Supervisor-owned cleanup boundary. `AskUserQuestion` is converted to ordinary text because no human is synchronously present.
-- Local command and permission behavior follows the configured task/runtime policy; known direct remote push/main-integration operations and protected Git metadata remain rejected or parked without requiring a synchronous human response. Nested/custom tools run with the inherited capabilities and are cleaned with the Worker; they are not a second Supervisor permission loop.
-- Automatic mode still admits only the bare `claude`/`claude.exe` command name, resolves and pins an operator-owned executable from the supervisor PATH (or `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE`), and rejects explicit paths or writable/untrusted locations. Manual/custom integrations must provide their own executable and host authority boundary.
-- A worker completion is only a transition to `verifying`; it is not evidence of success.
-- Verification is an independent host command (default: `git diff --check`).
-- Target local development runs unattended after a task starts: the Worker may edit, test, repair and commit locally. Supervisor-managed requests for remote push or merge into `main`/an integration branch remain denied, while the final remote/main boundary must independently protect trusted nested/custom capabilities.
-- The extension never performs merge, deploy, release, or publish at runtime. Remote/main integration and repository releases cross independent protected boundaries.
-- A 4-hour wall-clock and 20-minute no-output watchdog stop a worker by default for long development tasks; embedding callers can set either to `0` to disable.
-- On Linux, the adapter automatically uses a writable cgroup v2 for descendant cleanup, including `setsid()` descendants; it falls back to process-group cleanup when unavailable. Use `cgroupMode: "required"` for a fail-closed integration; required mode is preflighted before Claude starts.
-- Acceptance commands, repository evidence collection and independent Review share an abort signal, so operator stop/shutdown does not wait for a full command or model timeout.
-- Events are append-only JSONL records in `~/.pi/agent/claude-supervisor/events.jsonl`.
-
-## Install
-
-Requires Pi 0.85+ and Node.js 22.19+.
+## What it is
+
+pi-claude-supervisor is a standard [Pi](https://pi.dev) agent extension package that
+supervises Claude Code for unattended local development. Pi owns the task's
+lifecycle, state machine, policy decisions, acceptance checks, and an
+independent Review step; Claude Code is the Worker that does the editing. The
+extension is a single `pi install`: Pi discovers and loads it itself, there is
+no separate build or binary, and there is nothing to configure inside Pi
+beyond environment variables.
+
+There is a hard boundary the Worker can never cross, regardless of its own
+permission settings: it may not push to a remote, merge into `main` or an
+integration branch, open a pull request, or run a remote CLI mutation;
+`.git` metadata writes and destructive rewrites of protected branches are
+denied outright. Everything else — edits, tests, shell commands, local
+commits — follows the policy you configure. The extension itself never
+merges, deploys, releases, or publishes anything at runtime.
+
+How the loop works, once a task starts:
+
+- The Worker works a turn; when it stops (`turn_completed`), Pi's Decision
+  Worker — a persistent Pi session with read-only tools — chooses to
+  continue, redirect, answer a question, verify, stop, or park the task.
+- `verify` runs the acceptance checks (the default `git diff --check`, or the
+  checks from a `--spec` file).
+- An independent Reviewer — a fresh, read-only Pi session — returns pass,
+  revise, or human.
+- `revise` sends the Worker a bounded repair turn (up to `maxRepairRounds`);
+  a pass promotes the work to a `completed` candidate.
+- Unresolvable work is parked as `blocked` (a non-publishable candidate, not
+  a crash); crashes and timeouts become `failed`.
+- Every terminal state emits a candidate notice, in the Pi UI and optionally
+  to a webhook (WeCom or generic JSON, with retries).
+
+## Quick start
+
+Requirements: Pi 0.85+, Node.js 22.19+, Claude Code 2.1.270+ (interactive
+hooks verified on 2.1.273), Linux for the cgroup and tmux features.
+
+Install it like any other Pi extension:
 
 ```text
 pi install npm:pi-claude-supervisor
 ```
 
-For local development:
+That's the whole installation — Pi loads the package's `./src/index.ts`
+extension directly and registers the `/supervise` command. Configuration is
+environment variables only, set before starting Pi (or in
+`~/.config/pi-claude-supervisor/env`):
 
 ```bash
-npm ci --ignore-scripts
-npm run check
-npm run build
+export PI_CLAUDE_SUPERVISOR_MODE=auto
+export PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux
+# Optional: candidate/failure notifications
+export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL='https://example.invalid/webhook'
+export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_FORMAT=generic
 ```
 
-Authenticated real-Claude spikes resolve `claude` from `PATH` by default, so
-installer-managed `latest` links work without a versioned path. Set
-`PI_CLAUDE_SUPERVISOR_REAL_CLAUDE_PATH` only when an explicit executable is needed;
-the spikes require Claude Code `2.1.270` or newer and report the resolved path and version.
-
-## Use
+Then, inside any Pi session:
 
-Set the worker executable if needed, then use explicit commands in Pi:
-
-```bash
-export PI_CLAUDE_SUPERVISOR_WORKER=claude
+```text
+/supervise start implement the requested change
+/supervise adopt-tmux my-tmux-session implement the requested change
 ```
 
+Watch a task with `/supervise status <task-id>` or `/supervise sessions`; for
+a tmux transport, attach directly with the `tmux -S <socket> attach -t
+<session>` command each of these prints. `/supervise stop <task-id>` closes
+the task; on the interactive tmux transport a completed task instead leaves
+the session open for you by default (see below).
+
+## Modes and transports
+
+`PI_CLAUDE_SUPERVISOR_MODE=auto` (or `PI_CLAUDE_SUPERVISOR_AUTOMATION=1`)
+enables automatic supervision — the Decision Worker/Reviewer loop above.
+Without it, `/supervise` still exposes its commands, but a Worker runs
+without that loop.
+
+| Transport | `TRANSPORT` | `TMUX_MODE` | What the Worker runs as | Use it when |
+| --- | --- | --- | --- | --- |
+| Interactive tmux | `tmux` | `interactive` (default) | The real, unmodified Claude Code TUI in a tmux pane, driven by Claude Code hooks | You want to watch or occasionally type into the exact session Claude uses |
+| Headless JSONL | `jsonl` (default in `auto` mode) | – | `claude -p --input-format stream-json`, no terminal | Every permission-relevant command must be visible to the Supervisor |
+| tmux bridge | `tmux` | `bridge` | Claude's stream-json protocol, rendered into a tmux pane | A visible pane with the older structured (pre-hook) transport |
+| Manual (process-pipe) | `process-pipe` (default when `MODE` is unset) | – | The worker's stdin/stdout as plain text | Exposing the commands without automatic supervision |
+
+## Interactive tmux mode (hooks)
+
+`PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux` defaults to running the real,
+unmodified Claude Code TUI in the tmux pane — the same interface you would
+see running `claude` yourself — instead of the structured stream-json
+bridge. You can attach to the printed `attach=...` command at any time and
+watch, or type into the session yourself; Pi reports its events through
+Claude Code's own hooks rather than scraping the screen.
+
+When the extension loads with `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux` in
+interactive mode (the default `TMUX_MODE`), it automatically installs a small
+relay command for the eight Claude Code hook events it uses into
+`~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR/settings.json`) — idempotent,
+and announced once in the Pi UI. Set
+`PI_CLAUDE_SUPERVISOR_AUTO_INSTALL_HOOKS=0` to opt out; `/supervise
+uninstall-hooks` removes the entry, and `/supervise install-hooks` remains
+available to install it by hand. The relay is a ~1ms no-op in any Claude
+session no Supervisor is listening for. An owned `/supervise start` does not
+depend on this at all — it passes its own `--settings` file — but
+`/supervise adopt-tmux` runs inside your normal Claude Code configuration and
+needs the relay installed there.
+
 ```text
-/supervise capabilities
-/supervise start inspect the current repository and report what should be changed
-/supervise start --spec ./task.json
-/supervise sessions
-/supervise recover [--takeover] <task-id>
-/supervise poll
-/supervise poll all
-/supervise send continue with read-only inspection
-/supervise pause
-/supervise resume
-/supervise stop human requested stop
-/supervise verify
+/supervise start <task>
+/supervise adopt-tmux <tmux-session> <task>
 ```
 
-`--spec` accepts a JSON file; checks are always executed with argv (never through
-a shell), for example:
+Pi intervenes when Claude stops a turn (`Stop`; an API/model failure mid-turn
+arrives as `StopFailure` and is treated as an errored turn the Decision
+Worker can retry, and a minute of idle prompt with no stop signal closes the
+turn as a safety net), when Claude is about to show you a real permission
+prompt (only then — every ordinary tool call is otherwise left to your own
+Claude Code permission mode), when Claude asks `AskUserQuestion` (the
+Decision Worker picks an answer and Claude continues with it as ordinary
+text, exactly as in headless mode), and when the session exits. Before that
+prompt, a `PreToolUse` veto point only ever denies a known direct remote
+push/merge/PR or other destructive/protected-branch operation (or forwards an
+`AskUserQuestion`); it never second-guesses a normal edit, read, or local
+command — those reach your own permission mode with no decision from Pi at
+all.
+
+**What this means for the boundary.** Interactive mode deliberately skips the
+headless-mode check that refuses inherited `Bash` pre-authorization or an
+`auto`/`bypassPermissions` mode in your Claude settings: your own
+configuration governs what Claude may do without asking, exactly as when you
+run Claude yourself. Anything your settings already allow never reaches the
+Decision Worker; its judgment applies only where Claude would have asked
+*you*. The hard boundary (remote push/merge/PR, remote CLI mutation, `.git`
+writes, destructive protected-branch rewrites) is enforced by `PreToolUse`
+regardless of permission mode — verified against `auto` mode on Claude Code
+2.1.273 — and is the only guarantee this mode makes beyond your own
+settings. Use headless (`bridge`) mode when every `Bash` call must be visible
+to the Supervisor.
+
+**Adopting an idle session.** `adopt-tmux` types the task into the session
+only when Claude is idle at its prompt; a session caught mid-turn keeps its
+current work and is judged on its next `Stop` instead.
+
+**Human coexistence.** If you type into the attached session, automation
+pauses (`human_takeover`, visible as a warning) until you run `/supervise
+resume-auto <task-id>`; the turn that completed while you were driving is
+replayed to the Decision Worker at that point, so nothing already finished is
+lost.
+
+**Completion hands the session back.** Unlike other transports, a completed
+task by default disconnects Pi from the session instead of closing it, so you
+can keep working in the same window or review what Claude did; `/supervise
+stop <task-id>` closes it explicitly, and a blocked or failed candidate still
+stops the Worker as usual. Set
+`PI_CLAUDE_SUPERVISOR_CLOSE_WORKER_ON_COMPLETION=1` to restore the old
+close-on-completion behavior. The hand-back is clean, not a bare disconnect:
+before reporting the candidate ready, Pi moves every process out of its
+private cgroup into its parent (instead of killing them) and stops the
+guardian process, and the tmux server and pane are left alone — the session
+survives a Pi restart with nothing left owing it. Afterward it is an ordinary
+tmux session with no Supervisor attached; `tmux -S <socket> attach -t
+<session>` reaches it directly, and `/supervise adopt-tmux` can babysit it
+again exactly as it would any other externally created session.
+
+**Cost accounting limits.** The TUI's `Stop` hook has no `total_cost_usd` or
+token `usage` (that only comes from Claude's own `result` stream-json record,
+which the TUI does not emit), so cost tracking in interactive mode only
+counts turns, not dollars; `--max-budget-usd` is also unavailable (Claude
+Code only enforces it under `-p`) and is not passed to an interactive launch.
+Set `autonomy.maxWorkerCostUsd` expecting it to have no effect in interactive
+mode, or use bridge/jsonl mode when a hard cost cap matters.
+
+**Trust dialog.** The very first time Claude Code runs in a given directory
+it shows its own one-time "do you trust this folder" dialog before any hook
+fires. For a session that `/supervise start` launched, the launcher accepts
+it automatically — only when the pane's directory is the task directory. An
+adopted session was started by you, so you already answered it.
+
+## Headless mode (JSONL)
+
+`PI_CLAUDE_SUPERVISOR_TRANSPORT=jsonl` runs Claude as `claude -p
+--input-format stream-json`, with no terminal at all; it is the default
+transport once `PI_CLAUDE_SUPERVISOR_MODE=auto` is set. Every permission
+request Claude makes is answered by the Supervisor — the deny list, routine
+in-cwd edits, and read-only/local-dev shell commands are answered by policy
+alone, and everything else goes to the Decision Worker. `worker_usage`
+events carry full token and cost accounting from Claude's own `result`
+records, so `--max-budget-usd` and the token/cost reporting below both work
+as expected. Use this transport when nothing should ever run without the
+Supervisor being able to see it, or when you don't need to attach.
+
+## Safety boundary
+
+- Always denied, regardless of policy or permission mode: remote push,
+  merge/PR into `main` or an integration branch, other remote CLI mutations,
+  `.git` metadata writes, and destructive rewrites of protected branches
+  (`reset`, `update-ref`, `symbolic-ref`, or a delete/move/force `branch`).
+  Everything else follows the configured policy.
+- `autonomy.permissionAuthority` (`policy` | `hybrid` default |
+  `decision-worker`) controls who answers a permission request — every
+  request in headless mode, and in interactive tmux mode only those Claude
+  would otherwise have shown you as a prompt: `hybrid` answers routine
+  in-cwd edits and local read-only/dev shell commands from policy alone, and
+  sends every ambiguous request to the Decision Worker (a policy denial is
+  always applied directly).
+- **Baseline, not branch.** Any branch, including `main`, may be supervised;
+  the candidate only has to descend from the recorded baseline commit
+  (`merge-base --is-ancestor`). A branch change mid-task is recorded
+  (`worker_branch_changed`), not rejected, and a candidate on a protected
+  branch is reported in its notice (`branch`, `protectedBranch`), not parked.
+  `checkout`/`switch` onto `main` is allowed; only a destructive rewrite of a
+  protected branch name is denied. Claude Code's own "branch first if you're
+  on the default branch" guidance is advisory, not enforced.
+- Worker commands launch without a shell. Automatic mode admits only the bare
+  `claude` command name and pins an operator-owned, non-writable executable
+  path (`PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` to pin one explicitly).
+- On Linux, a cgroup v2 boundary cleans up every descendant, including
+  `setsid()` descendants; `required` mode fails closed instead of falling
+  back.
+- A 4-hour wall-clock deadline and a 20-minute no-output watchdog stop a
+  worker by default; embedding callers can change or disable either
+  (`deadlineMs`, `noOutputTimeoutMs`).
+- Acceptance checks, evidence collection, and the Reviewer share an abort
+  signal, so a stop or shutdown does not wait for a full command or model
+  timeout.
+- Only one cwd lease is held per task; concurrent tasks need separate
+  worktrees.
+
+## Task specs
+
+`--spec file.json` accepts:
 
 ```json
 {
@@ -98,195 +245,201 @@ a shell), for example:
   "constraints": ["Keep the public API compatible"],
   "forbidden": ["Do not publish artifacts"],
   "acceptance": [
-    { "id": "tests", "name": "tests", "command": "npm", "args": ["test"], "required": true }
+    { "id": "tests", "name": "tests", "command": "npm", "args": ["test"], "required": true, "timeoutMs": 120000 }
   ],
   "maxRepairRounds": 3,
   "autonomy": {
     "unattended": true,
     "requireLocalCommit": true,
-    "maxDecisionRetries": 2
+    "maxDecisionRetries": 2,
+    "permissionAuthority": "hybrid",
+    "maxWorkerCostUsd": 20
   }
 }
 ```
 
-The default MVP writes the task to the worker's stdin as plain process-pipe
-text. After running the transport spike for the target CLI, JSONL framing can
-be selected explicitly:
-
-```bash
-export PI_CLAUDE_SUPERVISOR_TRANSPORT=jsonl
-export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode acceptEdits'
-```
-
-This adds Claude Code stream-json flags and frames supervisor messages as JSONL.
-The supervisor allows only one active JSONL request per session: poll until its
-`result` and `waiting` state before sending the next turn. Session resume is not
-yet exposed by the adapter. Multiple independent task sessions can run
-concurrently when they use different canonical working directories or
-worktrees; same-directory starts are rejected even when concurrent, and
-`/supervise sessions` lists the sessions. This is independent-session
-parallelism, not coordinated multi-worker collaboration. A future multi-worker
-milestone will add explicit parent/child task graphs, dependencies, bounded
-scheduling, structured handoffs, aggregate acceptance and graph-aware recovery;
-it will not grant any Worker remote push or main/integration merge authority.
-Unattended local development is the target operating mode; a blocked or failed
-candidate is parked with its evidence rather than made dependent on a human being
-online. Automatic mode preserves Claude Code's normal argument and extension surface:
-its tools, agents, background tasks, plugins, MCP configuration, credentials and network
-access are not replaced with a sandbox or allowlist. `CLAUDECODE` is removed from the
-Worker environment so nested Claude sessions can start, and the Supervisor-owned cgroup
-still cleans every descendant. Automatic mode adds a safe `default` permission mode
-when omitted and rejects Bash preauthorization in the effective CLI/settings roots
-(including an overridden `HOME`); Bash itself remains available through
-Supervisor-visible permission requests. The automatic tmux bridge repeats that
-settings check synchronously immediately before spawning Claude, so a mutation after
-Supervisor preflight fails closed. The adapter also adds stream-json transport framing,
-and its known direct command policy refuses remote push/main integration operations.
-Automatic mode still accepts only the bare direct Claude command name, pins its
-operator-owned resolved executable path, and rejects explicit executable paths or
-writable/untrusted locations. Set `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` when the resolved
-path must be pinned explicitly. Custom tools and nested workers are trusted capabilities,
-so a hard remote/main boundary must remain independently protected outside this process.
-Set `PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT=0` only for a task that intentionally
-produces no local commit candidate, or set `autonomy.requireLocalCommit` in its spec;
-automatic mode still requires a valid Git baseline and non-protected worktree.
-`PI_CLAUDE_SUPERVISOR_UNATTENDED=0` opts a task out of automatic Decision Worker control;
-a required local commit is checked on a non-protected task branch;
-`PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES` bounds transient Decision Worker retries.
-
-The `v0.5.0` automation milestone adds a structured acceptance pipeline:
-multiple argv-based checks, an independent read-only Reviewer, bounded structured
-findings and repair rounds. Legacy text tasks keep the default `git diff --check`.
-The Reviewer only has `read`, `grep`, `find` and `ls`; it cannot edit files or grant
-permissions. Automatic mode requires complete baseline-relative tracked, commit and
-bounded untracked evidence, repairs a live `repairableSession` Worker within a
-bounded budget, enforces a local commit when enabled, and prevents a non-publishable
-candidate from crossing the remote/main boundary. Automatic mode rejects explicit
-`process-pipe` and preflights runtime prerequisites. Invalid output, unavailable
-evidence, duplicate findings, P0/P1 findings and exhausted repair budgets park the
-candidate without waiting for a human; see [the autonomy target](docs/autonomy-target.md).
-The automatic tmux bridge carries Claude stream-json records inside the same live PTY
-as display output using private terminal framing; it does not create an independent
-structured-event sidecar. Automatic tmux accepts only Supervisor-owned sessions,
-while `adopt-tmux` remains manual-only.
-Coordinated multi-worker scheduling is a later milestone; CI uses deterministic fake
-Workers/replay fixtures, and real multi-worker Claude tests remain authenticated
-manual Spikes. Full host-level sandboxing and low-privilege execution for custom
-integrations remain separate hardening work.
-
-Automatic mode persists the Pi Decision Worker session under the configured state
-directory. After an unclean Pi restart, `/supervise sessions` lists recoverable
-tasks; `/supervise recover [--takeover] <task-id>` explicitly restores the Decision Worker
-context and starts a new Claude Worker. It never silently resumes or duplicates
-work. If the old Pi owner is dead, add `--takeover` only after the lease proves
-the old Worker's process group is gone and its cgroup is a real, readable empty
-boundary; missing or unverifiable Worker evidence is refused. The lease also
-persists the generated Worker/cgroup identity, including the cgroup device/inode,
-and rejects a renamed or replaced cgroup. Automatic Workers retain a verified
-empty cgroup until the owning cwd lease is released, covering a normal-exit
-crash between Worker cleanup and lease finalization; release then removes it.
-Automatic lease acquisition records a no-spawn startup marker and the adapter
-persists its generated cgroup/socket plan before creating those resources,
-then records cgroup and server identity in stages before spawn. Recovery
-inspects and cleans a planned empty cgroup/session instead of assuming that
-startup-only means no resource exists. A stale marker is reclaimable only after
-its owner is proven dead because that adapter has not reached spawn. For an automatic tmux lease, takeover additionally requires Supervisor ownership,
-dead tmux-server identity, a gone private tmux session, and a durable
-cleanup-pending transaction plus atomic reservation of the private socket. The
-replacement reuses the old lease record, and the reservation remains until that
-replacement is written. Only then is the guardian-left-empty cgroup removed; a
-fresh Supervisor can reconcile the pending transaction if recovery is
-interrupted. For a persistent manual tmux Worker, use explicit `adopt-tmux`
-instead of takeover.
-Manual embedding integrations may pass credentials through an explicit
-`WorkerStartInput.env`. Automatic mode passes the full supervisor environment to the
-Worker (except `CLAUDECODE`), including provider/remote credentials, credential helpers,
-configuration and proxy settings. Keep the Supervisor's own environment appropriate for
-the task; `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` pins executable identity but is otherwise
-not used to select the Claude binary.
-
-### tmux/PTY transport
-
-For an interactive Claude Code window, opt in to the tmux transport:
-
-```bash
-export PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux
-export PI_CLAUDE_SUPERVISOR_WORKER='claude'
-# Manual tmux currently requires Linux for process identity and cleanup;
-# it may use cgroup mode auto/off.
-# Set PI_CLAUDE_SUPERVISOR_MODE=auto for the Supervisor-owned automatic bridge;
-# automatic tmux additionally requires Linux cgroup v2 and a parent-death guardian.
-# Optional, only when adopting a non-default tmux server:
-# export PI_CLAUDE_SUPERVISOR_TMUX_SOCKET=/path/to/tmux.sock
-```
-
-`/supervise start <task>` starts Claude in a private tmux server and reports a
-literal attach command. Use that command in another terminal to watch or
-manually interact with the same PTY; attaching is optional for unattended local
-development. The adapter sends multi-line input through
-tmux buffers and Enter, never by interpolating the message into a shell command.
-In automatic mode the Supervisor starts a bridge in the pane: it runs Claude's
-stream-json protocol inside the live PTY, contains the bridge and descendants in
-an owned cgroup, fails closed when that containment or the Linux guardian is
-unavailable, renders readable deltas for the attached terminal, and returns
-structured records through private terminal framing on the same PTY. The bridge
-re-reads effective Claude settings in the same process immediately before its
-child `spawn`, so a startup settings mutation fails closed instead of reaching
-an unchecked Claude process. The adapter parses those records from the raw PTY
-pipe, so there is no independent
-JSONL event sidecar. Automatic mode refuses adopted sessions; use JSONL or the owned
-bridge for unattended decisions, repair and protected command enforcement.
-
-A session that you started yourself can be explicitly adopted without replaying
-the task:
-
-```text
-/supervise adopt-tmux <tmux-session-name> <task description>
-```
-
-Adoption checks the session's working directory and pane command, and refuses a
-pane that already has another output pipe. Owned sessions use a generated
-private tmux socket, so preserve the complete `attach=...` command printed by
-`start`. When re-adopting after a Pi restart, set
-`PI_CLAUDE_SUPERVISOR_TMUX_SOCKET` to the socket path from that command before
-running `adopt-tmux`; the session name alone is sufficient only for the default
-server. Adoption does not claim ownership: `/supervise stop` and Pi shutdown
-detach supervision rather than killing the user's tmux session. Use `tmux
-kill-session` yourself when the adopted window should be closed.
-`/supervise takeover <task-id>` disables automatic Decision Worker messages;
-resume them only with `/supervise resume-auto <task-id>`.
-
-PTY screen text is not itself Claude JSONL and must not be treated as structured
-permission evidence; only the Supervisor bridge's private framed records are
-authoritative. TUI decisions follow the configured autonomy policy and are
-recorded; an unresolved task may be parked without requiring a human to remain
-online. A normal terminal Claude process cannot be migrated into tmux, and
-`--resume` is historical recovery rather than live PTY attach. Manual owned tmux
-sessions survive a Pi disconnect and require an explicit `adopt-tmux` after
-restart; automatic owned sessions are terminated by their parent-death guardian
-when the Supervisor disappears. A later `/supervise recover --takeover` may
-reclaim an automatic lease only after the guardian, process, cgroup and private
-tmux-session proofs pass. Use plan/read-only flags for live testing.
+Checks always run with argv, never through a shell. A plain-text task (no
+`--spec`) becomes a `goal` with the default `git diff --check` acceptance
+check (120s timeout) and the env autonomy defaults below.
+
+## Configuration reference
+
+Environment variables (or `~/.config/pi-claude-supervisor/env`), all prefixed
+`PI_CLAUDE_SUPERVISOR_`; see `.env.example` for a template.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `MODE` | unset (manual) | `auto` enables automatic supervision (Decision Worker + Reviewer loop) |
+| `AUTOMATION` | unset | `1` is equivalent to `MODE=auto` |
+| `TRANSPORT` | `jsonl` in auto mode, `process-pipe` otherwise | `jsonl` \| `tmux` \| `process-pipe` (manual only) |
+| `TMUX_MODE` | `interactive` | `interactive` (real TUI via hooks) \| `bridge` (stream-json in a pane) |
+| `AUTO_INSTALL_HOOKS` | `true` | Interactive tmux mode only: automatically install the hook relay into the user's Claude settings on load; `0` opts out |
+| `CLOSE_WORKER_ON_COMPLETION` | `false` | Interactive tmux only: close the Worker/session on completion instead of leaving it open |
+| `CGROUP_MODE` | `auto` | `off` \| `auto` \| `required`; automatic mode always uses `required` on Linux; `required` is rejected for a manual (non-automatic) tmux Worker |
+| `TMUX_SOCKET` | unset (default tmux server) | Socket path for adopting a non-default tmux server |
+| `WORKER` | `claude` | Worker command; may include arguments |
+| `NODE` | unset (resolved from `PATH`) | Explicit `node` executable path, for a Bun-compiled Pi |
+| `TRUSTED_CLAUDE` | unset | Pins the expected resolved Claude executable identity explicitly |
+| `STATE_DIR` | `~/.pi/agent/claude-supervisor` | Supervisor state directory |
+| `CWD_LEASE_DIR` | `<state>/cwd-leases` | Shared cwd-lease registry directory |
+| `WORKER_ENV` | unset | Comma-separated list of env vars to pass through to manual workers |
+| `HUMAN_WEBHOOK_URL` | unset | Outbound candidate/failure notification endpoint |
+| `HUMAN_WEBHOOK_FORMAT` | `generic` | `wecom` \| `generic` |
+| `HUMAN_WEBHOOK_SECRET` | unset | HMAC signing secret; sent as the `x-pi-supervisor-signature` header |
+| `UNATTENDED` | `true` | Task runs without a synchronous human callback |
+| `REQUIRE_LOCAL_COMMIT` | `true` | Require a local commit on the candidate's branch before completion |
+| `MAX_DECISION_RETRIES` | `2` (0–10) | Retries of a Decision Worker call that times out or fails (429/529, network, auth) |
+| `PERMISSION_AUTHORITY` | `hybrid` | `policy` \| `hybrid` \| `decision-worker` |
+| `WORKER_MAX_BUDGET_USD` | unset | Hard cap passed as `--max-budget-usd`; unavailable to interactive tmux |
+| `WORKER_MODEL` | unset (Claude's own default) | `--model` for the Claude Worker |
+| `WORKER_AUTOCOMPACT_TOKENS` | `200000` in automatic mode | Per-turn context bound; `0` keeps Claude's own default |
+| `WORKER_MCP_CONFIG` | unset | Path passed as `--strict-mcp-config --mcp-config`, restricting the Worker's MCP servers |
+| `DECISION_MODEL` | unset (Pi's default) | `provider/model-id` for the Pi Decision Worker, as listed by Pi |
+| `REVIEWER_MODEL` | unset (Pi's default) | `provider/model-id` for the independent Reviewer |
+| `DECISION_COMPACT_TOKENS` | `60000` | Proactively compacts the persistent Decision Worker session past this size; `0` disables it |
+| `PROGRESS_HEARTBEAT_MS` | `60000` | Minimum interval between repeated progress notifications for the same phase |
+| `DECISION_SESSION_RETENTION_DAYS` | `30` | Prunes closed Decision Worker session records older than this; `0` keeps forever |
+| `EVIDENCE_MAX_BYTES` | `1048576` (1 MiB) | Maximum repository evidence bytes collected per task |
+| `EVIDENCE_MAX_UNTRACKED_FILES` | `512` | Maximum untracked files collected as evidence per task |
+| `REVIEW_TIMEOUT_MS` | `600000` (10 min) | Total independent Reviewer budget per round, including one retry on a provider error |
+| `EVENT_LOG_MAX_BYTES` | `67108864` (64 MiB) | Rotates `events.jsonl` at this size; 5 rotated files are kept |
+
+## Recovery, leases and state
+
+After an unclean Pi restart, `/supervise sessions` lists recoverable tasks;
+`/supervise recover [--takeover] <task-id>` restores the Decision Worker
+context and starts a new Claude Worker. It never silently resumes or
+duplicates work. Add `--takeover` only once the lease proves the old
+Worker's process group is gone and its cgroup is a real, readable empty
+boundary (and, for tmux, that the private tmux session is also gone);
+missing or unverifiable evidence is refused rather than reclaimed.
+`/supervise recover` does not persist whether the original task was
+interactive — it derives that from the current `TRANSPORT`/`TMUX_MODE`
+configuration at recovery time, so do not change either between starting a
+task and recovering it.
+
+Every task holds one cwd lease under `CWD_LEASE_DIR`; concurrent tasks need
+separate worktrees. A lease record that cannot be read (corrupt JSON,
+unexpected shape) is quarantined instead of blocking other lookups, and
+`/supervise sessions` lists the current quarantined records so an operator
+can inspect and clean them up.
+
+Events are append-only JSONL in `<STATE_DIR>/events.jsonl`, with
+`worker_output` size-capped and the log rotated past `EVENT_LOG_MAX_BYTES`.
+The Decision Worker session for each task is persisted as its own JSONL file
+under the state directory, pruned by `DECISION_SESSION_RETENTION_DAYS`.
+
+## Notifications
+
+Every terminal state (`completed`, `blocked`, `failed`) emits a candidate
+notice in the Pi UI and, if `HUMAN_WEBHOOK_URL` is set, to a webhook in
+either `wecom` or `generic` JSON form, signed with `HUMAN_WEBHOOK_SECRET`
+when set. A parked candidate that asked a question sends a separate "needs
+you" notice; a human takeover (you typed into the session) only shows an
+in-UI hint, since you are already there. Either notice includes an
+`attach` field with the literal `tmux -S <socket> attach -t <session>`
+command when it concerns a tmux session, and a usage summary
+(`CandidateNotice.usage`: cost, worker turns/tokens, Pi tokens, decision and
+reviewer call counts). Webhook delivery retries transient errors (network,
+429/5xx). Notifications are outbound-only: receiving one does not grant any
+approval, and a webhook cannot push commands back into Pi — use `/supervise
+send`/`approve`/`takeover` for that.
+
+## Token usage and cost controls
+
+Measured on one real unattended review task (29 minutes wall clock):
+
+| Component | Turns/calls | Tokens | Cost |
+| --- | --- | --- | --- |
+| Claude Code Worker | 70 turns | 15.5M cache-read + 370k cache-write + 100k output | $18.46 |
+| Pi Decision Worker | 30 model calls | ~1.0M (91k uncached + 914k cache-read) | $0.04 |
+
+Almost all of the money goes to the Worker, not the Supervisor's own Decision
+Worker or Reviewer calls. In this run the Worker averaged ~220k tokens of
+context per turn because it ran as a single long `-p` session under a
+1M-token window that never compacted; a trivial Claude Code turn costs
+roughly 24k prompt tokens for its system prompt alone, regardless of which
+MCP servers are configured. Of the 30 Decision Worker calls, 28 were
+permission requests, and the Decision Worker overrode the deterministic
+policy 4 times (denying downloads and writes outside the task directory) —
+this is why `hybrid` is the default `permissionAuthority`, not `policy`.
+Replaying those 28 requests through the shipped `isRoutinePermission`
+classifier answers 4 of them locally; that task was dominated by inline
+`node -e` scripts and `$(...)` substitutions, which are never routine. An
+ordinary implementation task is mostly in-cwd `Edit`/`Write`, `npm test` and
+`git status/diff/add/commit`, all of which are routine, so its Decision
+Worker call count drops much further.
+
+Knobs, with their defaults and trade-offs:
+
+- `PERMISSION_AUTHORITY` (`policy` | `hybrid` default | `decision-worker`):
+  `hybrid` answers routine in-cwd file edits and local read-only/dev shell
+  commands from the deterministic policy alone (`isRoutinePermission` in
+  `src/policy.ts`) and still sends every ambiguous request, and every policy
+  denial, to the Decision Worker. This mainly buys latency and a smaller
+  Decision Worker context, not dollars: the 30 calls above already cost
+  $0.04.
+- `WORKER_MODEL` / `--model`: roughly a 5x price difference between Opus- and
+  Sonnet-class models. This is the single largest lever on the actual bill,
+  and it is the operator's choice; the Supervisor does not pick it for you.
+- `WORKER_AUTOCOMPACT_TOKENS` (default 200000 in automatic mode; `0` keeps
+  Claude's own default): bounds context per Worker turn so a long session
+  does not keep accumulating ~220k-token turns. Worth tens of percent, at
+  the cost of some context quality.
+- `WORKER_MAX_BUDGET_USD` / `autonomy.maxWorkerCostUsd`: a hard cap passed to
+  Claude as `--max-budget-usd` and re-checked by the Supervisor against the
+  cumulative Worker `result` cost. It is a cap, not a saving; a task that
+  hits it is parked with its evidence.
+- `WORKER_MCP_CONFIG` (`--strict-mcp-config --mcp-config`): restricts the
+  Worker to only the listed MCP servers. It bounds what the Worker can
+  reach, not the ~24k-token fixed overhead of an ordinary turn.
+- `DECISION_MODEL` / `REVIEWER_MODEL` (`provider/model-id`, for example
+  `anthropic/claude-haiku-4-5-20251001`): the Pi Decision Worker and
+  Reviewer models. Pi-side usage was already a few cents in this run, so a
+  cheaper model here mostly buys latency, not headline savings.
+- `DECISION_COMPACT_TOKENS` (default 60000; `0` disables): proactively
+  compacts the persistent Decision Worker session once its estimated context
+  passes this threshold, and re-sends the startup instructions once on the
+  next prompt after compaction.
+
+The Supervisor records what it spends rather than estimating it after the
+fact: every Worker `result` record becomes a `worker_usage` event, every
+Decision Worker/Reviewer model call becomes a `pi_usage` event, and both
+accumulate into `session.usage` (`SupervisorTokenUsage`). `/supervise status
+<task-id>` prints a `cost=… workerTurns=… workerTokens=… piTokens=…
+decisionCalls=… reviewerCalls=…` summary; progress notifications carry
+`SupervisorProgress.costUsd`/`.piTokens`, and a candidate notification
+carries the same summary through `CandidateNotice.usage`, which the generic
+webhook serialises as a numeric `usage` object and the WeCom format renders
+as two extra lines.
+
+None of this changes what a task actually costs beyond the Worker model and
+budget choice; the Supervisor-side changes here mainly cut Decision Worker
+tokens and latency, which were cents to begin with. For a cost-sensitive
+unattended run, a reasonable starting point is a Sonnet-class `WORKER_MODEL`,
+an explicit `WORKER_MAX_BUDGET_USD` per task, the default `hybrid` permission
+authority, and a Haiku-class `DECISION_MODEL`.
 
 ## Development
 
+Contributing to the extension itself (not required to use it):
+
 ```bash
-npm run typecheck
-npm test
-npm run check:package
-npm run check:docs
-npm run check:automation
-npm run check:workflows
+npm ci --ignore-scripts
+npm run check
 npm run build
+npm run test:pi
+npm run test:install
 ```
 
-See [the engineering plan](docs/engineering-plan.md), [the confirmed autonomy target](docs/autonomy-target.md), [the independent review](docs/independent-review.md),
-[architecture](docs/architecture.md), [testing](docs/testing.md), and [releasing](docs/releasing.md).
+Some tests validate the trusted-executable and protected-branch boundaries
+against the real checkout, so they must run from a non-protected branch and
+from a path that is not group/world-writable.
 
-Pull requests are gated by the aggregated `CI / Quality gate`. Release Please
-creates version PRs from Conventional Commits; after a maintainer merges one,
-`Release` verifies the exact tag commit and publishes the package with npm
-provenance through the protected `npm` environment.
+See [architecture](docs/architecture.md), [testing](docs/testing.md), and
+[releasing](docs/releasing.md) for more detail; `docs/autonomy-target.md`
+records the confirmed unattended-development target this project is built
+around.
 
 ## License