pi-claude-supervisor 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented here.
 
+## [0.5.2](https://github.com/btnalit/pi-claude-supervisor/compare/v0.5.1...v0.5.2) (2026-09-14)
+
+
+### Bug Fixes
+
+* harden automatic review lifecycle ([fefa5c5](https://github.com/btnalit/pi-claude-supervisor/commit/fefa5c5b39fd2411b5e82df384074983252263ca))
+
 ## [0.5.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.5.0...v0.5.1) (2026-09-14)
 
 
@@ -18,6 +25,18 @@ All notable changes to this project will be documented here.
 
 ## [Unreleased]
 
+### Hardening implemented in working tree (not yet released)
+
+- Split JSONL in-process `repairableSession` from cross-restart `persistentSession` and eliminate duplicate terminal transitions.
+- Make `verifying` stop/shutdown cleanup authoritative, with abortable acceptance and Reviewer operations.
+- Pause and rebase the no-output watchdog clock across pause/resume while retaining the cumulative deadline.
+- Include staged, unstaged and bounded untracked evidence in independent Review, with symlink/path safety and fail-closed completeness.
+- Harden assistant-message output framing, startup/runtime preflight, permission gates, bounded acceptance buffers and lifecycle progress reporting.
+
+### Remaining hardening gate
+
+- Complete the exact-head independent read-only Review; the real editable Claude `2.1.270` repair/reacceptance drill and cleanup/lease evidence are recorded in `docs/automation-hardening-plan.md`.
+
 ### Added
 
 - Structured task specifications with Goal, scope, constraints, forbidden actions and multiple argv-based acceptance checks.

package/README.cn.md

@@ -8,7 +8,12 @@
 
 用于 Pi 的 Claude Code Worker 监督扩展。MVP 中 Pi 负责生命周期、状态机、策略门和独立验收；Worker 只是被显式启动的子进程。
 
-> 当前默认 transport 是无额外依赖的 process pipe，不是 PTY。已新增可选 Claude JSONL framing，并通过基础 prompt、多轮和 resume Spike。当前优先保证生命周期、进程组清理、恢复和独立验收；低权限用户、OS sandbox 与网络隔离不作为当前主线，按明确授权和宿主机策略运行，后续再做安全加固。
+> `v0.5.1` 已发布为单 Worker recovery 基线。默认手动 transport 是无额外依赖的
+> process pipe，不是 PTY；自动模式只使用 Claude JSONL 或 tmux。当前工作树已实现
+> repairable/persistent 能力拆分、可取消验收/Reviewer、证据完整性门禁、启动前
+> preflight 和阶段进度通知；真实 Claude Code `2.1.270` 允许编辑的
+> repair/reacceptance 演练已在隔离临时 worktree 通过，剩余发布门禁是 exact-head
+> 独立只读 Review。低权限用户、OS sandbox 与网络隔离继续延期。
 
 ## 关键安全边界
 
@@ -16,12 +21,13 @@
 - 不经过 shell 启动子进程。
 - Worker 只继承最小环境；凭据必须由调用方显式传入。
 - 破坏性命令和绕过权限的 Worker 参数默认拒绝；需要复核的启动命令会请求用户批准，不会一律拒绝。
-- Linux 上优先使用可写的 cgroup v2 清理后代进程，包括 `setsid()` 后代；不可用时回退到进程组清理。需要强制失败闭环时，embedding 集成可使用 `cgroupMode: "required"`。
+- Linux 上优先使用可写的 cgroup v2 清理后代进程，包括 `setsid()` 后代；不可用时回退到进程组清理。需要强制失败闭环时，embedding 集成可使用 `cgroupMode: "required"`，并会在 Claude 启动前执行 preflight。
 - 普通联网查询不因联网本身被拒绝；下载后直接交给 shell 等高风险模式仍需人工复核。
 - Worker 声称完成只会进入 `verifying`，不能作为成功证据。
 - 默认独立验收命令为 `git diff --check`。
 - 扩展运行时不执行 merge、deploy、release 或 publish；仓库 Release 只会在维护者合并 Release Please PR 且 CI 门禁全部通过后自动发布。
-- 默认 4 小时总时限、20 分钟无输出 watchdog 超时即停止 Worker，适合长程开发任务；嵌入调用方可将对应选项设为 `0` 关闭。
+- 默认 4 小时总时限、20 分钟无输出 watchdog 超时即停止 Worker；paused 期间不消耗无输出预算，resume 会重建基准但不会重置总时限。嵌入调用方可将对应选项设为 `0` 关闭。
+- 验收命令、仓库证据收集和独立 Reviewer 共用 abort signal，人工 stop/shutdown 不必等待完整超时。
 
 ## 安装和使用
 
@@ -105,9 +111,12 @@ Worker 应使用 `adopt-tmux`，而不是 takeover。
 `v0.5.0` 已完成并发布“多命令验收—独立只读 Reviewer—结构化修复轮次—再次验收”闭环。
 任务可通过 API 或 JSON spec 提供 `goal`、`scope`、`constraints`、`forbidden` 和多个
 `acceptance` 命令；旧的纯文本任务继续使用默认 `git diff --check`。Reviewer 只能使用
-`read`、`grep`、`find`、`ls`，不会修改工作树或批准权限。短期剩余门禁是固定 Claude Code
-`2.1.270` 的重复稳定性统计和 recovery 测试；协同多 Worker 属于后续独立开发阶段，
-暂不把多版本兼容、sandbox、低权限和网络隔离作为本阶段门禁。
+`read`、`grep`、`find`、`ls`，不会修改工作树或批准权限。当前加固要求 HEAD-relative
+tracked diff 和受限 untracked evidence 完整，P0/P1 或重复 finding 必须人工处理；自动模式
+拒绝显式 process-pipe，并在模型执行前检查目录、可执行文件、依赖和 cgroup。剩余门禁是
+固定 Claude Code `2.1.270` 隔离 worktree 的真实 repair/reacceptance 已通过，当前只剩
+exact-head 独立只读 Review；协同多 Worker 属于后续独立开发阶段，暂不把 sandbox、低权限
+和网络隔离作为本阶段门禁。
 
 ### tmux/PTY 交互模式
 

package/README.md

@@ -10,11 +10,15 @@ A policy-gated [Pi](https://pi.dev) extension for supervising a Claude Code work
 The MVP keeps Pi in control of lifecycle, state, policy and verification while the
 worker remains an explicitly started child process.
 
-> **MVP status:** the default transport is dependency-free process pipes, not PTY.
-> An opt-in Claude JSONL framing mode has passed basic prompt, multi-turn and
-> resume fixtures. The current priority is signal, shutdown, process-group and
-> recovery validation; OS sandbox, low-privilege execution and network isolation
-> are deferred hardening items and are not required by the current MVP plan.
+> **Release status:** `v0.5.1` is the released single-Worker recovery baseline. The
+> default manual transport is dependency-free process pipes, not PTY. Automatic
+> supervision uses Claude JSONL or tmux, and the current working-tree hardening
+> adds 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 has passed in an
+> isolated temporary worktree; the exact-head independent review is the remaining
+> release gate. OS sandbox, low-privilege execution and network isolation remain
+> deferred.
 
 ## Safety boundary
 
@@ -27,7 +31,8 @@ worker remains an explicitly started child process.
 - Verification is an independent host command (default: `git diff --check`).
 - The extension never performs merge, deploy, release, or publish at runtime. Repository releases are automated only after a maintainer merges a Release Please PR and the full CI gate passes.
 - 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 the adapter's `cgroupMode: "required"` for a fail-closed integration.
+- 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
@@ -114,12 +119,15 @@ 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. The next gates are pinned Claude Code `2.1.270` stability statistics
-and explicit session recovery. Coordinated multi-worker scheduling is a later
-milestone; CI will use deterministic fake Workers/replay fixtures, and real
-multi-worker Claude tests will remain authenticated manual Spikes. CLI
-multi-version compatibility, sandboxing, low-privilege execution and network
-isolation are not part of this milestone.
+permissions. The current hardening also requires complete HEAD-relative tracked and
+bounded untracked evidence, rejects P0/P1 or repeated findings, and only repairs a
+live `repairableSession` Worker. Automatic mode rejects explicit `process-pipe` and
+preflights runtime prerequisites. The real pinned Claude Code `2.1.270` disposable repair/reacceptance run has passed;
+the remaining gate is the exact-head independent review.
+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. CLI multi-version compatibility, sandboxing, low-privilege execution
+and network isolation are not part of this milestone.
 
 Automatic mode persists the Pi Decision Worker session under the configured state
 directory. After an unclean Pi restart, `/supervise sessions` lists recoverable

package/docs/architecture.md

@@ -59,6 +59,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 +75,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 +86,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
 
@@ -130,10 +140,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
@@ -166,6 +178,14 @@ 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 preflight the validated cwd,
+worker executable, transport dependencies, runtime state/lease directories and,
+when requested, the real writable cgroup-v2 boundary. 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 human-gate 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 +206,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
@@ -224,11 +246,19 @@ conversation or control channel. It can inspect only `read`, `grep`, `find` and
 output or a Reviewer API failure is a human-required condition.
 
 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 escalate. 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 human-review 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 HEAD-relative: tracked staged and unstaged changes are collected together,
+and untracked regular files are included through bounded, component-safe, no-symlink reads. Incomplete or
+truncated evidence is not sufficient for an independent `pass` verdict. 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
 

package/docs/automation-hardening-plan.md

@@ -0,0 +1,211 @@
+# 自动化稳定性与生命周期加固计划
+
+> 计划状态：Phase A–D 已在当前工作树实现；真实可编辑 repair/reacceptance 已通过，待 exact-head 独立只读 Review 作为发布前最后门禁
+> 基线：`v0.5.1` / `26443f0`
+> 真实验证：Claude Code `2.1.270`
+> 记录日期：2026-09-14
+
+## 1. 实际演练结论
+
+本轮真实演练完成了以下链路：
+
+```text
+真实 Claude Code Worker
+  -> Decision Worker 判断完成
+  -> argv/execFile 验收
+  -> 独立只读 Reviewer
+  -> P1/P2 阻塞发现
+  -> fail-closed / human intervention
+  -> 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 使用 `git diff HEAD`、受限 untracked regular-file 内容、路径组件/symlink 门禁，并对 incomplete/truncated fail-closed。
+- Acceptance 子进程、证据收集和 Reviewer 共享 abort signal；Pi UI 可看到 startup、Worker heartbeat、acceptance、review、repair 和 human phases。
+- 自动模式启动前检查运行目录、cwd、Worker/tmux 可执行文件、transport 依赖和 required cgroup；显式 `process-pipe` 不再进入自动模式。
+- Reviewer/Decision Worker 只解析 assistant message 边界的最终文本；permission pending 会在自动和人工响应后清除，独立 human gate 不会被错误解除；扩大的 exec buffer 避免普通大测试报告被误判为命令失败。
+
+仍待完成：
+
+- 对当前 exact head 执行最后一次独立只读 Review；该 Review 必须不编辑、不运行命令、不发送 Worker 输入、不提交或发布。
+- Review 通过且完整质量门禁再次通过后，才允许人工决定是否提交、合并或发布；本轮仍不自动 release/publish。
+
+## 4. 实施顺序
+
+### Phase A：生命周期和能力模型（最高优先级）
+
+1. 增加 `repairableSession` capability。
+2. JSONL 在当前 Supervisor 生命周期内支持 repair，仍不声明跨重启恢复。
+3. 重构 repair/finalize/human 分支，保证终态转换和 Decision Worker closure 幂等。
+4. `verifying` 支持 stop/shutdown，保留 cleanup 不确定时的 lease。
+5. 增加真实非持久 adapter 和 stop-from-verifying 测试。
+
+### Phase B：watchdog 与证据完整性
+
+1. paused no-output 时钟暂停，resume 重建基准。
+2. HEAD-relative diff 覆盖 staged/unstaged tracked 修改。
+3. 安全收集 untracked regular-file evidence，防 symlink 和路径逃逸。
+4. evidence truncation/incomplete 强制 human。
+
+### 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 证据完整后，才允许人工
+   决定是否提交、合并或发布。
+
+## 5. 验收矩阵
+
+| 场景 | 预期 |
+|---|---|
+| JSONL Worker alive + P2 revise | 发送一次 bounded repair，重新验收 |
+| JSONL Worker 已退出 + 验收失败 | 不抛非法 transition，记录 `verification_failed`，升级人工 |
+| Reviewer `human` + Worker alive | 保持 Worker 可人工接管，不自动继续 |
+| Reviewer `human` + Worker 已退出 | 完成 cleanup、关闭 Decision Worker、保留 recoverable 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 只能返回 human |
+| malformed/multi-message model output | 不误判为 pass/action |
+| preflight 失败 | Claude 尚未启动前 fail-closed |
+
+## 6. 明确不改变的安全边界
+
+- Reviewer 继续只允许 `read`、`grep`、`find`、`ls`。
+- 验收命令继续使用 argv 和 `execFile`，不经过 shell 拼接。
+- 不伪造 Claude `--resume`；`resumeSession` 仍然是明确能力声明。
+- 不自动 merge、deploy、release 或 publish。
+- 不允许多 Worker 共享同一可写 worktree。
+- P0/P1、重复 finding、超时、API 错误、无效输出和不完整证据继续 fail-closed。

package/docs/engineering-plan.md

@@ -1,6 +1,6 @@
 # Pi Claude Supervisor 完整方案
 
-> 文档状态：`v0.5.0` 已发布 / 后续开发路线图
+> 文档状态：`v0.5.1` 已发布；Phase A–D 加固和真实 repair/reacceptance 已在当前工作树实现；待 exact-head 独立只读 Review 门禁
 > 目标项目目录：`pi-claude-supervisor`  
 > 适用对象：W、项目负责人、实现人员、评审人员
 
@@ -36,7 +36,7 @@ Claude Code Worker
 4. Supervisor 因误判导致无限循环、危险操作或不可审计的修改。
 5. 人工无法随时接管或恢复任务。
 
-**当前状态：`v0.5.0` 已完成“验收—独立 Review—自动修复—再验收”闭环并正式发布。下一阶段先完成固定 Claude Code `2.1.270` 的稳定性统计和恢复语义，再推进有边界的多 Worker 协作；低权限用户、OS sandbox 与网络隔离仍是后续安全加固，不作为当前主线硬性阻塞。**
+**当前状态：`v0.5.1` 已正式发布，已完成固定 Claude Code `2.1.270` 稳定性统计、单 Worker recovery、真实只读 Review drill 和隔离临时 worktree 的允许编辑 repair/reacceptance drill。当前工作树已落实 repairable/persistent 能力拆分、verifying stop、paused watchdog、完整 repository evidence、可取消验收/Reviewer、启动 preflight、权限门禁修复和阶段进度通知；下一项也是发布前最后硬门禁的是当前 exact head 的独立只读 Review。协同多 Worker 仍延期；低权限用户、OS sandbox 与网络隔离仍是后续安全加固。**
 
 ---
 
@@ -1030,3 +1030,25 @@ Reviewer 必须使用独立 Pi session，只允许 `read`、`grep`、`find`、`l
 - CLI 多版本兼容矩阵；
 - OS sandbox、低权限执行、网络隔离/allowlist；
 - 更深的供应链、SBOM、密钥隔离和生产监控。
+
+## 22. v0.5.1 真实演练后的自动化加固计划
+
+`v0.5.1` 发布后的真实 Claude Code `2.1.270` 演练完成了
+Worker → 验收 → 独立 Reviewer → fail-closed 人工介入链路。验收六项全部通过，
+但发现两个 P1 和两个 P2 生命周期/证据问题。正式记录、复现结果、实施阶段和门禁
+见 [`docs/automation-hardening-plan.md`](automation-hardening-plan.md)。
+
+本轮实现顺序固定为：
+
+1. **生命周期与能力模型**：拆分 `persistentSession` 与 `repairableSession`，修复非持久
+   JSONL repair 的非法终态转换，并支持 `verifying` 状态的 stop/shutdown；
+2. **watchdog 与证据完整性**：暂停 no-output 时钟，补齐 HEAD-relative staged/unstaged
+   diff 和安全的 untracked evidence；
+3. **自动化协议**：按 assistant message 边界解析 Reviewer/Decision Worker 输出，增加
+   启动 preflight、可观测 heartbeat、permission gate 一致性和 signal 生命周期；
+4. **验证门禁**：已补齐真实 capability 矩阵并完成隔离 worktree 的真实
+   repair/reacceptance 演练；当前 exact-head 独立 Reviewer 通过前不进行任何合并或发布。
+
+本轮不放宽以下边界：Reviewer 仍只读，验收仍使用 argv/`execFile`，不伪造 Claude
+`--resume`，不自动 merge/deploy/release，P0/P1、重复 finding、超时、API 错误和不完整
+证据继续 fail-closed。多 Worker 协作继续后置。

package/docs/testing.md

@@ -65,7 +65,10 @@ cause a later run to fail closed as human-required after the bounded Decision
 Worker or Reviewer timeout; this is evidence for the manual spike only, not a CI
 guarantee.
 The extension persists each automatic Decision Worker session as Pi JSONL plus a
-0600 task mapping. Recovery is explicit and safe: after an unclean Pi restart,
+0600 task mapping. Automatic startup preflights the state/lease directories, cwd,
+worker executable, transport dependency and required cgroup boundary before model
+execution. Progress callbacks expose the current phase and periodic Worker
+heartbeat. Recovery is explicit and safe: after an unclean Pi restart,
 `/supervise sessions` shows the task as `recoverable`, and `/supervise recover
 [--takeover] <task-id>` restores the Decision Worker history before starting a new
 Claude Worker. `--takeover` is accepted only when the old Pi owner is dead, the
@@ -120,7 +123,9 @@ escalation is outbound-only through `PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL`;
 approval callbacks are deliberately not accepted without a separately
 authenticated endpoint.
 
-The tmux transport is selected with `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. Before
+The tmux transport is selected with `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`.
+Automatic mode rejects an explicit `process-pipe` transport; use JSONL or tmux for
+bounded decisions and repair. Before
 release, verify: private-socket attach, multi-line paste, prompt stability while
 Claude is busy, trust/permission dialog takeover, duplicate send prevention, pane
 replacement refusal, pause/resume, owned-session stop, adopted-session
@@ -137,29 +142,38 @@ response.
 
 The automated adapter matrix covers external `SIGTERM`, `SIGINT`, `SIGKILL`,
 `SIGSTOP`/`SIGCONT`, SIGTERM refusal/escalation, leader-early-exit descendant
-cleanup, required cgroup cleanup of a `setsid()` descendant, repeated stop,
-spawn failure, output truncation, blocked stdin write timeouts, and immediate
-JSONL results. The Supervisor matrix also covers
-retrying failed lifecycle events, preserving startup event order, stopping under
-persistent timeout-event failure, and restoring output after event-log failure. The Supervisor matrix covers startup rejection, externally terminated
-workers, lifecycle serialization and stop races.
+cleanup, required cgroup bootstrap containment of a pre-attachment detached
+and `setsid()` descendant, repeated stop, spawn failure, output truncation,
+blocked stdin write timeouts, and immediate JSONL results. The Supervisor
+matrix also covers retrying failed lifecycle events, preserving startup event
+order, stopping under persistent timeout-event failure, and restoring output
+after event-log failure. The Supervisor matrix covers startup rejection,
+externally terminated workers, lifecycle serialization and stop races.
 
 Before release, manually test at least: immediate crash, hung process, malformed
 output, duplicate send, send/exit race, Pi `SIGTERM`/`SIGINT` shutdown,
 verification failure, blocked stdin writes/stop preemption, corrupt event-log
 tails, and descendants that call `setsid()` when cgroup mode is unavailable (expected
-fallback limitation). The cgroup test proves cleanup after attachment but does
-not eliminate the post-spawn attachment window. `SIGSTOP` and `SIGKILL` of the Pi host cannot be handled;
-verify and document the resulting orphan behavior.
+fallback limitation). In cgroup mode, a small bootstrap joins the cgroup before
+launching Worker code, and cleanup also validates and reaps the detached process
+group; this closes the post-spawn attachment window. `SIGSTOP` and `SIGKILL` of
+the Pi host cannot be handled; verify and document the resulting orphan behavior.
 Default behavior must be fail-closed and leave no orphaned worker process within
 the managed process group.
 
 ## Near-term automation acceptance gate
 
 The `v0.5.0` implementation of the acceptance—independent Review—repair—reacceptance
-loop is shipped. The remaining gate focuses on real stability for the pinned
-Claude Code `2.1.270` CLI. It does not add a multi-version matrix or wait for
-OS sandbox, low-privilege or network-isolation work.
+loop is shipped. The `v0.5.1` real read-only drill reached acceptance and independent
+Review, then correctly stopped at human intervention after two P1 and two P2 findings.
+A separate real edit-capable Claude Code `2.1.270` drill then exercised one bounded
+acceptance failure, repair turn, reacceptance and independent Reviewer `pass` in an
+isolated temporary worktree. The current hardening plan and evidence paths are recorded
+in [`docs/automation-hardening-plan.md`](automation-hardening-plan.md). Deterministic
+coverage now includes repairable-vs-persistent capability assertions, cancellation
+of acceptance commands, stop-from-verifying precedence, paused watchdog baselining,
+staged/untracked evidence and untracked symlink rejection. The remaining release gate
+is the exact-head independent read-only review.
 
 ### Acceptance and Reviewer fixtures
 
@@ -170,6 +184,9 @@ Deterministic tests must cover:
 - independent read-only Reviewer pass/revise/human results;
 - invalid Reviewer JSON and Reviewer API failure escalating to human;
 - repair rounds, repeated finding detection, P0/P1 escalation 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;
 - completion being impossible without passing all required checks and review.
 
 Reviewer sessions use only `read`, `grep`, `find` and `ls`; they must not modify
@@ -187,14 +204,17 @@ The adapter/replay matrix must cover:
 - duplicate Supervisor idempotency keys without duplicate input;
 - stop, SIGTERM, SIGINT and Pi shutdown while a JSONL request is active;
 - ordinary completion, low-risk permission allow, AskUserQuestion deny-to-text,
-  multi-turn, verifier failure/repair, takeover and explicit recovery.
+  multi-turn, verifier failure/repair, takeover and explicit recovery;
+- staged and untracked repository evidence, symlink rejection and truncation fail-closed;
+- paused watchdog behavior and resume-time no-output rebasing;
+- assistant-message-bounded Reviewer and Decision Worker output parsing.
 
 Real Claude tests remain authenticated manual Spikes and are pinned to
 `2.1.270`; they are not part of normal CI. Normal CI runs deterministic fake
-Worker and replay fixtures. The short-term stability gate is still pending and
-must include ten consecutive ordinary automatic runs and at least five runs each
-for permission and question handling, with no duplicate action, false completion
-or unreaped Worker.
+Worker and replay fixtures. The pinned stability matrix is the compatibility evidence
+for this release line; any future CLI change must rerun ten consecutive ordinary
+automatic runs and at least five runs each for permission and question handling, with
+no duplicate action, false completion or unreaped Worker.
 
 ## Future multi-worker test plan
 
@@ -218,3 +238,23 @@ Required deterministic and integration coverage:
 The multi-worker gate should be added only after the pinned single-worker stability
 and recovery gates pass. CI should use fake Workers and replay fixtures; authenticated
 Claude multi-worker Spikes remain manual and version-pinned.
+
+## Live drill and hardening gate
+
+A live review must record the exact Claude executable/version, transport, cgroup mode,
+permission flags, task id, acceptance result, Reviewer result, cleanup status and cwd lease
+status. A human-required result is a valid safety outcome and must not be converted into a
+pass by retrying the same task automatically.
+
+For the hardening release, the completed gate record is:
+
+1. `npm run check`, `npm run test:pi`, `npm run test:install`, `npm run build`;
+2. deterministic lifecycle/evidence/capability tests;
+3. a disposable temporary-worktree real Claude repair/reacceptance spike with an edit-capable
+   Worker;
+4. cleanup verification: no Worker, no Decision Worker, no unreconciled lease and clean Git
+   worktree.
+
+The remaining gate is a read-only review of the exact resulting commit. The drill evidence is
+recorded in `docs/automation-hardening-plan.md`; it did not run against this release worktree,
+did not use Claude `--resume`, and did not merge, publish or release automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {