pi-claude-supervisor 0.5.2 → 0.5.4

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
@@ -68,24 +77,25 @@ 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
-contract validated by the fixed-version spike; an explicit tmux transport remains
-screen-based.
+(`PI_CLAUDE_SUPERVISOR_MODE=auto`) defaults to Claude JSONL and can select the
+Supervisor-owned tmux bridge. The bridge uses the CLI contract validated by the
+fixed-version spike, renders the stream in the pane and carries structured records
+through private framing on the same PTY; explicit adoption remains manual-only.
 
 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 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.
-
-When cgroup v2 is unavailable, the adapter falls back to detached
-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.
+that cleanup to be confirmed (or reports a cleanup error). On Linux, manual
+workers may use cgroup v2 automatically when the current user cgroup is writable;
+the `required` mode performs a preflight and fails before Claude starts if cgroup
+attachment or cleanup is unavailable. Automatic JSONL workers always require the
+same preflight and a guarded cgroup bootstrap; automatic startup fails closed on
+non-Linux hosts or when the boundary cannot be established. Cgroup cleanup kills
+descendants even when they call `setsid()` or create another process group.
+
+When cgroup v2 is unavailable, manual mode falls back to detached 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.
 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`
@@ -95,42 +105,59 @@ host-fatal signals.
 ## tmux/PTY transport
 
 `TmuxWorkerAdapter` is an explicit second transport, selected with
-`PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. Because tmux has no equivalent cgroup
-containment boundary, `PI_CLAUDE_SUPERVISOR_CGROUP_MODE=required` is rejected
-with this transport; use `auto`/`off` only when the tmux boundary is acceptable.
-An owned worker gets a private tmux server/socket and executes the validated Claude command directly in the pane,
-so its pane identity remains re-adoptable after a Pi restart. The worker
+`PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. Both owned and adopted tmux currently
+require Linux because pane identity and cleanup use `/proc`; manual tmux may use
+cgroup `auto`/`off`. Automatic owned tmux additionally creates a required Linux
+cgroup for the bridge and its descendants; it is rejected when cgroup v2 or the
+parent-death guardian is unavailable.
+An owned manual worker gets a private tmux server/socket and executes the
+validated Claude command directly in the pane. An owned automatic worker instead
+starts the Supervisor bridge through a cgroup-joining pane bootstrap, so its
+bridge identity is not a manual adoption target. The worker
 environment is supplied to the tmux server through the same least-privilege
 environment builder; credentials are not copied into a file; credential-shaped
 command arguments are rejected.
 `load-buffer`, bracketed `paste-buffer` and `send-keys Enter` provide the input
 boundary without interpolating a task into a shell command. C0/C1 terminal
-control bytes are rejected; CRLF is normalized to a newline.
+control bytes are rejected; CRLF is normalized to a newline. In automatic mode,
+the adapter snapshots the trusted direct Claude process and checks both the
+required Linux cgroup and process tree on every poll; a newly executed Claude or
+Reviewer descendant is a runtime policy failure and the owned session is stopped.
+This supplements the lexical Bash/file-tool boundary and is disabled for
+manual/adopted sessions.
 
 The transport has three deliberately separate observations:
 
 - `pipe-pane` provides an append-only raw PTY log for output polling and audit;
 - `capture-pane` provides a bounded screen snapshot used only for stable prompt
   detection and human display;
-- Claude's own transcript, when available, remains the structured history. The
-  screen is never relabeled as JSONL or permission evidence.
+- the Supervisor-owned bridge emits Claude stream-json records as private framed
+  PTY control data; `pipe-pane` carries those records to the adapter without an
+  independent JSONL sidecar;
+- Claude's own transcript, when available, remains the structured history. Ordinary
+  screen text is never relabeled as JSONL or permission evidence.
 
 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
 that immutable pane target; a replacement process is refused. Adopted sessions
 are not owned: stop and Pi shutdown detach rather than kill them. Tmux commands
 and serialized input waits have bounded deadlines so shutdown cannot hang
-forever. Sessions started by the adapter also survive a Pi disconnect, but
-recovery after restart is explicit re-adoption; the extension never claims to
-attach to an arbitrary non-tmux PTY. A normal Claude
+forever. Manual sessions started by the adapter survive a Pi disconnect, but recovery
+after restart is explicit re-adoption; automatic sessions are intentionally
+terminated by their parent-death guardian when the Supervisor disappears. The
+extension never claims to attach to an arbitrary non-tmux PTY. Startup cleanup always attempts the
+private tmux server teardown, including after partial session creation, and a
+confirmed `kill-server` is sufficient cleanup evidence. A normal Claude
 `--resume` starts another process from history and is not a live PTY migration.
 
 ## State machine
@@ -165,7 +192,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
@@ -178,13 +207,20 @@ 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
+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 human-gate phases in the Pi UI.
+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
@@ -221,20 +257,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.
 
@@ -243,35 +281,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 `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 Worker that has already exited cannot be silently recreated
+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 human-review branch cannot continue, a single idempotent terminalizer records
+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 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
+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

@@ -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,18 @@ 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` 仍仅限手动模式，Supervisor 自有 tmux bridge 可进入自动模式，被接管的
+session 仍仅限手动 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 +160,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 +184,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 +208,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,130 @@
+# 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 or Supervisor-owned tmux bridge, and by default requires a local commit before a candidate is deliverable.
+
+## 2. Hard authority boundary
+
+Automatic Worker supervision uses either the structured JSONL transport or a
+Supervisor-owned tmux bridge. The bridge runs Claude's stream-json protocol inside the live
+PTY, renders a human-readable display, and returns private framed records through the same
+PTY; adopted tmux sessions remain manual-only. 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, the unstructured
+process-pipe transport 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.