pi-claude-supervisor 0.5.1 → 0.5.3

package/docs/architecture.md

@@ -1,5 +1,7 @@
 # Architecture
 
+> The confirmed target is fully unattended local development with an independent remote/main boundary. Automatic mode implements the local editing, testing, repair, acceptance, Review and local-commit loop; unresolved work becomes a parked candidate. Legacy human/takeover APIs remain compatibility controls only. See [autonomy-target.md](autonomy-target.md).
+
 ## Control boundary
 
 Pi owns the `Supervisor`. The supervisor owns the task state machine, event log,
@@ -17,12 +19,16 @@ Supervisor -> Policy Gate -> WorkerAdapter -> child process
 ```
 
 The Worker cannot advance a task directly to `completed`. A clean worker exit
-moves the supervisor to `verifying`; only a successful verifier moves it to
-`completed`.
+moves the supervisor to `verifying`; only successful acceptance, independent Review,
+complete evidence and the configured local-commit boundary move it to `completed`.
+An unresolvable automatic path moves it to `blocked`, never to a publishable result.
 
 The extension keeps a registry of independent task sessions. Each session has
 its own Supervisor, watchdog, state machine and Worker handle, while the event
-log is shared and protected by an inter-process lock. Concurrent active sessions must use non-overlapping canonical working
+log is shared and protected by an inter-process lock. Once a task starts, the
+local development loop is intended to run unattended: the Worker may edit, test,
+repair and commit locally. Remote push and merge into `main`/an integration branch
+are outside Worker authority and cross an independent boundary. Concurrent active sessions must use non-overlapping canonical working
 directories/worktrees; same-cwd and parent/child cwd starts are rejected before
 spawn, including concurrent starts, to prevent uncoordinated edits. Pending starts
 are also awaited during Pi shutdown.
@@ -40,8 +46,11 @@ graph, roles, dependencies, bounded concurrency and structured handoff
 artifacts. Child Workers must communicate through validated evidence and event
 references rather than another Worker's control channel. Each child is accepted
 independently; the parent can complete only after aggregate acceptance and
-independent Review. Integration, conflict resolution, merge and publication
-remain explicit human-controlled operations in a separate integration worktree.
+independent Review. Integration and conflict resolution remain separate from the local development
+loop. The Worker cannot push remotely or merge into `main`/an integration branch;
+the independent integration boundary may combine read-only review, CI and an
+authorized integration action in a separate integration worktree. Rejection or
+shutdown leaves the candidate local.
 
 Recovery and shutdown must be graph-aware: a parent with an unknown child state
 cannot complete, cancellation must propagate within a bounded budget, and Pi
@@ -59,6 +68,13 @@ recovery, not by relaxing the current cwd lease rule.
 - idempotency keys for messages;
 - no session-resume claim.
 
+Worker capabilities distinguish two different properties. `persistentSession` means that a
+Worker can remain usable across a Pi disconnect/restart and can be explicitly re-adopted;
+`repairableSession` means that the current Supervisor can send another bounded turn after a
+verification/review result. Claude JSONL is repairable while attached but does not claim
+cross-restart resume. Tmux is both repairable and persistent. The Supervisor must never infer
+one capability from the other.
+
 This is a control-boundary fixture and headless transport. It does not emulate a
 terminal. Manual compatibility mode remains `process-pipe`; automatic mode
 (`PI_CLAUDE_SUPERVISOR_MODE=auto`) defaults to Claude JSONL and uses the CLI
@@ -68,7 +84,8 @@ screen-based.
 A worker exit automatically triggers cleanup, and terminal status waits for
 that cleanup to be confirmed (or reports a cleanup error). On Linux the adapter
 uses cgroup v2 automatically when the current user cgroup is writable; the
-`required` mode fails startup if cgroup attachment is unavailable. Cgroup
+`required` mode performs a preflight and fails before Claude starts if cgroup
+attachment or cleanup is unavailable. Cgroup
 cleanup kills descendants even when they call `setsid()` or create another
 process group. Attachment occurs immediately after spawn, so a worker that
 forks before attachment remains a documented startup-window limitation.
@@ -78,9 +95,11 @@ process-group cleanup. That fallback is not recursive: `setsid()` descendants
 can escape, and PID reuse between leader exit and cleanup is a host-level
 limitation. Production deployments that require an atomic boundary should use a
 service-manager scope, Job Object, pidfd-aware reaper, or equivalent supervisor.
-The Pi host installs graceful `SIGTERM`/`SIGINT` handlers, but `SIGSTOP` and
-`SIGKILL` cannot be handled; no orphan guarantee is claimed for those host-fatal
-signals.
+Pi owns graceful `SIGTERM`/`SIGINT` handling and invokes the extension's
+`session_shutdown` hook. The extension does not install a second `process.exit()`
+handler, avoiding races with Pi terminal restoration and other extensions. `SIGSTOP`
+and `SIGKILL` cannot be handled; no orphan guarantee is claimed for those
+host-fatal signals.
 
 ## tmux/PTY transport
 
@@ -109,9 +128,11 @@ For an owned initial turn, the adapter emits a synthetic `turn_completed` only
 after output activity and two stable input-prompt observations. Adopting an idle
 prompt remains inactive and emits no synthetic completion. This is a liveness
 signal, not proof that the task succeeded; the independent verifier remains
-mandatory. Interactive dialogs,
-trust prompts and ambiguous screens are not auto-approved. Human takeover sets a
-Supervisor gate that stops automatic messages until `resume-auto`.
+mandatory. Interactive dialogs, trust prompts and ambiguous screens are interpreted by
+the configured autonomy policy and recorded as evidence. An unresolved task is
+parked or failed as a non-publishable candidate rather than requiring a human to
+remain online. Human takeover remains an explicit kill/control path and stops
+automatic messages until `resume-auto`.
 
 `/supervise adopt-tmux` is explicit and validates the pinned pane's cwd and
 process identity before attaching. Every later input, capture and signal uses
@@ -130,10 +151,12 @@ idle -> starting -> running -> waiting -> running -> verifying -> completed
                   |       |       |             |
                   v       v       v             v
                 paused  failed  stopped        idle
+                              verifying -> stopped
 ```
 
-`stop` is available from `starting`, `running`, `waiting` and `paused`. Invalid
-transitions fail closed. Supervisor lifecycle operations and their state/event
+`stop` is available from `starting`, `running`, `waiting`, `paused` and `verifying`.
+A stop request from `verifying` is cleanup-authoritative and takes precedence over a
+verification result that has not yet been finalized. Invalid transitions fail closed. Supervisor lifecycle operations and their state/event
 updates run through one serial queue, so concurrent `poll`, `send`, `stop`,
 watchdog and shutdown work cannot produce duplicate terminal transitions. If a
 lifecycle event append fails after the state transition, it remains pending and
@@ -153,7 +176,9 @@ unconfirmed lease left by a crashed Pi is intentionally retained. Ordinary
 recovery refuses it; an operator may use `recover --takeover` only when the old
 owner is dead, the Worker process group is gone, and the lease independently
 reads a real empty cgroup boundary for the old Worker. Missing or unverifiable
-Worker evidence still requires manual cleanup rather than unsafe reclamation.
+Worker evidence retains the lease and parks the task rather than performing unsafe
+reclamation; later recovery can inspect or clean it without requiring an operator to
+be online.
 An explicitly adopted tmux session may hand off an existing lease only after
 its owner identity is no longer live and its canonical cwd, tmux session/socket,
 pane id, pane PID/start time, and pane command all match; ordinary starts
@@ -166,6 +191,21 @@ is alive; the extension periodically rechecks released sessions and removes the
 lease only after the pane is confirmed gone. If that check fails, the lease is
 retained rather than allowing a cwd overlap.
 
+Before model or Worker execution, automatic starts validate a full existing Git
+baseline, a non-bare worktree, a readable non-protected branch, the direct bare
+`claude`/`claude.exe` command name, JSONL transport, runtime state/lease directories
+and, when requested, the real writable cgroup-v2 boundary. The resolved Claude
+executable is checked for an operator-owned, non-writable path and then pinned by
+absolute path; `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` can pin the expected identity. The initial repository HEAD is captured, and the repository boundary immediately
+before the Worker adapter starts must report that exact same HEAD (recovery captures
+and compares its current HEAD separately while retaining the persisted baseline).
+The built-in process adapter invokes the same assertion through `preSpawnCheck`
+after cgroup/executable setup and immediately before `spawn`; a failed preflight
+is fail-closed and does not start Claude. Long acceptance commands and Reviewer
+sessions share an abort signal with the Supervisor, so operator stop/shutdown
+wins without waiting for a full check timeout. Progress hooks expose starting,
+Worker heartbeat, acceptance, review, repair and candidate/decision phases in the Pi UI.
+
 Startup owns an `AbortController` and passes its signal to the adapter. A stop
 or shutdown request aborts the controller and calls the adapter's out-of-band
 startup cleanup without waiting behind the serialized start operation. Each
@@ -186,7 +226,9 @@ must be treated as sensitive because worker output may contain repository data.
 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.
+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.
 Input writes are serialized with stop and are acknowledged through the stream
 write callback before their idempotency key is consumed. Writes have a bounded
 timeout, and `stop()` preempts a queued lifecycle operation by initiating adapter
@@ -199,20 +241,22 @@ unclean Pi restart, recovery is explicit: `/supervise recover [--takeover]
 <task-id>` restores
 the Decision Worker context and starts a new Claude Worker. It does not silently
 resume or duplicate a task. It does not poll to detect turn completion. A watchdog timer remains only as a deadlock safety
-fallback. Permission actions pass through `evaluatePermission` and can be
-approved or denied manually with `/supervise approve`; human escalation is sent
-to an outbound webhook when configured. If the Decision Worker API/model call
-fails, the system records `decision_worker_failed` and directly alerts the
-human operator; it does not attempt a second LLM fallback. Alert delivery is
-kept independent from event-log persistence so an audit write failure cannot
-suppress the alert.
+fallback. Permission and other actions pass through the configured autonomy policy and
+are recorded. The local development loop must not require synchronous human
+approval for ordinary actions; a task that cannot safely produce a candidate is
+parked or failed without granting remote/main authority. 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. Optional alert
+delivery remains independent from event-log persistence, but notification is not
+the control boundary.
 
 ## Acceptance, review and repair loop
 
 A task may provide a structured `TaskSpec` with `goal`, `scope`, `constraints`,
-`forbidden` and an ordered list of required or optional acceptance checks. A
+`forbidden`, an ordered list of required or optional acceptance checks, and
+`autonomy` (`unattended`, `requireLocalCommit`, `maxDecisionRetries`). A
 legacy plain-text task is normalized to a goal with the default `git diff
---check` acceptance check. The verifier runs every configured check with argv,
+--check` acceptance check and unattended defaults. The verifier runs every configured check with argv,
 bounded output and the same deterministic command policy; a Worker completion
 claim never substitutes for these results.
 
@@ -221,27 +265,40 @@ fresh read-only Reviewer session. The Reviewer receives the task specification,
 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
-output or a Reviewer API failure is a human-required condition.
+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.
 
 A `revise` result produces an audited repair round and sends a bounded corrective
-instruction to a still-live JSONL/tmux Worker. Checks and review then run again.
+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 escalate. A non-persistent Worker that has already exited
-cannot be silently recreated for repair; it remains failed/recoverable rather
-than replaying the original task.
+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
+a second `failed -> failed` transition.
+
+Repository evidence is baseline-relative: the Supervisor records the initial HEAD,
+then collects tracked committed/staged/unstaged changes, commit summaries after that
+baseline and untracked regular files through bounded, component-safe, no-symlink reads.
+Incomplete or truncated evidence is not sufficient for an independent `pass` verdict;
+automatic mode parks a task when the required git baseline or local commit is unavailable. Acceptance
+process output uses a bounded execution buffer before the smaller persisted evidence
+limit, so a normal large test report is not misclassified as a failed command.
 
 ## Deliberate non-goals
 
-- automatic merge/deploy/release;
-- unauthenticated inbound webhook commands; outbound notifications do not grant
-  permission and do not replace Pi human takeover;
-- treating an unknown Claude interactive question as safe to answer automatically;
-- bypassing Claude Code permissions;
+- giving the Worker remote push or main/integration merge authority;
+- unauthenticated inbound webhook commands; outbound notifications are optional,
+  do not grant permission and do not replace the remote/main independent boundary;
+- treating an unknown Claude interactive question as safe without task evidence or configured authorization;
+- bypassing the configured Claude Code/task permissions;
 - accepting model text as verification;
 - shell command interpolation;
-- automatic network denial or a fake domain allowlist. Network access follows
-  Claude's own permission model and the command policy; suspicious download-to-
-  shell patterns require human review rather than blanket network rejection;
+- a host-level network sandbox for manual integrations. Automatic mode does not admit
+  arbitrary custom executables: its supported Worker is direct Claude, which requests a
+  fail-closed Claude Code Bash sandbox with no outbound domains; command policy and
+  credential filtering remain defense in depth;
 - Claude CLI multi-version compatibility in the current stability milestone;
-- OS sandbox, low-privilege execution and network isolation in the current
+- full OS sandbox and low-privilege execution for custom Worker integrations in the current
   lifecycle milestone.

package/docs/automation-hardening-plan.md

@@ -0,0 +1,212 @@
+# 自动化稳定性与生命周期加固计划
+
+> 计划状态：Phase A–D、真实可编辑 repair/reacceptance、exact-head 独立只读 Review、受保护发布和本地无人值守闭环已完成；远程 push/main merge 仍是独立边界。
+> 基线：`v0.5.2` / `eefc7bc`
+> 真实验证：Claude Code `2.1.270`
+> 记录日期：2026-09-14
+
+## 1. 实际演练结论
+
+本轮真实演练完成了以下链路：
+
+```text
+真实 Claude Code Worker
+  -> Decision Worker 判断完成
+  -> argv/execFile 验收
+  -> 独立只读 Reviewer
+  -> P1/P2 阻塞发现
+  -> fail-closed / parked non-publishable candidate
+  -> Worker、Pi、lease 清理
+```
+
+六项验收全部通过：
+
+- `git diff --check`
+- `npm run check`
+- `npm run check:workflows`
+- `npm run test:pi`
+- `npm run test:install`
+- `npm run build`
+
+本次任务明确使用只读 Claude 权限并设置 `maxRepairRounds=0`，因此没有进入真实的
+repair/reacceptance。现有 replay 测试覆盖了模拟 repair，但没有覆盖真实
+`ProcessWorkerAdapter` 能力矩阵。
+
+完整事件证据位于本机临时目录：
+
+```text
+/tmp/pi-claude-supervisor-real-state-3/events.jsonl
+```
+
+### 1.1 Phase D：真实可编辑 repair/reacceptance
+
+在不触碰主仓库的临时 Git 工作树中，使用真实 Claude Code `2.1.270` 和
+`ProcessWorkerAdapter(mode=claude-jsonl, cgroup=off)` 完成了一个 bounded repair：
+
+- task：`cd39ed51-6003-4aad-8518-ebd6ab5de7e7`；`maxRepairRounds=1`。
+- Worker 首轮只创建 `add.mjs`；第一次 `node check.mjs` 按 drill 设计失败并给出
+  `repair required`。
+- Supervisor 发送 repair round 1；真实 Worker 创建 `add.test.mjs`。
+- 第二轮验收通过，独立只读 Reviewer 返回 `pass`，没有 human intervention。
+- 最终状态为 `completed`；Worker 状态为 `running=false`、`exitReason=stopped`、
+  `processGroupCleaned=true`；Decision Worker closure 为 `cleanupConfirmed=true`。
+- UI progress 覆盖 `starting -> worker -> acceptance(failed) -> repair -> worker ->
+  acceptance(passed) -> review -> completed`，并包含 Worker heartbeat。
+- Cwd lease 在 Worker 启动后记录了 PID/start time；结束后 `leaseAfterRelease=[]`，
+  未留下 lease。
+
+事件序列为：
+
+```text
+task_started -> worker_started -> worker_output -> worker_waiting -> decision_made
+-> acceptance_started -> acceptance_check_finished -> acceptance_result
+-> repair_requested -> worker_message_sent -> worker_output -> worker_waiting
+-> decision_made -> acceptance_started -> acceptance_check_finished -> acceptance_result
+-> review_started -> review_result -> review_finished -> verification_passed
+```
+
+证据归档位置（均在主仓库之外）：
+
+```text
+/tmp/pi-cs-repair4-runtime-X6MLob/events.jsonl
+/tmp/pi-cs-repair4-runtime-X6MLob/decision/
+/tmp/pi-cs-repair4-runtime-X6MLob/leases/   # 结束时为空
+/tmp/pi-cs-repair4.log
+```
+
+## 2. 正式发现与复现结果
+
+### P1-1：非持久 JSONL repair 会触发非法状态转换
+
+`ProcessWorkerAdapter` 的 JSONL Worker 没有 `persistentSession`，Supervisor 在验收前停止
+Worker；验收失败或 Reviewer `revise` 后，`requestRepair()` 先执行
+`verifying -> failed`，调用方又执行 `failed -> failed`。
+
+已用非持久 JSONL fake adapter 复现：
+
+```text
+InvalidTransitionError: Invalid supervisor transition: failed -> failed
+```
+
+根本修复不是把 JSONL 伪装成可跨重启恢复，而是把 Worker 能力拆成：
+
+- `persistentSession`：能否在 Pi 重启/断开后继续存在；
+- `repairableSession`：当前 Supervisor 生命周期内能否继续发送 repair turn。
+
+JSONL 可以是 `repairableSession=true`、`persistentSession=false`；tmux 两者都可以为
+`true`。终结和人工介入必须通过单一幂等路径完成，不能由 `requestRepair()` 和
+`finalizeVerification()` 重复转换终态。
+
+### P1-2：`verifying` 状态下 stop 无效
+
+当前 `stop()` 和 `#stopInternal()` 没有处理 `verifying`。已复现：
+
+```text
+before stop: verifying
+adapter.stop calls: 0
+after stop: verifying
+```
+
+结果可能是 Decision Worker 未关闭、Pi shutdown 不释放 cwd lease、后续任务被错误地
+判定为 cwd 冲突。
+
+修复要求：`verifying` 支持 stop、cleanup、`worker_stopped` 事件、Decision Worker
+关闭、closure callback 和 lease 回收；并确保人工 stop 优先于正在完成的 verification。
+
+### P2-1：paused Worker 仍触发 no-output watchdog
+
+`SIGSTOP` 后 Worker 本来就不会产生输出，但 watchdog 仍把 `paused` 纳入 no-output
+计算。使用 50ms timeout 暂停 1.25s 已复现 Worker 被停止。
+
+修复要求：暂停期间暂停 no-output 时钟；resume 时重建基准；wall-clock deadline 仍然
+保持累计，不允许通过 pause 绕过总时限。
+
+### P2-2：Reviewer diff evidence 遗漏 staged 和 untracked 内容
+
+当前使用 unstaged-only 的 `git diff`。已复现：
+
+```text
+status: M  tracked.txt / ?? new.txt
+diff:   (none)
+```
+
+修复要求：tracked 文件使用 `git diff HEAD`，额外安全读取 untracked regular files，
+拒绝 symlink，限制单文件和总证据大小；证据不完整或被截断时 Reviewer 不得返回
+`pass`。
+
+## 3.1 当前实现状态
+
+已完成并有确定性回归覆盖：
+
+- `repairableSession` 与 `persistentSession` 已分离；JSONL 仅支持当前进程内 repair，tmux 才声明持久恢复。
+- `verifying` 的 stop/shutdown 使用统一 cleanup/finalize 路径，人工 stop 优先于验收结果，cleanup 不确定时保留恢复记录。
+- paused Worker 不消耗 no-output watchdog；resume 重建 no-output 基准，但不重置累计 deadline。
+- Reviewer evidence 使用任务 baseline-relative diff、baseline 后 commit summaries、受限 untracked regular-file 内容、路径组件/symlink 门禁，并对 incomplete/truncated fail-closed。
+- Acceptance 子进程、证据收集和 Reviewer 共享 abort signal；Pi UI 可看到 startup、Worker heartbeat、acceptance、review、repair 和 candidate/decision phases。
+- 自动模式启动前检查运行目录、cwd、Worker 可执行文件、transport 依赖和 required cgroup；显式
+`process-pipe` 和 `tmux` 不再进入自动模式，后者保留为手动 PTY transport。
+- Reviewer/Decision Worker 只解析 assistant message 边界的最终文本；permission pending 会在自动响应后清除，候选状态不会被错误解除；扩大的 exec buffer 避免普通大测试报告被误判为命令失败。
+
+本轮已完成：
+
+- 普通本地命令和权限不再进入同步人工审批；Decision Worker 的无效输出、API 错误、Reviewer 失败、P0/P1、重复 finding、证据不完整和预算耗尽会进入 `blocked` 候选。
+- TaskSpec 和环境变量提供 unattended/local-commit/Decision retry 控制；Worker 可在本地修改、测试、修复并提交，push、merge、发布和破坏性边界仍硬拒绝并写入审计。
+- replay、候选通知和 baseline-relative commit evidence 覆盖正常完成、修复、歧义和挂起；保持独立 Review、保护 CI、Release Please 和 provenance 发布边界。
+
+## 4. 实施顺序
+
+### Phase A：生命周期和能力模型（最高优先级）
+
+1. 增加 `repairableSession` capability。
+2. JSONL 在当前 Supervisor 生命周期内支持 repair，仍不声明跨重启恢复。
+3. 重构 repair/finalize/candidate 分支，保证终态转换和 Decision Worker closure 幂等。
+4. `verifying` 支持 stop/shutdown，保留 cleanup 不确定时的 lease。
+5. 增加真实非持久 adapter 和 stop-from-verifying 测试。
+
+### Phase B：watchdog 与证据完整性
+
+1. paused no-output 时钟暂停，resume 重建基准。
+2. 记录任务开始时的 HEAD；baseline-relative diff 覆盖 committed/staged/unstaged tracked 修改，并记录 baseline 后 commits。
+3. 安全收集 untracked regular-file evidence，防 symlink 和路径逃逸。
+4. evidence truncation/incomplete 生成不可发布候选并自动挂起，不能自动 `pass`。
+
+### Phase C：自动化协议和运行前保护
+
+1. Reviewer/Decision Worker 按 assistant message 边界解析最终响应，不拼接所有工具回合文字。
+2. 自动模式启动前执行 transport、Claude、cgroup、state/lease 目录 preflight。
+3. 区分 Worker heartbeat、验收、Reviewer、repair 阶段，并提高实时可观测性。
+4. 修复自动 permission 响应后的 stale pending request，并使本地决策不会依赖同步 human gate。
+5. 清理 Pi extension 自己安装的 signal handler，避免与 Pi `session_shutdown` 竞争。
+
+### Phase D：回归、真实演练和发布门禁
+
+1. 扩展 acceptance/replay/capability 矩阵。
+2. 在临时 worktree 中使用真实 Claude 做一次受控 repair/reacceptance；禁止触碰主仓库。
+3. 运行 `npm run check`、Pi/npm smoke、build 和真实只读 review。
+4. 只有独立 Reviewer `pass`、所有检查通过、cleanup/lease 证据完整后，才生成可交付本地候选；远程 push 和 main/integration merge 仍必须经过独立边界。
+
+## 5. 验收矩阵
+
+| 场景 | 预期 |
+|---|---|
+| JSONL Worker alive + P2 revise | 发送一次 bounded repair，重新验收 |
+| JSONL Worker 已退出 + 验收失败 | 不抛非法 transition，记录 `verification_failed`，生成不可发布候选 |
+| Reviewer `human` + Worker alive | 不自动完成；按预算修复或挂起 `blocked` 候选，不要求人工在线 |
+| Reviewer `human` + Worker 已退出 | 完成 cleanup、关闭 Decision Worker、保留 recoverable/parked record |
+| `stop()` from `verifying` | `stopped`、cleanup confirmed 后释放 lease |
+| shutdown from `verifying` | 不泄漏 Worker、Decision Worker 或 cwd lease |
+| pause 超过 no-output timeout | 仍保持 paused |
+| resume 后无输出 | 从 resume 时刻重新计算 timeout |
+| staged + untracked 修改 | Reviewer evidence 包含两者 |
+| evidence 截断/不可验证 | Reviewer 只能阻止 `pass`，候选自动挂起 |
+| malformed/multi-message model output | 不误判为 pass/action |
+| preflight 失败 | Claude 尚未启动前 fail-closed |
+
+## 6. 明确不改变的安全边界
+
+- Reviewer 继续只允许 `read`、`grep`、`find`、`ls`。
+- 验收命令继续使用 argv 和 `execFile`，不经过 shell 拼接。
+- 不伪造 Claude `--resume`；`resumeSession` 仍然是明确能力声明。
+- Worker 不得远程 push 或 merge 到 main/integration；发布仍走独立受保护 workflow。
+- 不允许多 Worker 共享同一可写 worktree。
+- P0/P1、重复 finding、超时、API 错误、无效输出和不完整证据继续 fail-closed，并自动生成不可发布/挂起候选，而不是要求同步人工响应。

package/docs/autonomy-target.md

@@ -0,0 +1,127 @@
+# Confirmed autonomy target
+
+> Owner-confirmed product requirement: local development is fully unattended; code entering a remote repository or the main/integration branch must cross an independent boundary.
+
+This document is authoritative for the autonomy direction. Earlier planning text that treats a
+human as a synchronous approval step for ordinary local development is historical conservative
+baseline text and must not be used to add a new gate to the local development loop.
+
+## 1. Target operating model
+
+Once a task has been started with its task specification, the local development loop may run
+without a human watching it:
+
+```text
+Worker edits and runs local commands
+  -> acceptance checks
+  -> independent Reviewer
+  -> bounded repair/reacceptance
+  -> local commit/candidate artifact
+  -> independent remote/main integration boundary
+```
+
+The Supervisor may continue, answer, repair, test, review and commit locally. A human is not a
+synchronous dependency for ordinary progress, routine ambiguity, or a normal failed test.
+
+The system must still provide a kill switch, bounded execution, cleanup verification and a
+complete audit trail. These are reliability and containment mechanisms, not requests for a human
+to approve every development action. Automatic mode also records and revalidates a full existing
+repository baseline, captures the startup HEAD and requires that exact HEAD again at
+final pre-spawn, requires a non-protected branch and a pinned operator-owned direct Claude
+JSONL Worker, and by default requires a local commit before a candidate is deliverable.
+
+## 2. Hard authority boundary
+
+Automatic Worker supervision uses the structured JSONL transport; the interactive tmux transport
+remains manual-only because it has no equivalent permission-response boundary. The Worker and local
+automation do **not** receive authority or credentials for:
+
+- pushing code to a remote repository;
+- merging into `main` or another protected integration branch;
+- starting automatic candidate work directly on a protected integration branch; repositories with a
+  branch use a non-protected local branch for unattended work;
+- inheriting Git/GitHub/package credential helpers or explicitly selected remote credentials in
+  automatic mode.
+
+A completed local task is a candidate until it passes the independent boundary. That boundary may
+be a later read-only review, CI policy, a maintainer action, or an explicit shutdown/rejection.
+The Worker must not be able to bypass it through a prompt, a local decision, or a model response.
+
+This is the required authority boundary. Automatic mode admits only the bare direct Claude
+command name and pins its operator-owned resolved executable because its fail-closed Claude Code
+sandbox is part of the supported boundary; explicit paths and arbitrary custom executables must
+use manual mode or an independently hardened integration. No additional
+synchronous human-approval boundary should be invented for local editing, local tests, local
+commits, or local repair unless the task owner explicitly configures one.
+
+## 3. Unattended decision behavior
+
+The Decision Worker should resolve ordinary development decisions from the task specification,
+repository evidence and configured task policy, and record its assumptions and actions. It should
+not turn every uncertainty into an interactive human prompt.
+
+If the system cannot safely reach a candidate, it may automatically retry within the configured
+budget, mark the task blocked/failed, preserve the worktree and evidence, or park it for later
+inspection. “Parked for later inspection” is not the same as requiring a human to be online before
+other tasks can proceed.
+
+A task that reaches `blocked`, `review_pending` or `candidate_failed` must not be pushed or merged.
+The same rule applies to a ready local candidate until the independent remote/main boundary accepts it.
+It may be resumed, repaired or discarded later without weakening the remote/main boundary.
+
+## 4. Acceptance and independent review
+
+Acceptance and Reviewer remain automatic parts of the local loop:
+
+- run all required checks;
+- collect complete baseline-relative status, commit and untracked evidence;
+- run the independent read-only Reviewer;
+- apply bounded repair rounds;
+- re-run acceptance and Review;
+- produce a candidate with its evidence and assumptions.
+
+Reviewer findings are first an automatic repair input. Exhausted budgets, incomplete evidence,
+invalid output, duplicate findings or an unresolved finding produce a non-publishable
+candidate/parked task; they do not by themselves require a synchronous takeover notification.
+
+## 5. Notifications and shutdown
+
+Progress, assumptions, failures and candidate readiness must be recorded in the event log. Live
+notifications are optional delivery policy, not the local development control protocol.
+
+Immediate shutdown remains appropriate for technical containment failures such as an unverified
+Worker cleanup boundary, corrupted control state or an explicit operator kill. The system should
+stop or park safely and retain evidence; it must not silently grant remote or main-branch access.
+
+## 6. Current implementation
+
+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
+Decision Worker request retries. Automatic startup rejects non-Git/detached/bare/protected
+repository states, malformed baselines, startup-HEAD races, non-JSONL transports and
+non-Claude or untrusted executable identities before Worker startup. The resolved
+executable identity is persisted with the Decision Worker recovery record and must match
+again during recovery.
+
+Legacy `humanRequired`, takeover and approval fields remain for compatibility and explicit operator
+control. They are not entered by ordinary uncertainty, and a legacy approval object cannot override
+the deterministic remote push/main merge denial. The existing independent Review and protected
+CI/release paths remain the final external checks. Built-in automatic Claude workers request a fail-closed Claude Code Bash sandbox with no
+outbound domains; automatic command policy and credential filtering remain defense in depth.
+Full host-level sandboxing for custom Worker integrations is separate hardening work.
+
+## 7. Explicit non-goals of this target
+
+This target does not authorize:
+
+- remote push from the Worker;
+- merge into `main` from the Worker;
+- bypassing the independent integration boundary;
+- silently treating incomplete evidence as success;
+- claiming that a failed or parked task completed.
+
+Coordinated multi-Worker scheduling, OS sandboxing and broader CLI compatibility remain separate
+engineering milestones. They must not be used to add synchronous human approval to the local
+development loop.