pi-claude-supervisor 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented here.
 
+## [0.9.2](https://github.com/btnalit/pi-claude-supervisor/compare/v0.9.1...v0.9.2) (2026-09-24)
+
+
+### Bug Fixes
+
+* **supervisor:** finish stop and startup races; add gated live Decision spike ([#67](https://github.com/btnalit/pi-claude-supervisor/issues/67)) ([648b269](https://github.com/btnalit/pi-claude-supervisor/commit/648b269f185fbeb5ab39fe22ce855cc8d4342747))
+* **supervisor:** stability fixes found by end-to-end runs with a real Decision Worker ([#65](https://github.com/btnalit/pi-claude-supervisor/issues/65)) ([cd0b8ef](https://github.com/btnalit/pi-claude-supervisor/commit/cd0b8efdd0898833036b14acab5ca7b29ca70d04))
+
+## [0.9.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.9.0...v0.9.1) (2026-09-24)
+
+
+### Bug Fixes
+
+* long-task stability findings from an independent 0.9.0 review ([#62](https://github.com/btnalit/pi-claude-supervisor/issues/62)) ([35c6789](https://github.com/btnalit/pi-claude-supervisor/commit/35c678962c357bc188eb2ed82141e4046ae793aa))
+* **review:** pin Reviewer finding key order so quoted text cannot swap a P0's description ([#64](https://github.com/btnalit/pi-claude-supervisor/issues/64)) ([6df3fd2](https://github.com/btnalit/pi-claude-supervisor/commit/6df3fd2b75a9555eb6dc9112b1c19f5e35bfa3cd))
+
 ## [0.9.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.8.1...v0.9.0) (2026-09-20)
 
 

package/README.cn.md

@@ -202,8 +202,11 @@ stream-json` 的方式运行 Claude,完全没有终端界面;一旦设置
   时间。只有收尾窗口也耗尽,Worker 才会被硬停(`worker_watchdog_timeout`);对
   接管的交互式会话来说这个硬停只是 release:Claude 继续运行,但不再受监督。
   收尾窗口只属于自动模式任务;手动任务仍在到期时停止,`DEADLINE_GRACE_MS=0`
-  让自动任务也恢复这一行为。20 分钟无输出 watchdog(`NO_OUTPUT_TIMEOUT_MS`)
-  随时会停止沉默的 Worker。
+  让自动任务也恢复这一行为。20 分钟无输出 watchdog(`NO_OUTPUT_TIMEOUT_MS`,
+  从 Worker 最后一次输出或 Supervisor 最后一次发给它的消息起算)会停止在一轮
+  中途沉默的 Worker;自动模式下只是空闲了这么久的 Worker(在等永远没回来的
+  后台工作)则改为直接验收(`worker_idle_timeout`),人工接管中的 Worker 不会
+  因沉默超时。
 - 验收命令、证据收集和 Reviewer 共用一个 abort signal,因此 stop 或 shutdown
   不必等待完整的命令或模型超时。
 - 每个任务只持有一个 cwd 租约;并发任务需要各自独立的 worktree。
@@ -285,7 +288,7 @@ commit,通知能说清已验证的 commit 是否在工作树变动之前就已
   "autonomy": {
     "unattended": true,
     "requireLocalCommit": true,
-    "maxDecisionRetries": 2,
+    "maxDecisionRetries": 4,
     "permissionAuthority": "hybrid",
     "maxWorkerCostUsd": 20
   }
@@ -298,7 +301,9 @@ commit,通知能说清已验证的 commit 是否在工作树变动之前就已
 ## 配置参考
 
 环境变量(或 `~/.config/pi-claude-supervisor/env`),均以 `PI_CLAUDE_SUPERVISOR_`
-为前缀;完整模板见 `.env.example`。
+为前缀;完整模板见 `.env.example`。env 文件每行是 `KEY=value`,可以带 `export `
+前缀和行尾 ` # 注释`。数值、时长或布尔类配置超出范围或无法解析时会沿用默认值,
+并以 `pi-claude-supervisor: ignoring …` 警告报告一次。
 
 | 变量 | 默认值 | 含义 |
 | --- | --- | --- |
@@ -321,7 +326,7 @@ commit,通知能说清已验证的 commit 是否在工作树变动之前就已
 | `HUMAN_WEBHOOK_SECRET` | 未设置 | HMAC 签名密钥;以 `x-pi-supervisor-signature` header 发送 |
 | `UNATTENDED` | `true` | 任务无需同步人工回调即可运行 |
 | `REQUIRE_LOCAL_COMMIT` | `true` | 完成前要求在候选所在分支上有本地 commit |
-| `MAX_DECISION_RETRIES` | `2`(0–10) | Decision Worker 调用超时或失败(429/529、网络、鉴权)时的重试次数 |
+| `MAX_DECISION_RETRIES` | `4`(0–10) | Decision Worker 调用超时或失败(429/529、网络、鉴权)时的重试次数;两次尝试之间依次等待 15s、45s、60s |
 | `PERMISSION_AUTHORITY` | `hybrid` | `policy` \| `hybrid` \| `decision-worker` |
 | `REMOTE_AUTHORITY` | `none` | `none` \| `push` \| `pr`;验收通过后开启发布阶段。`--remote` 可按任务覆盖 |
 | `REMOTE_NAME` | `origin` | 发布授权唯一允许的 remote 名 |
@@ -336,8 +341,8 @@ commit,通知能说清已验证的 commit 是否在工作树变动之前就已
 | `DECISION_SESSION_RETENTION_DAYS` | `30` | 启动时清理早于此天数的已关闭 Decision Worker session 记录;`0` 表示永久保留 |
 | `EVIDENCE_MAX_BYTES` | `1048576`(1 MiB) | 每个任务收集的最大仓库证据字节数 |
 | `EVIDENCE_MAX_UNTRACKED_FILES` | `512` | 每个任务作为证据收集的最大未跟踪文件数 |
-| `REVIEW_TIMEOUT_MS` | `600000`(10 分钟) | 每轮独立 Reviewer 的总预算,含一次针对 provider 错误的重试 |
-| `DEADLINE_MS` | `4h` | 每个任务的累计总时限(`8h`、`90m`、`2h30m` 或毫秒;5 分钟到 7 天);`0`(或 `0m`)关闭;`--deadline` 可按任务覆盖 |
+| `REVIEW_TIMEOUT_MS` | `10m`(30s–1h) | 每轮独立 Reviewer 的总预算;预算未用完时,provider 错误会用新会话重试 |
+| `DEADLINE_MS` | `4h` | 每个任务从启动起算的墙钟总时限,Pi 停机期间也计入,因此恢复时用 `recover --extend` 重新给预算(`8h`、`90m`、`2h30m` 或毫秒;5 分钟到 7 天);`0`(或 `0m`)关闭;`--deadline` 可按任务覆盖 |
 | `DEADLINE_GRACE_MS` | `30m` | 自动任务到期后的收尾窗口:空闲的 Worker 会被验收而不是停止;`0` 恢复到期立即停止 |
 | `DEADLINE_WARNING_MS` | `15m` | 到期前多久提醒并重新询问 Decision Worker;`0` 关闭提醒 |
 | `NO_OUTPUT_TIMEOUT_MS` | `20m` | Worker 多久没有输出就停止;`0` 关闭该检查 |
@@ -358,7 +363,10 @@ Worker,它不会静默恢复或重复执行任务。只有在租约证明旧 Wor
 会拒绝它;`recover --takeover --extend <duration> <task-id>` 从现在起再给这么
 多预算(恢复后的 Supervisor 会把新时限持久化),`--extend 0` 则立即进入收尾:
 新 Worker 的第一个 watchdog tick 就会对仓库现状做验收和 review,修复轮会告诉
-它还剩多少时间。确定不再恢复的记录用 `/supervise discard <task-id>` 丢弃
+它还剩多少时间。带 `--extend` 时,恢复的任务会直接交回自动化:非零的延长会
+给新 Worker 发送原任务的续做指令(先让它查看已有的工作),`--extend 0` 则无需
+指令。不带 `--extend` 的普通 `recover` 仍让 Worker 在人工接管下空闲——先发送
+续做指令,再执行 `resume-auto`。确定不再恢复的记录用 `/supervise discard <task-id>` 丢弃
 (会话文件保留到保留期清理为止)。
 
 每个任务在 `CWD_LEASE_DIR` 下持有一个 cwd 租约;并发任务需要各自独立的

package/README.md

@@ -247,8 +247,11 @@ Supervisor being able to see it, or when you don't need to attach.
   is a release: Claude keeps running, unsupervised. The close-out belongs to
   automatic tasks; a manual task is stopped at the deadline as before, and
   `DEADLINE_GRACE_MS=0` restores that for automatic ones too. A 20-minute
-  no-output watchdog (`NO_OUTPUT_TIMEOUT_MS`) still stops a silent Worker at
-  any time.
+  no-output watchdog (`NO_OUTPUT_TIMEOUT_MS`, counted from the Worker's last
+  output or the Supervisor's last message to it) stops a Worker that falls
+  silent mid-turn; an automatic Worker that is merely idle that long (waiting on
+  background work that never came back) is verified instead
+  (`worker_idle_timeout`), and a Worker under human takeover is never timed out.
 - 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.
@@ -374,7 +377,7 @@ confirmed publish says so in its candidate notice instead of reporting a bare
   "autonomy": {
     "unattended": true,
     "requireLocalCommit": true,
-    "maxDecisionRetries": 2,
+    "maxDecisionRetries": 4,
     "permissionAuthority": "hybrid",
     "maxWorkerCostUsd": 20
   }
@@ -388,7 +391,11 @@ 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.
+`PI_CLAUDE_SUPERVISOR_`; see `.env.example` for a template. The env file takes
+`KEY=value` lines, optionally prefixed with `export ` and followed by a
+` # comment`. A numeric, duration or boolean value that is out of range or
+unparsable keeps the default and is reported once as a
+`pi-claude-supervisor: ignoring …` warning.
 
 | Variable | Default | Meaning |
 | --- | --- | --- |
@@ -411,7 +418,7 @@ Environment variables (or `~/.config/pi-claude-supervisor/env`), all prefixed
 | `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) |
+| `MAX_DECISION_RETRIES` | `4` (0–10) | Retries of a Decision Worker call that times out or fails (429/529, network, auth); waits 15s, 45s, then 60s between attempts |
 | `PERMISSION_AUTHORITY` | `hybrid` | `policy` \| `hybrid` \| `decision-worker` |
 | `REMOTE_AUTHORITY` | `none` | `none` \| `push` \| `pr`; grants the publish phase after verification passes. `--remote` overrides it per task |
 | `REMOTE_NAME` | `origin` | The single remote a publish grant may name |
@@ -426,8 +433,8 @@ Environment variables (or `~/.config/pi-claude-supervisor/env`), all prefixed
 | `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 |
-| `DEADLINE_MS` | `4h` | Cumulative wall-clock budget per task (`8h`, `90m`, `2h30m` or ms; 5m–7d); `0` (or `0m`) disables it; `--deadline` overrides it per task |
+| `REVIEW_TIMEOUT_MS` | `10m` (30s–1h) | Total independent Reviewer budget per round; a provider error is retried with a fresh session while budget remains |
+| `DEADLINE_MS` | `4h` | Wall-clock budget per task, measured from its start — time Pi was down counts too, so `recover --extend` grants a fresh budget (`8h`, `90m`, `2h30m` or ms; 5m–7d); `0` (or `0m`) disables it; `--deadline` overrides it per task |
 | `DEADLINE_GRACE_MS` | `30m` | Close-out window after the deadline for automatic tasks: an idle Worker is verified instead of stopped; `0` restores the immediate stop |
 | `DEADLINE_WARNING_MS` | `15m` | How long before the deadline the Decision Worker is warned and re-asked; `0` disables the warning |
 | `NO_OUTPUT_TIMEOUT_MS` | `20m` | Stop a Worker that has produced no output for this long; `0` disables the check |
@@ -452,7 +459,11 @@ A task that stopped at its wall-clock deadline is listed with `deadline=expired
 <task-id>` grants that much budget from now (the recovered Supervisor persists
 the new deadline), and `--extend 0` opens the close-out at once, so the fresh
 Worker's first watchdog tick verifies and reviews the repository as it stands
-and any repair round tells it how long it has. A record nobody will recover is
+and any repair round tells it how long it has. With `--extend` the recovered
+task goes straight back to automation: a real extension sends the fresh Worker a
+continuation of the original task (telling it to inspect the earlier work first),
+and `--extend 0` needs none. A plain `recover` still leaves the Worker idle under
+takeover — send it a continuation, then `resume-auto`. A record nobody will recover is
 dropped with `/supervise discard <task-id>` (its session file is kept until
 retention pruning).
 

package/docs/architecture.md

@@ -143,7 +143,8 @@ start); credentials are not copied into a file, and credential-shaped command
 arguments are still rejected.
 `load-buffer`, bracketed `paste-buffer` and `send-keys Enter` provide the input
 boundary without interpolating a task into a shell command. C0/C1 terminal
-control bytes are rejected; CRLF is normalized to a newline. Automatic agents,
+control bytes are neutralized (escape sequences removed, a lone CR becomes a newline,
+other C0/C1 bytes become spaces); CRLF is normalized to a newline. Automatic agents,
 background tasks, plugins, MCP servers and nested Claude processes stay in the
 same cgroup and are cleaned with the Worker; they are intentionally not rejected
 or polled as a nested-process policy failure. The lexical Bash/file-tool policy
@@ -399,8 +400,11 @@ For Claude JSONL, the adapter tracks `activeRequests`, `lastInputAt` and
 `lastOutputAt`. A `result` record closes an active request; malformed output does
 not. JSONL sends are rejected while a request is active, and a valid terminal
 result moves the session to `waiting`; only then may the next turn be sent. A paused
-Worker does not consume its no-output budget; resume establishes a fresh no-output
-baseline while the cumulative wall-clock deadline remains active.
+Worker does not consume its no-output budget; resume, and every message the
+Supervisor sends, establishes a fresh no-output baseline while the cumulative
+wall-clock deadline remains active. An idle automatic Worker that reaches the
+no-output timeout is verified (`worker_idle_timeout`) rather than stopped, and a
+Worker under human takeover is exempt.
 
 The wall-clock deadline is a budget, not a kill switch. The watchdog drives it
 through three phases, each recorded once per task: `worker_deadline_approaching`
@@ -513,10 +517,17 @@ parked or failed without granting remote/main authority. Model/API failures are
 detected from the Pi `stopReason` (a provider error resolves the prompt normally
 rather than throwing); if the Decision Worker
 API/model call fails, the system records `decision_worker_failed`, applies the
-bounded retry/park policy and preserves the candidate evidence. An abort is never
+bounded retry/park policy and preserves the candidate evidence. The startup
+instructions prompt retries provider errors on the same backoff and budget, so a
+provider overload at start does not fail the task before its first turn. An abort is never
 retried, and a `noop` reply on a completed turn or a permission request parks the
 candidate rather than being treated as a resolved decision, while a `noop` on a
-clean Worker exit proceeds to verification. Optional alert
+clean Worker exit proceeds to verification. A `stop` on a completed turn of an
+unattended task without remote authority stops the Worker (never keeping it open)
+and then verifies its finished work instead of discarding it (`decision_overridden`);
+no repair round may follow, so a failure blocks the candidate. A `stop` on a
+pending permission, on a turn the Worker has already resumed, or on a task with
+remote authority stays a plain stop. Optional alert
 delivery remains independent from event-log persistence, but notification is not
 the control boundary.
 
@@ -587,19 +598,40 @@ When automatic supervision is enabled, a successful check set is passed to a
 fresh read-only Reviewer session. The Reviewer receives the task specification, repository status/diff evidence,
 check results and bounded Worker completion evidence, but not the Decision Worker
 conversation or control channel. It can inspect only `read`, `grep`, `find` and `ls`, and must return
-`pass`, `revise` or `human` with bounded structured findings. Invalid Reviewer
+`pass`, `revise` or `human` with bounded structured findings. Its whole reply
+must be that one JSON object (an optional ```json fence aside), carrying a
+random `reviewId` that appears only in its own prompt, with no key repeated and
+nothing beyond the schema (a string `summary`, and `findings` as flat objects of
+the finding fields with scalar values). Each finding opens with `severity`
+then a non-empty `message` (an `id` may lead) and closes with `evidence` if it
+has one — the only field the prompt allows repository quotes in. Repository
+text it quotes or copies therefore cannot stand in for the answer, change its
+verdict, or drop a finding it wrote, and a quote in `evidence` that closes a
+finding early can only add findings after it — never change the severity,
+message, fix or location the Reviewer already wrote. A quote the Reviewer puts
+in any other field against the prompt can still reach the rest of that
+finding. Added findings cannot unblock a candidate (any P0/P1 blocks, even
+under `pass`), and repair instructions list findings most severe first so
+added lesser ones cannot crowd out a blocking one. A reply that breaks any of
+these earns one corrective re-prompt. Invalid Reviewer
 output, incomplete evidence or a Reviewer API failure must prevent a candidate
 from crossing the remote/main boundary; the local system may retry, repair or
-park it without requiring a human to be online. The Reviewer retries a provider
-error once within a total review budget
+park it without requiring a human to be online. The Reviewer retries provider
+errors with a fresh session within a total review budget
 (`PI_CLAUDE_SUPERVISOR_REVIEW_TIMEOUT_MS`, default 10 minutes). Truncated
 (oversize) evidence requests a bounded repair before parking, while incomplete
 evidence still parks.
 
 A `revise` result produces an audited repair round and sends a bounded corrective
 instruction to a still-live `repairableSession` Worker. Checks and review then run again.
-The repair budget defaults to three rounds; repeated findings and P0/P1 findings
-stop automation and park a non-publishable candidate. A Worker that has already exited cannot be silently recreated
+The Decision Worker sees the last result tagged with the Worker turn it judged, and chooses
+when to verify again; if it keeps steering instead, the Supervisor verifies on its own once
+the Worker has taken three turns since that failure (`decision_overridden`), so a Decision
+Worker reasoning from the stale failure cannot hold a fixed Worker in a loop until the deadline.
+The repair budget defaults to three rounds. P0/P1 findings block a `pass` but are repair
+inputs like any other concrete finding (a `pass` carrying one is treated as `revise`); a
+`human` verdict, repeated findings or an exhausted budget stop automation and park a
+non-publishable candidate. A Worker that has already exited cannot be silently recreated
 for repair; it remains failed/recoverable rather than replaying the original task. If a repair
 or candidate branch cannot continue, a single idempotent terminalizer records
 `verification_failed`, closes the Decision Worker and reports cleanup evidence; it never performs

package/docs/autonomy-target.md

@@ -106,7 +106,7 @@ stop or park safely and retain evidence; it must not silently grant remote or ma
 Automatic mode implements the local loop: policy decisions allow ordinary local development,
 `AskUserQuestion` is converted to a denied interactive permission, the Decision Worker can
 continue/redirect/answer/repair, acceptance and independent Review run without a human callback,
-and unresolved situations become `blocked` candidates. The default task autonomy is unattended, requires a local commit, and permits two bounded
+and unresolved situations become `blocked` candidates. The default task autonomy is unattended, requires a local commit, and permits four bounded
 Decision Worker request retries. Automatic startup rejects non-Git/detached/bare/protected
 repository states, malformed baselines, startup-HEAD races, the unstructured
 process-pipe transport, Bash-preauthorizing Claude arguments/settings and non-Claude or untrusted

package/docs/testing.md

@@ -1,6 +1,6 @@
 # Testing
 
-> Autonomy target: local editing, testing, repair and local commits run without a human being online. Invalid output, unavailable evidence, duplicate findings, P0/P1 findings and exhausted budgets become parked/non-publishable candidates rather than synchronous human gates. Remote push and main/integration merge remain independent-boundary tests. See [autonomy-target.md](autonomy-target.md).
+> Autonomy target: local editing, testing, repair and local commits run without a human being online. Invalid output (after one corrective re-prompt), unavailable evidence, duplicate findings, a `human` Reviewer verdict and exhausted budgets become parked/non-publishable candidates rather than synchronous human gates. Remote push and main/integration merge remain independent-boundary tests. See [autonomy-target.md](autonomy-target.md).
 
 ## Local checks
 
@@ -113,6 +113,43 @@ PI_CLAUDE_SUPERVISOR_REAL_CLAUDE_PATH="$HOME/.local/share/mise/installs/claude/l
 PI_CLAUDE_SUPERVISOR_REAL_CLAUDE=1 npm run spike:tmux
 ```
 
+The Decision spike runs a real Pi Decision Worker and Reviewer, on any Pi
+model, against a scripted Worker that edits a temporary git repository. It
+needs no Claude Code, cgroup or tmux, so it runs on hosts that cannot run the
+real-Claude spikes. It is gated and excluded from normal CI:
+
+```bash
+# Default model: google/gemini-3.5-flash-lite
+PI_CLAUDE_SUPERVISOR_REAL_DECISION=1 npm run spike:decision
+# Optional: another Pi model, a subset of scenarios, a per-scenario deadline,
+# and keeping the temp repositories
+SPIKE_DECISION_MODEL=google/gemini-3.1-flash-lite \
+SPIKE_DECISION_SCENARIOS=review,stuck SPIKE_TIMEOUT_MS=600000 SPIKE_KEEP=1 \
+PI_CLAUDE_SUPERVISOR_REAL_DECISION=1 npm run spike:decision
+```
+
+Credentials come only from Pi's own sources (for example `GEMINI_API_KEY` in
+the environment, or `~/.pi/agent/auth.json`); the script never reads, prints or
+stores a key, and redacts what it prints. The scenarios cover:
+- `review`: an incomplete first turn is caught and repaired. Two model
+  behaviors fail it without being regressions: a Reviewer that passes the
+  incomplete turn, and a Decision Worker that answers the "task is complete"
+  turn with `stop`, which ends the task blocked with no repair;
+- `question`: a mid-task question is answered from the spec without a human;
+- `stuck`: a Worker that only claims success ends `blocked` within its repair
+  budget.
+
+The scripted Worker writes the full implementation only after a Supervisor
+message that mentions the RangeError (or min > max). A Decision Worker answer
+that never names it leaves the work undone, and the scenario fails.
+
+Each prints a redacted summary: state, decisions, overrides, Reviewer verdicts
+and answer-format failures. The script exits non-zero when a scenario misses
+its expected outcome. Weak and rate-limited models are useful here, because
+they exercise the deterministic guards that the prompt alone does not
+guarantee. A daily quota error at startup or mid-task is expected to fail
+closed (park), and is not a regression.
+
 The tmux spike is gated, authenticated, and excluded from normal CI. It uses
 plan mode with a fixed `opus` model, records only protocol metadata, and
 verifies three real Claude turns, exact screen-result markers, pause/resume,
@@ -146,7 +183,7 @@ Pi Decision Worker. Setting `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux` selects the
 Supervisor-owned live bridge, which carries the same structured records through
 private framing on the PTY rather than an independent JSONL sidecar. Task autonomy
 defaults to unattended local work, a required
-local commit on the task branch (any branch, anchored to the baseline commit) and two bounded Decision Worker retries. Configure
+local commit on the task branch (any branch, anchored to the baseline commit) and four bounded Decision Worker retries. Configure
 `PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT=0` or task `autonomy.requireLocalCommit`
 only to disable the local-commit deliverability check; automatic mode still requires a Git
 baseline (any branch, including `main`; the candidate must descend from it). The tmux bridge
@@ -240,7 +277,7 @@ Deterministic tests must cover:
 - multiple required/optional checks with bounded output, timeout and exit-code evidence;
 - independent read-only Reviewer pass/revise/human results;
 - invalid Reviewer JSON and Reviewer API failure becoming a parked/non-publishable candidate without requiring a live callback;
-- repair rounds, repeated finding detection, P0/P1 parking and repair-budget exhaustion;
+- repair rounds (P0/P1 findings are repaired, never passed), repeated finding detection and repair-budget exhaustion;
 - non-persistent JSONL verification failure without duplicate terminal transitions;
 - repairable-but-not-persistent JSONL multi-turn repair;
 - stop and Pi shutdown from `verifying`, including Decision Worker closure and cwd lease release;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {
@@ -61,6 +61,7 @@
     "spike:permissions": "node scripts/spike-claude-permissions.mjs",
     "spike:signals": "node scripts/spike-claude-signals.mjs",
     "spike:automation": "node scripts/spike-claude-automation.mjs",
+    "spike:decision": "node scripts/spike-decision.mjs",
     "check": "npm run typecheck && npm test && npm run check:package && npm run check:docs && npm run check:automation",
     "build": "node scripts/build-package.mjs"
   },

package/src/acceptance.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_MAX_DECISION_RETRIES } from "./config.ts";
 import { isPlainRemoteName } from "./policy.ts";
 import type { AcceptanceCheck, TaskSpec } from "./types.ts";
 
@@ -94,7 +95,7 @@ function normalizeAutonomy(value: unknown, defaults?: Partial<TaskSpec["autonomy
   const source = value as Record<string, unknown>;
   if (source.unattended !== undefined && typeof source.unattended !== "boolean") throw new Error("task spec autonomy.unattended must be boolean");
   if (source.requireLocalCommit !== undefined && typeof source.requireLocalCommit !== "boolean") throw new Error("task spec autonomy.requireLocalCommit must be boolean");
-  const retries = source.maxDecisionRetries ?? defaults?.maxDecisionRetries ?? 2;
+  const retries = source.maxDecisionRetries ?? defaults?.maxDecisionRetries ?? DEFAULT_MAX_DECISION_RETRIES;
   if (typeof retries !== "number" || !Number.isSafeInteger(retries) || retries < 0 || retries > 10) throw new Error("task spec autonomy.maxDecisionRetries must be between 0 and 10");
   const authority = source.permissionAuthority ?? defaults?.permissionAuthority ?? "hybrid";
   if (authority !== "policy" && authority !== "hybrid" && authority !== "decision-worker") throw new Error("task spec autonomy.permissionAuthority must be policy, hybrid or decision-worker");

package/src/config.ts

@@ -60,22 +60,22 @@ export interface AutonomyDefaults {
 
 export function autonomyDefaults(env: NodeJS.ProcessEnv = process.env): AutonomyDefaults {
   return {
-    unattended: readBoolean(env.PI_CLAUDE_SUPERVISOR_UNATTENDED, true),
-    requireLocalCommit: readBoolean(env.PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT, true),
-    maxDecisionRetries: readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES, 2, 0, 10),
+    unattended: readBoolean(env.PI_CLAUDE_SUPERVISOR_UNATTENDED, true, "PI_CLAUDE_SUPERVISOR_UNATTENDED"),
+    requireLocalCommit: readBoolean(env.PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT, true, "PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT"),
+    maxDecisionRetries: readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES, DEFAULT_MAX_DECISION_RETRIES, 0, 10, "PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES"),
     permissionAuthority: readPermissionAuthority(env.PI_CLAUDE_SUPERVISOR_PERMISSION_AUTHORITY),
     remoteAuthority: readRemoteAuthority(env.PI_CLAUDE_SUPERVISOR_REMOTE_AUTHORITY),
     remoteName: readRemoteName(env.PI_CLAUDE_SUPERVISOR_REMOTE_NAME),
-    ...(readPositiveNumber(env.PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD) !== undefined ? { maxWorkerCostUsd: readPositiveNumber(env.PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD) } : {}),
+    ...(readPositiveNumber(env.PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD, "PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD") !== undefined ? { maxWorkerCostUsd: readPositiveNumber(env.PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD, "PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD") } : {}),
   };
 }
 
 export function reviewTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_REVIEW_TIMEOUT_MS, 600_000, 30_000, 3_600_000);
+  return readBoundedDuration(env.PI_CLAUDE_SUPERVISOR_REVIEW_TIMEOUT_MS, 600_000, 30_000, 3_600_000, "PI_CLAUDE_SUPERVISOR_REVIEW_TIMEOUT_MS");
 }
 
 export function eventLogMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVENT_LOG_MAX_BYTES, 64 * 1024 * 1024, 1024 * 1024, 1024 * 1024 * 1024);
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVENT_LOG_MAX_BYTES, 64 * 1024 * 1024, 1024 * 1024, 1024 * 1024 * 1024, "PI_CLAUDE_SUPERVISOR_EVENT_LOG_MAX_BYTES");
 }
 
 export function workerModel(env: NodeJS.ProcessEnv = process.env): string | undefined {
@@ -84,7 +84,7 @@ export function workerModel(env: NodeJS.ProcessEnv = process.env): string | unde
 
 /** The 200_000 default applies only in automatic mode; "0" is an explicit opt-out that omits --autocompact. */
 export function workerAutocompactTokens(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedIntegerWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_WORKER_AUTOCOMPACT_TOKENS, 200_000, 100_000, 1_000_000);
+  return readBoundedIntegerWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_WORKER_AUTOCOMPACT_TOKENS, 200_000, 100_000, 1_000_000, "PI_CLAUDE_SUPERVISOR_WORKER_AUTOCOMPACT_TOKENS");
 }
 
 export function workerMcpConfigPath(env: NodeJS.ProcessEnv = process.env): string | undefined {
@@ -101,25 +101,27 @@ export function reviewerModel(env: NodeJS.ProcessEnv = process.env): string | un
 
 /** "0" is an explicit opt-out that disables Decision Worker session compaction. */
 export function decisionCompactionTokens(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedIntegerWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DECISION_COMPACT_TOKENS, 60_000, 10_000, 500_000);
+  return readBoundedIntegerWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DECISION_COMPACT_TOKENS, 60_000, 10_000, 500_000, "PI_CLAUDE_SUPERVISOR_DECISION_COMPACT_TOKENS");
 }
 
 export function progressHeartbeatMs(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_PROGRESS_HEARTBEAT_MS, 60_000, 5_000, 3_600_000);
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_PROGRESS_HEARTBEAT_MS, 60_000, 5_000, 3_600_000, "PI_CLAUDE_SUPERVISOR_PROGRESS_HEARTBEAT_MS");
 }
 
 export function decisionSessionRetentionDays(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_DECISION_SESSION_RETENTION_DAYS, 30, 0, 3650);
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_DECISION_SESSION_RETENTION_DAYS, 30, 0, 3650, "PI_CLAUDE_SUPERVISOR_DECISION_SESSION_RETENTION_DAYS");
 }
 
 export function evidenceMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_BYTES, 1024 * 1024, 64 * 1024, 64 * 1024 * 1024);
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_BYTES, 1024 * 1024, 64 * 1024, 64 * 1024 * 1024, "PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_BYTES");
 }
 
 export function evidenceMaxUntrackedFiles(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_UNTRACKED_FILES, 512, 16, 10_000);
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_UNTRACKED_FILES, 512, 16, 10_000, "PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_UNTRACKED_FILES");
 }
 
+/** Retries of a failed Decision Worker request before the task is parked. */
+export const DEFAULT_MAX_DECISION_RETRIES = 4;
 export const DEFAULT_DEADLINE_MS = 4 * 60 * 60_000;
 export const DEFAULT_DEADLINE_GRACE_MS = 30 * 60_000;
 export const DEFAULT_DEADLINE_WARNING_MS = 15 * 60_000;
@@ -131,7 +133,7 @@ export const DEFAULT_NO_OUTPUT_TIMEOUT_MS = 20 * 60_000;
  * accepted as well as plain milliseconds.
  */
 export function deadlineMs(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_MS, DEFAULT_DEADLINE_MS, 5 * 60_000, 7 * 24 * 60 * 60_000);
+  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_MS, DEFAULT_DEADLINE_MS, 5 * 60_000, 7 * 24 * 60 * 60_000, "PI_CLAUDE_SUPERVISOR_DEADLINE_MS");
 }
 
 /**
@@ -140,17 +142,17 @@ export function deadlineMs(env: NodeJS.ProcessEnv = process.env): number {
  * restores the immediate stop at the deadline. Up to 24 hours.
  */
 export function deadlineGraceMs(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_GRACE_MS, DEFAULT_DEADLINE_GRACE_MS, 60_000, 24 * 60 * 60_000);
+  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_GRACE_MS, DEFAULT_DEADLINE_GRACE_MS, 60_000, 24 * 60 * 60_000, "PI_CLAUDE_SUPERVISOR_DEADLINE_GRACE_MS");
 }
 
 /** How long before the deadline the Decision Worker is warned (up to 24 hours); "0" disables the warning. */
 export function deadlineWarningMs(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_WARNING_MS, DEFAULT_DEADLINE_WARNING_MS, 60_000, 24 * 60 * 60_000);
+  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_WARNING_MS, DEFAULT_DEADLINE_WARNING_MS, 60_000, 24 * 60 * 60_000, "PI_CLAUDE_SUPERVISOR_DEADLINE_WARNING_MS");
 }
 
 /** Stop a Worker that has produced no output for this long (1 minute to 24 hours); "0" disables the check. */
 export function noOutputTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
-  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_NO_OUTPUT_TIMEOUT_MS, DEFAULT_NO_OUTPUT_TIMEOUT_MS, 60_000, 24 * 60 * 60_000);
+  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_NO_OUTPUT_TIMEOUT_MS, DEFAULT_NO_OUTPUT_TIMEOUT_MS, 60_000, 24 * 60 * 60_000, "PI_CLAUDE_SUPERVISOR_NO_OUTPUT_TIMEOUT_MS");
 }
 
 const DURATION_UNITS_MS: Record<string, number> = { ms: 1, s: 1_000, m: 60_000, h: 60 * 60_000, d: 24 * 60 * 60_000 };
@@ -193,10 +195,12 @@ export function loadSupervisorEnvironment(): string | undefined {
     // Best effort: the file is local configuration, never a repository asset.
     try { chmodSync(path, 0o600); } catch { /* read-only filesystems may reject chmod */ }
     for (const line of contents.split(/\r?\n/u)) {
-      const match = line.match(/^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*?)\s*$/u);
+      // Shell-style: an optional `export ` prefix, and a trailing `# comment`
+      // after an unquoted value or a closing quote. Keeping the comment made
+      // `MODE="auto" # enable` a value no reader accepts.
+      const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=(.*?)\s*$/u);
       if (!match || !allowed.has(match[1]) || process.env[match[1]] !== undefined) continue;
-      const value = match[2].replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/u, (_, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted);
-      process.env[match[1]] = value;
+      process.env[match[1]] = envFileValue(match[2]);
     }
     return path;
   } catch (error) {
@@ -205,32 +209,72 @@ export function loadSupervisorEnvironment(): string | undefined {
   }
 }
 
-function readBoolean(value: string | undefined, fallback: boolean): boolean {
+const reportedSettings = new Set<string>();
+
+/**
+ * An unusable value keeps the default, but never silently: `DEADLINE_MS=10d`
+ * quietly running a 4h task is exactly the surprise an unattended run cannot
+ * afford. Each distinct rejected value is reported once per process.
+ */
+function rejectSetting(name: string | undefined, value: string, reason: string, fallback: unknown): void {
+  // An empty assignment (`KEY=`) is how an env file leaves a key unset.
+  if (!name || value.trim() === "") return;
+  const key = `${name}=${value}`;
+  if (reportedSettings.has(key)) return;
+  reportedSettings.add(key);
+  console.warn(`pi-claude-supervisor: ignoring ${name}=${JSON.stringify(String(redactSensitive(value)))} (${reason}); using ${String(fallback)}`);
+}
+
+/** The value of one env-file assignment: quoted text verbatim, or an unquoted word before any ` #` comment. */
+export function envFileValue(raw: string): string {
+  // `KEY= # note` is an empty value with a comment, as in a shell; only a
+  // `#` right after the `=` (`KEY=#abc`) belongs to the value.
+  if (/^\s+#/u.test(raw)) return "";
+  raw = raw.trimStart();
+  const quoted = raw.match(/^(?:"([^"]*)"|'([^']*)')(?:\s+#.*)?$/u);
+  if (quoted) return quoted[1] ?? quoted[2] ?? "";
+  // A comment needs whitespace before its `#`, as in a shell: `KEY=#abc`
+  // is the value `#abc` (a webhook secret may well start with one).
+  return raw.replace(/\s+#.*$/u, "").trim();
+}
+
+function readBoolean(value: string | undefined, fallback: boolean, name?: string): boolean {
   if (value === undefined) return fallback;
   if (/^(?:1|true|yes|on)$/iu.test(value.trim())) return true;
   if (/^(?:0|false|no|off)$/iu.test(value.trim())) return false;
+  rejectSetting(name, value, "expected 1/0, true/false, yes/no or on/off", fallback);
   return fallback;
 }
 
-function readBoundedInteger(value: string | undefined, fallback: number, minimum: number, maximum: number): number {
+function readBoundedInteger(value: string | undefined, fallback: number, minimum: number, maximum: number, name?: string): number {
   if (value === undefined) return fallback;
   const parsed = Number(value);
-  return Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum ? parsed : fallback;
+  if (Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum) return parsed;
+  rejectSetting(name, value, `expected an integer from ${minimum} to ${maximum}`, fallback);
+  return fallback;
 }
 
 /** Like readBoundedInteger, but the literal "0" is always honored as an opt-out below the normal minimum. */
-function readBoundedIntegerWithZeroOptOut(value: string | undefined, fallback: number, minimum: number, maximum: number): number {
+function readBoundedIntegerWithZeroOptOut(value: string | undefined, fallback: number, minimum: number, maximum: number, name?: string): number {
   if (value !== undefined && value.trim() === "0") return 0;
-  return readBoundedInteger(value, fallback, minimum, maximum);
+  return readBoundedInteger(value, fallback, minimum, maximum, name);
 }
 
-/** Like readBoundedIntegerWithZeroOptOut, but also accepts a duration suffix (`8h`, `90m`); out-of-range values keep the fallback. */
-function readBoundedDurationWithZeroOptOut(value: string | undefined, fallback: number, minimum: number, maximum: number): number {
+/** A duration (`20m`, `1h30m`, or plain milliseconds) within bounds; anything else keeps the fallback. */
+function readBoundedDuration(value: string | undefined, fallback: number, minimum: number, maximum: number, name?: string): number {
   if (value === undefined) return fallback;
   const parsed = parseDurationMs(value);
+  if (parsed !== undefined && parsed >= minimum && parsed <= maximum) return parsed;
+  rejectSetting(name, value, `expected a duration from ${formatDurationMs(minimum)} to ${formatDurationMs(maximum)}`, formatDurationMs(fallback));
+  return fallback;
+}
+
+/** Like readBoundedIntegerWithZeroOptOut, but also accepts a duration suffix (`8h`, `90m`); out-of-range values keep the fallback. */
+function readBoundedDurationWithZeroOptOut(value: string | undefined, fallback: number, minimum: number, maximum: number, name?: string): number {
+  if (value === undefined) return fallback;
   // "0", "0m", "0h": any zero duration is the opt-out, not a below-minimum typo.
-  if (parsed === 0) return 0;
-  return parsed !== undefined && parsed >= minimum && parsed <= maximum ? parsed : fallback;
+  if (parseDurationMs(value) === 0) return 0;
+  return readBoundedDuration(value, fallback, minimum, maximum, name);
 }
 
 function readTrimmedString(value: string | undefined): string | undefined {
@@ -262,10 +306,12 @@ function readPermissionAuthority(value: string | undefined): PermissionAuthority
   return normalized === "policy" || normalized === "decision-worker" ? normalized : "hybrid";
 }
 
-function readPositiveNumber(value: string | undefined): number | undefined {
+function readPositiveNumber(value: string | undefined, name?: string): number | undefined {
   if (value === undefined || value.trim() === "") return undefined;
   const parsed = Number(value);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  rejectSetting(name, value, "expected a positive number", "no limit");
+  return undefined;
 }
 
 /** How automatic tmux supervision drives Claude: the real TUI through hooks (default) or the stream-json bridge. */
@@ -275,10 +321,10 @@ export function tmuxMode(env: NodeJS.ProcessEnv = process.env): "interactive" |
 
 /** Exit the interactive Worker and its tmux session once a task completes; default keeps it open for the operator. */
 export function closeWorkerOnCompletion(env: NodeJS.ProcessEnv = process.env): boolean {
-  return readBoolean(env.PI_CLAUDE_SUPERVISOR_CLOSE_WORKER_ON_COMPLETION, false);
+  return readBoolean(env.PI_CLAUDE_SUPERVISOR_CLOSE_WORKER_ON_COMPLETION, false, "PI_CLAUDE_SUPERVISOR_CLOSE_WORKER_ON_COMPLETION");
 }
 
 /** Install the user-level Claude Code hook entries automatically when the interactive tmux mode is configured. */
 export function autoInstallHooks(env: NodeJS.ProcessEnv = process.env): boolean {
-  return readBoolean(env.PI_CLAUDE_SUPERVISOR_AUTO_INSTALL_HOOKS, true);
+  return readBoolean(env.PI_CLAUDE_SUPERVISOR_AUTO_INSTALL_HOOKS, true, "PI_CLAUDE_SUPERVISOR_AUTO_INSTALL_HOOKS");
 }