pi-claude-supervisor 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented here.
 
+## [0.5.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.5.0...v0.5.1) (2026-09-14)
+
+
+### Bug Fixes
+
+* harden single-worker recovery lifecycle ([14c01ec](https://github.com/btnalit/pi-claude-supervisor/commit/14c01ec610b1210eda1ea2d60269fad25b8b3575))
+
+## [0.5.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.4.1...v0.5.0) (2026-09-14)
+
+
+### Features
+
+* add acceptance review repair loop ([fe29c78](https://github.com/btnalit/pi-claude-supervisor/commit/fe29c78a228494768aa52b03ee1bf1545b079119))
+
+## [Unreleased]
+
+### Added
+
+- Structured task specifications with Goal, scope, constraints, forbidden actions and multiple argv-based acceptance checks.
+- Independent read-only Reviewer results with bounded findings and automatic repair rounds.
+- JSONL malformed-record handling and duplicate result/permission suppression fixtures.
+- Active JSONL request shutdown coverage and deterministic acceptance/review tests.
+- Durable Decision Worker recovery claims with stale-owner reconciliation and explicit fail-closed takeover.
+- Identity-bound tmux handoff cleanup and recovery/lease lifecycle coverage.
+- Claude Code 2.1.270 bounded stability matrix evidence in `docs/stability-matrix-2.1.270.md`.
+
 ## [0.4.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.4.0...v0.4.1) (2026-09-14)
 
 
@@ -69,7 +95,7 @@ All notable changes to this project will be documented here.
 - Historical Claude CLI 2.1.268 permission allow/deny and SIGTERM/SIGINT transport spike evidence; current release validation uses Claude CLI 2.1.270.
 - Event-driven JSONL `control_request`/`result`/exit events, permission responses, persistent Pi Decision Worker automation, bounded duplicate/turn handling, and outbound human-intervention webhooks.
 - Long-task defaults are now 100 automatic turns, 4 hours wall time and 20 minutes without output; Decision Worker API failures alert human operators directly instead of attempting an LLM fallback.
-- Automatic Decision Worker sessions now persist as Pi JSONL with a 0600 task registry. Unclean Pi restarts expose explicit `/supervise recover <task-id>` recovery; Claude work is not silently duplicated.
+- Automatic Decision Worker sessions now persist as Pi JSONL with a 0600 task registry. Unclean Pi restarts expose explicit `/supervise recover [--takeover] <task-id>` recovery; Claude work is not silently duplicated.
 - Local tests and package-content checks.
 
 ### Limitations

package/README.cn.md

@@ -51,9 +51,10 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 ```text
 /supervise capabilities
 /supervise start inspect the current repository
+/supervise start --spec ./task.json
 /supervise poll
 /supervise sessions
-/supervise recover <task-id>
+/supervise recover [--takeover] <task-id>
 /supervise stop human requested stop
 /supervise verify
 /supervise approve <task-id> allow|deny [request-id]
@@ -61,6 +62,21 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 /supervise resume-auto <task-id>
 ```
 
+`--spec` 接受 JSON 文件；验收命令始终使用 argv 执行，不经过 shell。例如：
+
+```json
+{
+  "goal": "实现请求的修改",
+  "scope": ["src/"],
+  "constraints": ["保持公共 API 兼容"],
+  "forbidden": ["不要发布构建产物"],
+  "acceptance": [
+    { "id": "tests", "name": "tests", "command": "npm", "args": ["test"], "required": true }
+  ],
+  "maxRepairRounds": 3
+}
+```
+
 人工升级通知的 generic JSON 格式为：
 
 ```json
@@ -78,12 +94,21 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 
 当前 webhook 是出站通知，不直接接受批准命令；批准或接管仍通过 Pi。
 自动模式会将 Decision Worker 会话持久化到状态目录。Pi 非正常重启后，`/supervise sessions`
-会显示 `recoverable` 任务；显式执行 `/supervise recover <task-id>` 会恢复 Decision Worker 上下文并
-重新启动 Claude Worker，不会静默恢复或重复执行任务。
+会显示 `recoverable` 任务；显式执行 `/supervise recover [--takeover] <task-id>` 会恢复 Decision Worker 上下文并
+重新启动 Claude Worker，不会静默恢复或重复执行任务。旧 Pi 进程已退出且租约确认旧 Worker
+进程组已消失且 cgroup 仍是真实、可读取的空边界时，才可显式添加 `--takeover`；缺失、仍存活或无法确认的 Worker 会被拒绝。持久 tmux
+Worker 应使用 `adopt-tmux`，而不是 takeover。
 自动模式下，Decision Worker 可以安全拒绝 `AskUserQuestion`，让 Claude 将问题转成普通文本，
 再根据任务和仓库证据自动回答；无法确定时才升级人工。如需微信内闭环，需要另建带签名验证、
 一次性 action token 和重放保护的入站 callback 服务。
 
+`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、低权限和网络隔离作为本阶段门禁。
+
 ### tmux/PTY 交互模式
 
 如果希望在可见的 Claude Code 终端中工作，可显式启用 tmux transport：
@@ -128,6 +153,11 @@ PTY 屏幕文字不是 Claude JSONL。权限/信任对话框和无法确定的 T
 /supervise send <task-id> continue after checking the test failure
 ```
 
+当前支持的是**独立任务会话并行**，不是共享工作树的协同多 Worker。后续多 Worker
+开发任务会引入 parent/child 任务图、依赖、并发上限、结构化 handoff、汇总验收和
+跨进程恢复，但不会放宽“一个 worktree 一个写入者”的边界，也不会自动 merge 或 publish。
+该阶段应安排在固定 Claude `2.1.270` 稳定性统计和单 Worker recovery 语义完成之后。
+
 Pull Request 必须通过聚合的 `CI / Quality gate`。Release Please 根据 Conventional Commits 创建版本 PR；维护者合并后，Release workflow 会针对精确 tag commit 重新验证，并通过受保护的 `npm` environment 使用 npm provenance 发布。
 
 详细内容见 [engineering-plan.md](docs/engineering-plan.md)、[independent-review.md](docs/independent-review.md)、[architecture.md](docs/architecture.md)、[testing.md](docs/testing.md) 和 [releasing.md](docs/releasing.md)。

package/README.md

@@ -57,8 +57,9 @@ export PI_CLAUDE_SUPERVISOR_WORKER=claude
 ```text
 /supervise capabilities
 /supervise start inspect the current repository and report what should be changed
+/supervise start --spec ./task.json
 /supervise sessions
-/supervise recover <task-id>
+/supervise recover [--takeover] <task-id>
 /supervise poll
 /supervise poll all
 /supervise send continue with read-only inspection
@@ -68,6 +69,22 @@ export PI_CLAUDE_SUPERVISOR_WORKER=claude
 /supervise verify
 ```
 
+`--spec` accepts a JSON file; checks are always executed with argv (never through
+a shell), for example:
+
+```json
+{
+  "goal": "Implement the requested change",
+  "scope": ["src/"],
+  "constraints": ["Keep the public API compatible"],
+  "forbidden": ["Do not publish artifacts"],
+  "acceptance": [
+    { "id": "tests", "name": "tests", "command": "npm", "args": ["test"], "required": true }
+  ],
+  "maxRepairRounds": 3
+}
+```
+
 The default MVP writes the task to the worker's stdin as plain process-pipe
 text. After running the transport spike for the target CLI, JSONL framing can
 be selected explicitly:
@@ -83,16 +100,36 @@ The supervisor allows only one active JSONL request per session: poll until its
 yet exposed by the adapter. Multiple independent task sessions can run
 concurrently when they use different canonical working directories or
 worktrees; same-directory starts are rejected even when concurrent, and
-`/supervise sessions` lists the sessions. Unattended use still requires the
-remaining lifecycle, signal and recovery checks. Host permissions and network
-access follow explicit caller authorization and host policy; there is no
-automatic merge, deploy, release or publish.
+`/supervise sessions` lists the sessions. This is independent-session
+parallelism, not coordinated multi-worker collaboration. A future multi-worker
+milestone will add explicit parent/child task graphs, dependencies, bounded
+scheduling, structured handoffs, aggregate acceptance and graph-aware recovery;
+it will not relax the one-writer-per-worktree rule or enable automatic
+merge/publish. Unattended use still requires the remaining lifecycle, signal and
+recovery checks. Host permissions and network access follow explicit caller
+authorization and host policy; there is no automatic merge, deploy, release or
+publish.
+
+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.
 
 Automatic mode persists the Pi Decision Worker session under the configured state
 directory. After an unclean Pi restart, `/supervise sessions` lists recoverable
-tasks; `/supervise recover <task-id>` explicitly restores the Decision Worker
+tasks; `/supervise recover [--takeover] <task-id>` explicitly restores the Decision Worker
 context and starts a new Claude Worker. It never silently resumes or duplicates
-work. The adapter intentionally does not inherit arbitrary host environment variables.
+work. If the old Pi owner is dead, add `--takeover` only after the lease proves
+the old Worker's process group is gone and its cgroup is a real, readable empty
+boundary; missing or unverifiable Worker evidence is refused.
+For a persistent tmux Worker, use explicit `adopt-tmux` instead of takeover.
+The adapter intentionally does not inherit arbitrary host environment variables.
 Pass credentials through an explicit `WorkerStartInput.env` in an embedding
 integration. For the built-in command, opt in to named variables, for example
 `PI_CLAUDE_SUPERVISOR_WORKER_ENV=ANTHROPIC_API_KEY`.

package/docs/architecture.md

@@ -27,6 +27,28 @@ 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.
 
+### Multi-worker boundary and roadmap
+
+The current implementation supports multiple **independent** task sessions, not
+coordinated shared-worktree editing. Every active session must own a
+non-overlapping canonical cwd/worktree and has an isolated Supervisor,
+watchdog, Worker handle and acceptance/review loop. The shared EventLog is only
+an audit stream; it is not a collaboration or authorization channel.
+
+A future multi-worker scheduler must introduce an explicit parent/child task
+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.
+
+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
+shutdown must leave every child either cleanup-verified or explicitly
+recoverable. This work is scheduled after single-worker stability and session
+recovery, not by relaxing the current cwd lease rule.
+
 ## MVP transport
 
 `ProcessWorkerAdapter` uses `node:child_process.spawn` with:
@@ -126,9 +148,12 @@ registry before spawning Claude. The default registry is
 may point all Pi processes at an alternate shared directory. Canonical paths
 conflict with both their parents and descendants, and the registry lock
 serializes acquisition across independent Pi processes. A lease is released
-only after the adapter confirms the worker and its descendant cleanup; an
-unconfirmed lease left by a crashed Pi is intentionally retained and requires
-operator verification/manual cleanup rather than unsafe automatic reclamation.
+only after the adapter confirms the worker and its descendant cleanup. An
+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.
 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
@@ -170,7 +195,8 @@ duplicate turns. The adapter also exposes event subscriptions for `result`,
 `control_request`, permission requests and process exit. Automatic mode routes
 those events to a persistent, read-only Pi Decision Worker; its Pi session JSONL
 and task mapping are persisted under the supervisor state directory. After an
-unclean Pi restart, recovery is explicit: `/supervise recover <task-id>` restores
+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
@@ -181,6 +207,29 @@ 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.
 
+## 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
+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,
+bounded output and the same deterministic command policy; a Worker completion
+claim never substitutes for these results.
+
+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
+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.
+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.
+
 ## Deliberate non-goals
 
 - automatic merge/deploy/release;
@@ -192,4 +241,7 @@ suppress the alert.
 - 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.
+  shell patterns require human review rather than blanket network rejection;
+- Claude CLI multi-version compatibility in the current stability milestone;
+- OS sandbox, low-privilege execution and network isolation in the current
+  lifecycle milestone.

package/docs/engineering-plan.md

@@ -1,6 +1,6 @@
 # Pi Claude Supervisor 完整方案
 
-> 文档状态：方案设计稿 / MVP 实施基线  
+> 文档状态：`v0.5.0` 已发布 / 后续开发路线图
 > 目标项目目录：`pi-claude-supervisor`  
 > 适用对象：W、项目负责人、实现人员、评审人员
 
@@ -36,7 +36,7 @@ Claude Code Worker
 4. Supervisor 因误判导致无限循环、危险操作或不可审计的修改。
 5. 人工无法随时接管或恢复任务。
 
-**总体判断：架构方向可以 GO。先完成兼容性 Spike、生命周期和故障恢复验证；低权限用户、OS sandbox 与网络隔离不作为当前主线或硬性阻塞，按调用者明确授权和宿主机策略运行，后续再做安全加固。**
+**当前状态：`v0.5.0` 已完成“验收—独立 Review—自动修复—再验收”闭环并正式发布。下一阶段先完成固定 Claude Code `2.1.270` 的稳定性统计和恢复语义，再推进有边界的多 Worker 协作；低权限用户、OS sandbox 与网络隔离仍是后续安全加固，不作为当前主线硬性阻塞。**
 
 ---
 
@@ -74,7 +74,9 @@ Claude Code 适合作为实际开发 Worker，但在长时间任务中可能出
 - 不自动 merge、deploy 或 release。
 
 当前扩展已支持多个独立任务会话并行推进，但不允许活动会话共享同一
-工作目录。事件日志由跨进程锁协调，状态和 watchdog 按会话隔离。
+工作目录。事件日志由跨进程锁协调，状态和 watchdog 按会话隔离。这里要区分两种
+“多 Worker”：**独立会话并行**已经属于当前能力；**有依赖、交接和汇总验收的协同多
+Worker**属于后续开发任务，不能通过简单地放宽 cwd 限制来实现。
 
 暂不支持：
 
@@ -916,3 +918,115 @@ PTY 和 headless JSONL 只能选择一个作为 MVP 的主 transport，禁止两
 ## 附录 B：一句话版本
 
 > 先用最小、可审计、可接管的 Supervisor 闭环证明可靠性，再逐步开放 LLM 判断和自动化权限；不要从“自动化最多”开始，而要从“边界最清楚、证据最可靠”开始。
+
+## 20. 近期落地与剩余门禁：稳定的自动验收闭环
+
+本轮已落地 TaskSpec、多命令验收、独立只读 Reviewer、结构化 repair round、重复 finding/P0/P1 人工升级、JSONL 去重和确定性 replay fixture。剩余门禁是固定 CLI 的重复运行统计，而不是继续扩大安全边界。近期目标从“扩大安全边界”调整为先证明单一已验证 Claude CLI 版本上的真实功能稳定性。当前只验证固定的 Claude Code `2.1.270`，不把多版本兼容作为本阶段任务。OS sandbox、低权限用户、网络 allowlist、SBOM 和更深的供应链加固后置，不作为本阶段门禁；现有 no-shell、Policy Gate、人工接管和独立验收边界继续保留。
+
+### 20.1 Goal / Evidence / Sign-off 模型
+
+任务规格统一为：
+
+```yaml
+ goal: 实现用户邀请接口
+ scope:
+   - 新增接口
+   - 添加权限校验
+ constraints:
+   - 不修改核心数据库模型
+ forbidden:
+   - 不执行生产部署
+ acceptance:
+   - id: tests
+     command: npm
+     args: [test]
+   - id: typecheck
+     command: npm
+     args: [run, typecheck]
+   - id: diff-check
+     command: git
+     args: [diff, --check]
+ maxRepairRounds: 3
+```
+
+兼容旧任务时，普通任务文本作为 `goal`，默认验收仍为 `git diff --check`。所有验收命令使用 argv 和确定性 Policy Gate，不经过 shell。
+
+验收流程固定为：
+
+```text
+Worker result
+  → 多命令 acceptance checks
+  → 独立只读 Reviewer
+      ├── pass   → completed
+      ├── revise → 结构化修复指令 → Worker → 重新验收
+      └── human  → 人工接管
+```
+
+Reviewer 必须使用独立 Pi session，只允许 `read`、`grep`、`find`、`ls`，输出结构化 verdict 和 findings；不能修改工作树或直接批准权限。默认最多三轮修复；相同 finding 重复出现或出现 P0/P1 问题时升级人工。
+
+### 20.2 JSONL 稳定性证据
+
+只对 Claude Code `2.1.270` 建立证据，覆盖：
+
+- JSONL 跨 chunk 拆分、单 chunk 多记录和 malformed 行；malformed 行不能触发完成事件；
+- 重复 result、重复 permission request、重复 Supervisor idempotency key 不产生重复动作；
+- active request 期间的 SIGTERM、SIGINT、stop 和 Pi shutdown；
+- 普通完成、低风险 Bash allow、`AskUserQuestion` deny-to-text、多轮、验收失败修复和恢复回放。
+
+真实 Claude Spike 不进入普通 CI；确定性 fake Worker/replay fixture 进入 CI。自动模式继续保持显式 opt-in，直到以下门禁通过：普通任务连续十次成功，权限和问题转文本场景各至少五次成功，无重复动作、无错误 complete、无未清理 Worker，且关键事件可以完整回放。
+
+### 20.3 明确不属于本阶段
+
+- Claude CLI 多版本兼容；
+- OS sandbox、低权限执行和网络隔离；
+- 自动 merge、deploy、release、publish；
+- 多 Worker 在同一工作树协作。
+
+## 21. 后续开发路线图
+
+`v0.5.0` 的发布不代表所有自动化目标都已完成。后续任务按“稳定性 → 恢复 → 协同
+调度 → 安全加固”推进；多 Worker 可以纳入开发任务，但应作为独立阶段，不能与当前
+单 Worker 稳定性门禁混在一起。
+
+### 21.1 短期：稳定性收尾
+
+- 完成真实 Claude Code `2.1.270` 重复 Spike：普通任务连续 10 次，权限和问题回退各至少 5 次；
+- 补齐 replay：多轮修复、验收失败修复、repair budget 耗尽、takeover、recover 和 Pi shutdown；
+- 补齐边界测试：Reviewer 流式输出上限、`DecisionSessionStore.list()` 任务 ID 校验、跨进程恢复和超时/输出截断；
+- 继续观察 npm `0.5.0`、GitHub Release 资产、provenance 和回滚路径；
+- 验收标准：无重复动作、错误 complete、未清理 Worker 或未审计的自动放行。
+
+### 21.2 中期：恢复能力
+
+- 设计安全的 Claude session resume；明确 `--resume` 与实时 PTY attach 的边界；
+- 完善 takeover、recover、Pi shutdown、Worker 崩溃和部分完成的状态语义；
+- 增加跨进程恢复端到端测试，包括 cwd lease、Decision Worker session、Worker 身份和事件日志一致性；
+- 恢复失败必须进入 `HUMAN_REQUIRED`，不能静默重放原始任务或重复发送输入。
+
+### 21.3 后续：多 Worker 协作与调度
+
+第一阶段只做**独立 worktree 的多 Worker 编排**，不允许共享工作树写入。建议拆成以下
+开发任务：
+
+1. **任务图与角色模型**：增加 `parentTaskId`、Worker role、`dependsOn`、worktree、handoff
+   artifact 和子任务状态；明确 root task 与 child task 的审计关联。
+2. **受限调度器**：实现并发上限、依赖就绪、全局时间/修复预算、取消传播和失败隔离；
+   不让任意 Worker 自行启动、停止或批准另一个 Worker。
+3. **结构化交接**：Worker 之间只通过受限 artifact、事件引用和验收报告交接，不直接共享
+   控制通道；交接内容必须经过 schema 校验和大小限制。
+4. **汇总验收**：每个 child 先独立验收，root task 再汇总目标、diff、测试和 Reviewer 结果；
+   冲突、缺失证据或任一 P0/P1 自动升级人工。
+5. **恢复与关闭**：支持单个 child、整棵任务图和 Pi shutdown 的一致性恢复；父任务不能在
+   子任务状态未知时报告 `completed`。
+6. **冲突检测和人工整合**：只允许在独立 integration worktree 中进行显式整合；不自动
+   merge/publish，冲突和整合动作必须保留人工控制权。
+
+多 Worker 阶段的最小验收矩阵：两个独立 Worker 并行、依赖顺序、一个 Worker 失败、取消
+传播、重复交接、工作树冲突、单 child 恢复、整棵任务图恢复和 shutdown 中断。通过这些
+门禁后，才评估是否需要更复杂的 lead-worker 或动态任务分解。
+
+### 21.4 后置：安全加固
+
+- CLI 多版本兼容矩阵；
+- OS sandbox、低权限执行、网络隔离/allowlist；
+- 更深的供应链、SBOM、密钥隔离和生产监控。

package/docs/recovery-review.md

@@ -0,0 +1,24 @@
+# Recovery follow-up review
+
+The independent read-only review of the recovery changes initially returned
+`BLOCK` with three P1 findings, one P2 finding, and a coverage note. The findings
+were addressed in this follow-up.
+
+- Stale `starting`/`registered`/`recovered_idle` claims now persist recovery
+  owner PID/start time, are reconciled only after the old owner and Worker
+  boundary are independently gone, and return to an explicit `interrupted`
+  state.
+- `--takeover` requires a dead owner, dead Worker/process group, and a real,
+  readable empty cgroup boundary; missing or unverifiable Worker evidence is
+  rejected.
+- Worker registration and `recovered_idle` transitions require an active record,
+  persist atomically, and are read back and checked before the recovered session
+  is exposed.
+- Adopted tmux handoff reports the replaced task and closes its old Decision
+  session mapping only after worker identity registration succeeds.
+- Session closure now carries cleanup evidence and intent; uncertain cleanup
+  retains the active record and cwd lease.
+
+Validation: `npm run check`, `npm run build`, the pinned Claude Code 2.1.270
+question matrix (5/5 verified), and the bounded stability evidence in
+[`stability-matrix-2.1.270.md`](stability-matrix-2.1.270.md).

package/docs/stability-matrix-2.1.270.md

@@ -0,0 +1,32 @@
+# Claude Code 2.1.270 stability matrix
+
+Run date: 2026-09-14. The executable was resolved as
+`/home/yancao/.local/share/mise/installs/claude/2.1.270/claude` and reported
+`2.1.270 (Claude Code)`. Runs used the authenticated local provider and
+`scripts/spike-claude-automation.mjs`; no Claude `--resume` was used.
+
+## Required matrix (120 s bounded run)
+
+| Scenario | Runs | Completed + verified | Fail-closed outcomes |
+| --- | ---: | ---: | --- |
+| ordinary task | 10 | 9 | 1 stopped at the bounded deadline without verification |
+| permission handling | 5 | 5 | 0 |
+| question handling | 5 | 5 | 0 |
+
+The ordinary outlier was not treated as success: the spike exited non-zero,
+kept verification false, and stopped rather than retrying or replaying the task.
+This is the intended timeout fail-closed behavior. An earlier question spike also
+escalated after invalid Decision Worker output; it was likewise not counted as a
+success. The five-run question matrix above was then rerun with a 180 s bound and
+all five completed with `verified=true` and zero human interventions.
+
+## Bounded follow-up
+
+Three additional ordinary and three additional question runs with the same
+pinned executable and a 180 s bound also completed with `verified=true` and zero
+human interventions. These runs support a provider-latency explanation for the
+120 s outliers; they do not turn an outlier into a success.
+
+The deterministic replay, acceptance, recovery-state, lease, cleanup and
+package checks remain the CI evidence. Authenticated Claude runs are manual
+release evidence only.

package/docs/testing.md

@@ -49,9 +49,9 @@ non-sensitive prompt, and prints protocol metadata rather than raw model output.
 It must not be added to the normal CI gate because authentication is an owner
 controlled prerequisite.
 
-The historical fixtures validate one prompt, multiple turns, session resume,
-permission allow/deny and SIGTERM/SIGINT behavior with Claude Code 2.1.268.
-The current release validation uses Claude Code 2.1.270 at
+The transport fixtures validate one prompt, multiple turns, session resume,
+permission allow/deny and SIGTERM/SIGINT behavior. The current release validation
+uses Claude Code 2.1.270 at
 `/home/yancao/.local/share/mise/installs/claude/2.1.270/claude`, including real
 owned tmux turns, pause/resume, and restart re-adoption.
 The adapter regression suite also verifies event subscription, parsed
@@ -59,11 +59,18 @@ The adapter regression suite also verifies event subscription, parsed
 The automation spike additionally exercises a real Pi SDK Decision Worker with
 Claude: ordinary completion, harmless Bash permission approval, and an
 `AskUserQuestion` denial-to-text fallback followed by automatic verification.
+A local pinned-CLI run completed all three scenarios with `state=completed`,
+`verified=true`, and zero human interventions. Provider/model latency can still
+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,
 `/supervise sessions` shows the task as `recoverable`, and `/supervise recover
-<task-id>` restores the Decision Worker history before starting a new Claude
-Worker.
+[--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
+Worker process group is gone, and its cgroup is a real readable empty boundary;
+persistent tmux sessions use `adopt-tmux`.
 Run the permission and signal probes explicitly when validating a CLI release:
 
 ```bash
@@ -89,7 +96,9 @@ response, and an exact result marker; it also records metadata only.
 
 For each release, pin and record the validated Claude Code version, resolved
 executable path, and model. The spikes reject an unpinned/mismatched executable
-version. For this release the validated version is `2.1.270` with model `opus`.
+version. For this release the validated version is `2.1.270` with model `opus`;
+the bounded matrix and its fail-closed outliers are recorded in
+[`docs/stability-matrix-2.1.270.md`](stability-matrix-2.1.270.md).
 Record:
 
 1. exact version and resolved executable path;
@@ -144,3 +153,68 @@ not eliminate the post-spawn attachment window. `SIGSTOP` and `SIGKILL` of the P
 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.
+
+### Acceptance and Reviewer fixtures
+
+Deterministic tests must cover:
+
+- legacy text tasks normalized to a Goal with the default `git diff --check`;
+- 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 escalating to human;
+- repair rounds, repeated finding detection, P0/P1 escalation and repair-budget exhaustion;
+- completion being impossible without passing all required checks and review.
+
+Reviewer sessions use only `read`, `grep`, `find` and `ls`; they must not modify
+the worktree or send Worker input. Decision Worker and Reviewer model calls are
+bounded; timeout or API failure escalates instead of auto-completing. Review reports
+are persisted as bounded event payloads and are not treated as permission grants.
+
+### JSONL protocol and replay fixtures
+
+The adapter/replay matrix must cover:
+
+- JSON split across stdout chunks and multiple records in one chunk;
+- malformed JSON between valid records without a false completion event;
+- duplicate result and permission records without duplicate actions;
+- 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.
+
+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.
+
+## Future multi-worker test plan
+
+Multiple independent task sessions already run concurrently when their canonical
+cwd/worktrees do not overlap. This is not yet coordinated multi-worker
+collaboration. The future multi-worker milestone must be tested as a task graph,
+not as unrestricted shared-worker access.
+
+Required deterministic and integration coverage:
+
+- two independent Workers with separate worktrees and aggregated parent status;
+- dependency ordering and a blocked child that must not start early;
+- child failure, timeout, cancellation propagation and bounded global budgets;
+- schema-validated handoff artifacts with duplicate/oversized/stale handoffs;
+- conflicting diffs detected before integration, with no same-worktree writes;
+- independent child acceptance followed by root-task aggregate acceptance and Review;
+- single-child recovery, whole-graph recovery and Pi shutdown during scheduling;
+- no child can grant permissions, send control input to another child or bypass Policy Gate;
+- explicit human-controlled integration in a separate worktree; no automatic merge or publish.
+
+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.

package/package.json

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