pi-claude-supervisor 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented here.
 
+## [0.5.3](https://github.com/btnalit/pi-claude-supervisor/compare/v0.5.2...v0.5.3) (2026-09-15)
+
+
+### Bug Fixes
+
+* harden unattended local lifecycle ([#27](https://github.com/btnalit/pi-claude-supervisor/issues/27)) ([2bb29d3](https://github.com/btnalit/pi-claude-supervisor/commit/2bb29d3c31f5196f208716723d89b6b538777939))
+
 ## [0.5.2](https://github.com/btnalit/pi-claude-supervisor/compare/v0.5.1...v0.5.2) (2026-09-14)
 
 
@@ -32,10 +39,14 @@ All notable changes to this project will be documented here.
 - 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.
+- Close automatic startup baseline/worktree/branch validation gaps, including persisted recovery baselines and the final pre-spawn boundary recheck.
+- Replace shell-policy lexical bypasses with quote-aware parsing, nested-shell inspection and protected Git-ref checks; deny dynamic shell expansions while preserving literal argv values, and reject arbitrary non-Claude automatic executables.
+- Normalize malformed custom Reviewer values to blocking reports, persist recovery baselines and the resolved Claude executable identity, filter automatic environment variables with a deny-by-default allowlist, and compare the exact startup HEAD at the adapter spawn boundary.
+- Keep protected CI checks on the exact checked-out commit while giving automatic-mode fixtures a local validation branch and an owned deterministic Claude executable.
 
 ### 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`.
+- Open the protected pull request and complete independent CI/integration review; the exact-head read-only review, real editable Claude `2.1.270` repair/reacceptance drill and cleanup/lease evidence are recorded in `docs/automation-hardening-plan.md`.
 
 ### Added
 

package/README.cn.md

@@ -8,24 +8,31 @@
 
 用于 Pi 的 Claude Code Worker 监督扩展。MVP 中 Pi 负责生命周期、状态机、策略门和独立验收；Worker 只是被显式启动的子进程。
 
-> `v0.5.1` 已发布为单 Worker recovery 基线。默认手动 transport 是无额外依赖的
-> process pipe，不是 PTY；自动模式只使用 Claude JSONL 或 tmux。当前工作树已实现
+> `v0.5.2` 已发布为单 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 与网络隔离继续延期。
+> repair/reacceptance 演练已在隔离临时 worktree 通过。确认的产品目标是本地开发
+> 完全无人值守；详见 [自动化目标](docs/autonomy-target.md)。代码进入远程仓库或
+> main/integration 分支必须经过独立边界，Worker 不拥有 push/merge 权限；自动模式仅使用
+> JSONL，tmux 保留为手动交互 transport。
+>
+> **无人值守状态：** 自动模式会自主完成本地修改、测试、有限修复、验收、独立 Review
+> 和本地提交检查；无法形成候选时自动挂起为不可发布候选。可选出站通知不授予权限，
+> push 和 main/integration merge 仍必须经过独立边界。
 
 ## 关键安全边界
 
 - 不会在扩展加载时自动启动 Worker。
 - 不经过 shell 启动子进程。
-- Worker 只继承最小环境；凭据必须由调用方显式传入。
-- 破坏性命令和绕过权限的 Worker 参数默认拒绝；需要复核的启动命令会请求用户批准，不会一律拒绝。
+- Worker 只继承最小环境；自动模式采用默认拒绝的环境变量 allowlist，过滤远程凭据并禁用 Git/包管理器 credential helper。自动模式只能选择文档列出的 Claude provider 变量；任意自定义变量仅限手动集成。
+- 本地命令和权限行为按任务/运行时授权策略处理；超出授权的动作自动拒绝或挂起，不要求同步人工响应。
 - Linux 上优先使用可写的 cgroup v2 清理后代进程，包括 `setsid()` 后代；不可用时回退到进程组清理。需要强制失败闭环时，embedding 集成可使用 `cgroupMode: "required"`，并会在 Claude 启动前执行 preflight。
-- 普通联网查询不因联网本身被拒绝；下载后直接交给 shell 等高风险模式仍需人工复核。
+- 自动模式只接受裸的 `claude`/`claude.exe` 命令名，并从 Supervisor 的 PATH 解析、固定由操作者拥有的可执行文件（或使用 `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` 固定路径）；显式路径和可写/不可信位置会被拒绝。它请求 fail-closed 的 Claude Code Bash sandbox，禁止 Bash 子进程出站联网；命令策略仍是第二道门。手动/自定义集成必须自行提供等效 host/network 边界。
 - Worker 声称完成只会进入 `verifying`，不能作为成功证据。
 - 默认独立验收命令为 `git diff --check`。
-- 扩展运行时不执行 merge、deploy、release 或 publish；仓库 Release 只会在维护者合并 Release Please PR 且 CI 门禁全部通过后自动发布。
+- 目标是任务启动后本地开发无人值守：Worker 可以修改、测试、修复和本地提交；Worker 必须没有远程 push 或合并到 `main`/integration 分支的权限。
+- 扩展运行时不执行 merge、deploy、release 或 publish；远程/main 集成和仓库 Release 必须经过独立受保护边界。
 - 默认 4 小时总时限、20 分钟无输出 watchdog 超时即停止 Worker；paused 期间不消耗无输出预算，resume 会重建基准但不会重置总时限。嵌入调用方可将对应选项设为 `0` 关闭。
 - 验收命令、仓库证据收集和独立 Reviewer 共用 abort signal，人工 stop/shutdown 不必等待完整超时。
 
@@ -42,14 +49,14 @@ pi install npm:pi-claude-supervisor
 ```bash
 export PI_CLAUDE_SUPERVISOR_MODE=auto
 export PI_CLAUDE_SUPERVISOR_WORKER='claude --safe-mode --tools Bash'
-# 可选：人工升级通知；generic 或 wecom
+# 可选：候选/失败通知；generic 或 wecom
 export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL='https://example.invalid/webhook'
 export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_FORMAT=generic
 # export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_SECRET='shared-secret'
 ```
 
-自动模式默认使用 `claude-jsonl`，通过 `result`、`control_request` 和进程
-`exit` 事件唤醒 Decision Worker；显式选择 tmux 时仍使用屏幕交互，不使用 JSONL 权限协议，也不会依赖 `/supervise poll` 轮询。本版本固定按已验证设备的
+自动模式默认并且只能使用 `claude-jsonl`，通过 `result`、`control_request` 和进程
+`exit` 事件唤醒 Decision Worker；tmux 仅用于手动屏幕交互，不使用 JSONL 权限协议，也不会依赖 `/supervise poll` 轮询。本版本固定按已验证设备的
 Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 
 然后在 Pi 中使用：
@@ -79,44 +86,47 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
   "acceptance": [
     { "id": "tests", "name": "tests", "command": "npm", "args": ["test"], "required": true }
   ],
-  "maxRepairRounds": 3
+  "maxRepairRounds": 3,
+  "autonomy": {
+    "unattended": true,
+    "requireLocalCommit": true,
+    "maxDecisionRetries": 2
+  }
 }
 ```
 
-人工升级通知的 generic JSON 格式为：
+候选/失败通知的 generic JSON 格式为（旧 human-intervention webhook 名称保持兼容）：
 
 ```json
 {
-  "schema": "pi-claude-supervisor/human-intervention/v1",
-  "event": "human_intervention_required",
+  "schema": "pi-claude-supervisor/candidate/v1",
+  "event": "candidate_status",
   "task": { "id": "...", "goal": "...", "cwd": "..." },
   "worker": { "id": "..." },
   "reason": "...",
-  "question": "...",
-  "permission": { "requestId": "...", "toolUseId": "...", "toolName": "Bash", "input": {} },
-  "actions": ["approve_or_deny_permission", "send_instruction", "stop_worker", "takeover"]
+  "status": "ready|blocked|failed",
+  "deliverable": false,
+  "note": "This notification does not grant remote push or main/integration merge permission."
 }
 ```
 
-当前 webhook 是出站通知，不直接接受批准命令；批准或接管仍通过 Pi。
+当前 webhook 只是出站候选通知，不直接接受批准命令；显式 stop、takeover 等兼容控制仍通过 Pi。
 自动模式会将 Decision Worker 会话持久化到状态目录。Pi 非正常重启后，`/supervise sessions`
 会显示 `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 服务。
+自动模式下，Decision Worker 在任务授权范围内自动处理普通问题、测试失败和修复轮次，记录假设和证据；无法形成可交付候选时自动挂起并保留证据，而不是要求人工必须在线。可通过 `PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT=0` 或 task `autonomy.requireLocalCommit` 关闭本地 commit 要求，但自动模式仍要求有效 Git baseline 和非保护 worktree；远程 push 和 main/integration merge 仍由独立边界控制。
 
 `v0.5.0` 已完成并发布“多命令验收—独立只读 Reviewer—结构化修复轮次—再次验收”闭环。
-任务可通过 API 或 JSON spec 提供 `goal`、`scope`、`constraints`、`forbidden` 和多个
-`acceptance` 命令；旧的纯文本任务继续使用默认 `git diff --check`。Reviewer 只能使用
-`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、低权限
-和网络隔离作为本阶段门禁。
+任务可通过 API 或 JSON spec 提供 `goal`、`scope`、`constraints`、`forbidden`、多个
+`acceptance` 命令和 `autonomy` 控制；旧的纯文本任务继续使用默认 `git diff --check`。
+Reviewer 只能使用 `read`、`grep`、`find`、`ls`，不会修改工作树或批准权限。自动模式在
+Worker 启动前捕获 git baseline，要求完整的 baseline-relative tracked/commit/untracked evidence，
+并在默认情况下要求 Worker 在非保护分支本地 commit；无效输出、证据不完整、重复 finding、P0/P1 或预算耗尽
+会自动挂起候选。自动模式拒绝 process-pipe 和 tmux，并在模型执行前检查目录、可执行文件、依赖
+和 cgroup；Worker 环境会过滤远程仓库凭据并禁用 Git 全局凭据 helper。详见 [自动化目标](docs/autonomy-target.md)。协同多 Worker 属于后续独立开发阶段，
+自动模式只接受裸的直接 Claude 命令名，会固定解析后的操作者拥有的可执行文件，并请求 fail-closed 的 Claude Code Bash sandbox；任意自定义可执行文件和显式可执行路径会在自动模式拒绝。需要固定路径时设置 `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE`。手动/自定义 Worker 的完整 host-level sandbox 仍需由集成方提供。
 
 ### tmux/PTY 交互模式
 
@@ -125,8 +135,7 @@ exact-head 独立只读 Review；协同多 Worker 属于后续独立开发阶段
 ```bash
 export PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux
 export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode plan'
-# 可选自动 Decision Worker（默认仍是人工模式）：
-# export PI_CLAUDE_SUPERVISOR_MODE=auto
+# tmux 仅为手动交互；无人值守 Decision Worker 必须使用 JSONL。
 # 接管非默认 tmux server 时可选：
 # export PI_CLAUDE_SUPERVISOR_TMUX_SOCKET=/path/to/tmux.sock
 ```
@@ -134,7 +143,8 @@ export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode plan'
 `/supervise start <task>` 会在私有 tmux server 中启动 Claude，并返回可复制的 attach 命令。
 可以在另一个终端 attach 到同一个 PTY，观察或人工输入。多行消息通过 tmux buffer 和 Enter
 发送，不会把消息拼接进 shell 命令；`pipe-pane` 记录原始输出，`capture-pane` 检测稳定的 Claude
-输入提示，并复用 watchdog、Decision Worker、审计和独立验收流程。
+输入提示，并复用 watchdog、审计和独立验收流程；由于 tmux 没有结构化权限边界，
+不会在 tmux 中启用自动 Decision Worker 或无人值守远程边界策略。
 
 如果 Claude 已由你在 tmux 中启动，可以显式接管且不会重放原始任务：
 
@@ -149,8 +159,7 @@ export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode plan'
 `tmux kill-session`。`/supervise takeover <task-id>` 会暂停 Decision Worker 自动发送，只有
 `/supervise resume-auto <task-id>` 才恢复。
 
-PTY 屏幕文字不是 Claude JSONL。权限/信任对话框和无法确定的 TUI 状态必须升级人工，不能把
-屏幕文字当作结构化权限证据。普通终端里已经运行的 Claude 不能安全迁移进 tmux；`--resume`
+PTY 屏幕文字不是 Claude JSONL，不能把屏幕文字当作结构化权限证据。TUI 决策应按任务授权策略处理并记录；无法形成候选时可以自动挂起，不要求人工持续在线。普通终端里已经运行的 Claude 不能安全迁移进 tmux；`--resume`
 是读取历史的新进程，不是实时 attach。实时测试请使用 plan/read-only 参数。
 
 可以从不同工作目录启动多个任务会话；活动会话不能共享同一 cwd，建议每个任务使用独立 worktree：
@@ -169,4 +178,4 @@ PTY 屏幕文字不是 Claude JSONL。权限/信任对话框和无法确定的 T
 
 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)。
+详细内容见 [engineering-plan.md](docs/engineering-plan.md)、[autonomy-target.md](docs/autonomy-target.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

@@ -10,26 +10,33 @@ 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.
 
-> **Release status:** `v0.5.1` is the released single-Worker recovery baseline. The
+> **Release status:** `v0.5.2` 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.
+> supervision uses Claude JSONL only; tmux is manual-only because it has no structured
+> permission boundary. 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 passed in an isolated temporary worktree. The confirmed product target is
+> unattended local development; see [the autonomy target](docs/autonomy-target.md).
+> Remote push and merge into the main/integration branch remain outside Worker authority
+> and must cross an independent boundary.
+>
+> **Autonomy status:** automatic mode continues local editing, testing, bounded repair,
+> acceptance, independent Review and local-commit enforcement without a synchronous human
+> callback. Unresolvable work is parked as a non-publishable candidate; optional outbound
+> notifications do not approve actions.
 
 ## Safety boundary
 
 - The extension never starts a worker automatically.
 - Worker commands are launched without a shell.
-- Workers receive a minimal environment; credentials must be explicitly supplied by the caller.
-- Destructive command patterns and permission-bypass worker flags are denied; review-level patterns request explicit user approval instead of being blanket-denied.
-- Ordinary network use is not denied merely because it is network use; download-to-shell patterns still require review.
+- Workers receive a minimal environment; automatic mode uses a deny-by-default variable allowlist, strips remote credentials and disables Git/package credential helpers. Only documented Claude provider variables may be selected for automatic mode; arbitrary custom variables remain manual-only.
+- Local command and permission behavior follows the configured task/runtime policy; actions outside that authority are rejected or parked without requiring a synchronous human response.
+- Automatic mode admits only the bare `claude`/`claude.exe` command name, resolves and pins an operator-owned executable from the supervisor PATH (or `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE`), and rejects explicit paths or writable/untrusted locations. It requests a fail-closed Claude Code Bash sandbox with no outbound domains; command policy remains a second guard. Manual/custom integrations must provide their own equivalent host/network boundary.
 - A worker completion is only a transition to `verifying`; it is not evidence of success.
 - 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.
+- Target local development runs unattended after a task starts: the Worker may edit, test, repair and commit locally. The Worker must have no authority or credentials to push remotely or merge into `main`/an integration branch.
+- The extension never performs merge, deploy, release, or publish at runtime. Remote/main integration and repository releases cross independent protected boundaries.
 - 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 `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.
@@ -86,7 +93,12 @@ a shell), for example:
   "acceptance": [
     { "id": "tests", "name": "tests", "command": "npm", "args": ["test"], "required": true }
   ],
-  "maxRepairRounds": 3
+  "maxRepairRounds": 3,
+  "autonomy": {
+    "unattended": true,
+    "requireLocalCommit": true,
+    "maxDecisionRetries": 2
+  }
 }
 ```
 
@@ -109,25 +121,37 @@ worktrees; same-directory starts are rejected even when concurrent, and
 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.
+it will not grant any Worker remote push or main/integration merge authority.
+Unattended local development is the target operating mode; a blocked or failed
+candidate is parked with its evidence rather than made dependent on a human being
+online. Automatic mode accepts only the bare direct Claude command name, pins its
+operator-owned resolved executable path, and uses a fail-closed Bash sandbox with no
+outbound domains; arbitrary custom executables and explicit executable paths are rejected
+in automatic mode. Set `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` when the resolved path must
+be pinned explicitly. Manual/custom integrations must provide an equivalent host/network
+boundary.
+Set `PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT=0` only for a task that intentionally
+produces no local commit candidate, or set `autonomy.requireLocalCommit` in its spec;
+automatic mode still requires a valid Git baseline and non-protected worktree.
+`PI_CLAUDE_SUPERVISOR_UNATTENDED=0` opts a task out of automatic Decision Worker control;
+a required local commit is checked on a non-protected task branch;
+`PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES` bounds transient Decision Worker retries.
 
 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 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.
+permissions. Automatic mode requires complete baseline-relative tracked, commit and
+bounded untracked evidence, repairs a live `repairableSession` Worker within a
+bounded budget, enforces a local commit when enabled, and prevents a non-publishable
+candidate from crossing the remote/main boundary. Automatic mode rejects explicit
+`process-pipe` and preflights runtime prerequisites. Invalid output, unavailable
+evidence, duplicate findings, P0/P1 findings and exhausted repair budgets park the
+candidate without waiting for a human; see [the autonomy target](docs/autonomy-target.md).
 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.
+manual Spikes. Full host-level sandboxing and low-privilege execution for custom
+integrations remain separate hardening work.
 
 Automatic mode persists the Pi Decision Worker session under the configured state
 directory. After an unclean Pi restart, `/supervise sessions` lists recoverable
@@ -138,9 +162,12 @@ 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`.
+Manual embedding integrations may pass credentials through an explicit
+`WorkerStartInput.env`; automatic mode accepts only documented Claude provider
+variables, for example `PI_CLAUDE_SUPERVISOR_WORKER_ENV=ANTHROPIC_API_KEY`, and
+filters remote credentials and configuration-injection variables. The host-side
+`PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` setting pins the executable identity and is not
+passed into the Worker environment.
 
 ### tmux/PTY transport
 
@@ -150,19 +177,20 @@ For an interactive Claude Code window, opt in to the tmux transport:
 export PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux
 export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode plan'
 # tmux does not support cgroup required mode; use cgroup mode auto/off.
-# Optional automatic Decision Worker (manual mode is the default):
-# export PI_CLAUDE_SUPERVISOR_MODE=auto
+# tmux is manual-only; automatic Decision Worker supervision requires JSONL.
 # Optional, only when adopting a non-default tmux server:
 # export PI_CLAUDE_SUPERVISOR_TMUX_SOCKET=/path/to/tmux.sock
 ```
 
 `/supervise start <task>` starts Claude in a private tmux server and reports a
 literal attach command. Use that command in another terminal to watch or
-manually interact with the same PTY. The adapter sends multi-line input through
+manually interact with the same PTY; attaching is optional for unattended local
+development. The adapter sends multi-line input through
 tmux buffers and Enter, never by interpolating the message into a shell command.
-It records the PTY stream with `pipe-pane`, uses `capture-pane` to detect a
-stable Claude input prompt, and feeds turn-completion events into the same
-watchdog, Decision Worker, audit and verification paths as JSONL.
+It records the PTY stream with `pipe-pane` and uses `capture-pane` to detect a
+stable Claude input prompt. Because tmux has no structured permission boundary,
+automatic Decision Worker supervision is disabled for this transport; use JSONL for
+unattended decisions, repair and protected command enforcement.
 
 A session that you started yourself can be explicitly adopted without replaying
 the task:
@@ -183,12 +211,13 @@ kill-session` yourself when the adopted window should be closed.
 `/supervise takeover <task-id>` disables automatic Decision Worker messages;
 resume them only with `/supervise resume-auto <task-id>`.
 
-PTY screen text is not Claude JSONL. Permission dialogs, trust prompts and
-ambiguous TUI states are escalated to a human; tmux mode must not be treated as
-structured permission evidence. A normal terminal Claude process cannot be
-migrated into tmux, and `--resume` is historical recovery rather than live PTY
-attach. Owned tmux sessions survive a Pi disconnect and require an explicit
-`adopt-tmux` after restart. Use plan/read-only flags for live testing.
+PTY screen text is not Claude JSONL and must not be treated as structured
+permission evidence. TUI decisions follow the configured autonomy policy and are
+recorded; an unresolved task may be parked without requiring a human to remain
+online. A normal terminal Claude process cannot be migrated into tmux, and
+`--resume` is historical recovery rather than live PTY attach. Owned tmux sessions
+survive a Pi disconnect and require an explicit `adopt-tmux` after restart. Use
+plan/read-only flags for live testing.
 
 ## Development
 
@@ -202,7 +231,7 @@ npm run check:workflows
 npm run build
 ```
 
-See [the engineering plan](docs/engineering-plan.md), [the independent review](docs/independent-review.md),
+See [the engineering plan](docs/engineering-plan.md), [the confirmed autonomy target](docs/autonomy-target.md), [the independent review](docs/independent-review.md),
 [architecture](docs/architecture.md), [testing](docs/testing.md), and [releasing](docs/releasing.md).
 
 Pull requests are gated by the aggregated `CI / Quality gate`. Release Please

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
@@ -119,9 +128,11 @@ For an owned initial turn, the adapter emits a synthetic `turn_completed` only
 after output activity and two stable input-prompt observations. Adopting an idle
 prompt remains inactive and emits no synthetic completion. This is a liveness
 signal, not proof that the task succeeded; the independent verifier remains
-mandatory. Interactive dialogs,
-trust prompts and ambiguous screens are not auto-approved. Human takeover sets a
-Supervisor gate that stops automatic messages until `resume-auto`.
+mandatory. Interactive dialogs, trust prompts and ambiguous screens are interpreted by
+the configured autonomy policy and recorded as evidence. An unresolved task is
+parked or failed as a non-publishable candidate rather than requiring a human to
+remain online. Human takeover remains an explicit kill/control path and stops
+automatic messages until `resume-auto`.
 
 `/supervise adopt-tmux` is explicit and validates the pinned pane's cwd and
 process identity before attaching. Every later input, capture and signal uses
@@ -165,7 +176,9 @@ unconfirmed lease left by a crashed Pi is intentionally retained. Ordinary
 recovery refuses it; an operator may use `recover --takeover` only when the old
 owner is dead, the Worker process group is gone, and the lease independently
 reads a real empty cgroup boundary for the old Worker. Missing or unverifiable
-Worker evidence still requires manual cleanup rather than unsafe reclamation.
+Worker evidence retains the lease and parks the task rather than performing unsafe
+reclamation; later recovery can inspect or clean it without requiring an operator to
+be online.
 An explicitly adopted tmux session may hand off an existing lease only after
 its owner identity is no longer live and its canonical cwd, tmux session/socket,
 pane id, pane PID/start time, and pane command all match; ordinary starts
@@ -178,13 +191,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 +241,22 @@ unclean Pi restart, recovery is explicit: `/supervise recover [--takeover]
 <task-id>` restores
 the Decision Worker context and starts a new Claude Worker. It does not silently
 resume or duplicate a task. It does not poll to detect turn completion. A watchdog timer remains only as a deadlock safety
-fallback. Permission actions pass through `evaluatePermission` and can be
-approved or denied manually with `/supervise approve`; human escalation is sent
-to an outbound webhook when configured. If the Decision Worker API/model call
-fails, the system records `decision_worker_failed` and directly alerts the
-human operator; it does not attempt a second LLM fallback. Alert delivery is
-kept independent from event-log persistence so an audit write failure cannot
-suppress the alert.
+fallback. Permission and other actions pass through the configured autonomy policy and
+are recorded. The local development loop must not require synchronous human
+approval for ordinary actions; a task that cannot safely produce a candidate is
+parked or failed without granting remote/main authority. If the Decision Worker
+API/model call fails, the system records `decision_worker_failed`, applies the
+bounded retry/park policy and preserves the candidate evidence. Optional alert
+delivery remains independent from event-log persistence, but notification is not
+the control boundary.
 
 ## Acceptance, review and repair loop
 
 A task may provide a structured `TaskSpec` with `goal`, `scope`, `constraints`,
-`forbidden` and an ordered list of required or optional acceptance checks. A
+`forbidden`, an ordered list of required or optional acceptance checks, and
+`autonomy` (`unattended`, `requireLocalCommit`, `maxDecisionRetries`). A
 legacy plain-text task is normalized to a goal with the default `git diff
---check` acceptance check. The verifier runs every configured check with argv,
+--check` acceptance check and unattended defaults. The verifier runs every configured check with argv,
 bounded output and the same deterministic command policy; a Worker completion
 claim never substitutes for these results.
 
@@ -243,35 +265,40 @@ fresh read-only Reviewer session. The Reviewer receives the task specification,
 check results and bounded Worker completion evidence, but not the Decision Worker
 conversation or control channel. It can inspect only `read`, `grep`, `find` and `ls`, and must return
 `pass`, `revise` or `human` with bounded structured findings. Invalid Reviewer
-output or a Reviewer API failure is a human-required condition.
+output, incomplete evidence or a Reviewer API failure must prevent a candidate
+from crossing the remote/main boundary; the local system may retry, repair or
+park it without requiring a human to be online.
 
 A `revise` result produces an audited repair round and sends a bounded corrective
 instruction to a still-live `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.