pi-claude-supervisor 0.5.2 → 0.5.3

package/docs/automation-hardening-plan.md

@@ -1,7 +1,7 @@
 # 自动化稳定性与生命周期加固计划
 
-> 计划状态：Phase A–D 已在当前工作树实现；真实可编辑 repair/reacceptance 已通过，待 exact-head 独立只读 Review 作为发布前最后门禁
-> 基线：`v0.5.1` / `26443f0`
+> 计划状态：Phase A–D、真实可编辑 repair/reacceptance、exact-head 独立只读 Review、受保护发布和本地无人值守闭环已完成；远程 push/main merge 仍是独立边界。
+> 基线：`v0.5.2` / `eefc7bc`
 > 真实验证：Claude Code `2.1.270`
 > 记录日期：2026-09-14
 
@@ -15,7 +15,7 @@
   -> argv/execFile 验收
   -> 独立只读 Reviewer
   -> P1/P2 阻塞发现
-  -> fail-closed / human intervention
+  -> fail-closed / parked non-publishable candidate
   -> Worker、Pi、lease 清理
 ```
 
@@ -141,15 +141,17 @@ diff:   (none)
 - `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 避免普通大测试报告被误判为命令失败。
+- 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 避免普通大测试报告被误判为命令失败。
 
-仍待完成：
+本轮已完成：
 
-- 对当前 exact head 执行最后一次独立只读 Review；该 Review 必须不编辑、不运行命令、不发送 Worker 输入、不提交或发布。
-- Review 通过且完整质量门禁再次通过后，才允许人工决定是否提交、合并或发布；本轮仍不自动 release/publish。
+- 普通本地命令和权限不再进入同步人工审批；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. 实施顺序
 
@@ -157,23 +159,23 @@ diff:   (none)
 
 1. 增加 `repairableSession` capability。
 2. JSONL 在当前 Supervisor 生命周期内支持 repair，仍不声明跨重启恢复。
-3. 重构 repair/finalize/human 分支，保证终态转换和 Decision Worker closure 幂等。
+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-relative diff 覆盖 staged/unstaged tracked 修改。
+2. 记录任务开始时的 HEAD；baseline-relative diff 覆盖 committed/staged/unstaged tracked 修改，并记录 baseline 后 commits。
 3. 安全收集 untracked regular-file evidence，防 symlink 和路径逃逸。
-4. evidence truncation/incomplete 强制 human。
+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。
+4. 修复自动 permission 响应后的 stale pending request，并使本地决策不会依赖同步 human gate。
 5. 清理 Pi extension 自己安装的 signal handler，避免与 Pi `session_shutdown` 竞争。
 
 ### Phase D：回归、真实演练和发布门禁
@@ -181,23 +183,22 @@ diff:   (none)
 1. 扩展 acceptance/replay/capability 矩阵。
 2. 在临时 worktree 中使用真实 Claude 做一次受控 repair/reacceptance；禁止触碰主仓库。
 3. 运行 `npm run check`、Pi/npm smoke、build 和真实只读 review。
-4. 只有独立 Reviewer `pass`、所有检查通过、cleanup/lease 证据完整后，才允许人工
-   决定是否提交、合并或发布。
+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 | 保持 Worker 可人工接管，不自动继续 |
-| Reviewer `human` + Worker 已退出 | 完成 cleanup、关闭 Decision Worker、保留 recoverable record |
+| 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 只能返回 human |
+| evidence 截断/不可验证 | Reviewer 只能阻止 `pass`，候选自动挂起 |
 | malformed/multi-message model output | 不误判为 pass/action |
 | preflight 失败 | Claude 尚未启动前 fail-closed |
 
@@ -206,6 +207,6 @@ diff:   (none)
 - Reviewer 继续只允许 `read`、`grep`、`find`、`ls`。
 - 验收命令继续使用 argv 和 `execFile`，不经过 shell 拼接。
 - 不伪造 Claude `--resume`；`resumeSession` 仍然是明确能力声明。
-- 不自动 merge、deploy、release 或 publish。
+- Worker 不得远程 push 或 merge 到 main/integration；发布仍走独立受保护 workflow。
 - 不允许多 Worker 共享同一可写 worktree。
-- P0/P1、重复 finding、超时、API 错误、无效输出和不完整证据继续 fail-closed。
+- 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.