pi-claude-supervisor 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented here.
 
+## [0.5.4](https://github.com/btnalit/pi-claude-supervisor/compare/v0.5.3...v0.5.4) (2026-09-15)
+
+
+### Bug Fixes
+
+* harden unattended local lifecycle ([4f68760](https://github.com/btnalit/pi-claude-supervisor/commit/4f6876044cd8be00b0376239377b02b70aae8473))
+
+## [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 +46,16 @@ 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.
+- Add a Supervisor-owned automatic tmux bridge that renders Claude stream-json in a live PTY and carries structured records through private framing instead of an independent event sidecar; adopted sessions remain manual-only.
+- Add parent-identity tmux guardians, guarded Linux bootstrap readiness/cleanup, explicit nested-Agent/background-reviewer denial, and tolerant Reviewer prose/fence/repeated-JSON parsing with separate display-truncation markers.
 
-### Remaining hardening gate
+### Release readiness
 
-- 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`.
+- 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`. The review's pathname TOCTOU concern is explicitly accepted as a false positive for the trusted local-development threat model; host-side broker isolation remains future work for an untrusted-worker mode.
 
 ### 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.3` 已发布为单 Worker recovery 基线。默认手动 transport 是无额外依赖的
+> process pipe，不是 PTY；自动模式支持 Claude JSONL 或 Supervisor 自有的 tmux bridge，被接管的
+> tmux session 仍仅限手动交互。当前工作树已实现
 > 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 权限。
+>
+> **无人值守状态：** 自动模式会自主完成本地修改、测试、有限修复、验收、独立 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,15 +49,16 @@ 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 CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
+自动模式支持 `claude-jsonl` 和 Supervisor 自有的 tmux bridge；JSONL 的 `result`、
+`control_request` 和进程 `exit` 事件会唤醒 Decision Worker。tmux bridge 把结构化记录
+通过同一个 live PTY 的私有 terminal framing 传回适配器，不创建独立 JSONL sidecar；
+`adopt-tmux` 仍是手动模式。本版本固定按已验证设备的 Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 
 然后在 Pi 中使用：
 
@@ -79,44 +87,48 @@ 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 服务。
+进程组已消失且 cgroup 仍是真实、可读取的空边界时，才可显式添加 `--takeover`；缺失、仍存活或无法确认的 Worker 会被拒绝。手动 owned tmux
+Worker 可在重启后使用 `adopt-tmux`，而不是 takeover；自动 bridge 会由 parent-death guardian
+在 Supervisor 消失时终止，不提供自动 session 的重接管。
+自动模式下，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，并在模型执行前检查目录、可执行文件、依赖
+和 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 交互模式
 
@@ -124,9 +136,10 @@ 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
+export PI_CLAUDE_SUPERVISOR_WORKER='claude'
+# 当前手动 tmux 也要求 Linux（用于 pane identity 和清理）；可使用 cgroup auto/off。
+# 设置 PI_CLAUDE_SUPERVISOR_MODE=auto 启用 Supervisor 自有的自动 bridge；自动 tmux
+# 要求 Linux cgroup v2 和 parent-death guardian，缺失时会 fail closed。
 # 接管非默认 tmux server 时可选：
 # export PI_CLAUDE_SUPERVISOR_TMUX_SOCKET=/path/to/tmux.sock
 ```
@@ -134,7 +147,12 @@ 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、审计和独立验收流程。自动模式会在 pane 内启动 bridge：它运行
+Claude stream-json、把可读输出渲染到附着的终端，并通过同一 PTY 的私有 framing 返回结构化
+记录；bridge 及其后代放入受 Supervisor 管理的 Linux cgroup，并由 parent-death guardian
+保护；任一 containment 机制不可用时 fail closed。适配器直接从 PTY 原始 pipe 解析，因此没有
+独立 JSONL sidecar。自动模式拒绝被接管的 session；Supervisor 自有 bridge 支持自动输入串行化、
+权限响应、turn 完成和 stop。
 
 如果 Claude 已由你在 tmux 中启动，可以显式接管且不会重放原始任务：
 
@@ -149,8 +167,8 @@ 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，不能把屏幕文字当作结构化权限证据；只有 Supervisor bridge
+的私有 framing 记录才是结构化证据。TUI 决策应按任务授权策略处理并记录；无法形成候选时可以自动挂起，不要求人工持续在线。普通终端里已经运行的 Claude 不能安全迁移进 tmux；`--resume`
 是读取历史的新进程，不是实时 attach。实时测试请使用 plan/read-only 参数。
 
 可以从不同工作目录启动多个任务会话；活动会话不能共享同一 cwd，建议每个任务使用独立 worktree：
@@ -169,4 +187,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.3` 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 or the Supervisor-owned tmux bridge; adopted tmux
+> sessions remain manual-only. 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,41 @@ 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).
+The automatic tmux bridge carries Claude stream-json records inside the same live PTY
+as display output using private terminal framing; it does not create an independent
+structured-event sidecar. Automatic tmux accepts only Supervisor-owned sessions,
+while `adopt-tmux` remains manual-only.
 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 +166,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
 
@@ -148,21 +179,28 @@ For an interactive Claude Code window, opt in to the tmux transport:
 
 ```bash
 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
+export PI_CLAUDE_SUPERVISOR_WORKER='claude'
+# Manual tmux currently requires Linux for process identity and cleanup;
+# it may use cgroup mode auto/off.
+# Set PI_CLAUDE_SUPERVISOR_MODE=auto for the Supervisor-owned automatic bridge;
+# automatic tmux additionally requires Linux cgroup v2 and a parent-death guardian.
 # 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.
+In automatic mode the Supervisor starts a bridge in the pane: it runs Claude's
+stream-json protocol inside the live PTY, contains the bridge and descendants in
+an owned cgroup, fails closed when that containment or the Linux guardian is
+unavailable, renders readable deltas for the attached terminal, and returns
+structured records through private terminal framing on the same PTY.
+The adapter parses those records from the raw PTY pipe, so there is no independent
+JSONL event sidecar. Automatic mode refuses adopted sessions; use JSONL or the owned
+bridge for unattended decisions, repair and protected command enforcement.
 
 A session that you started yourself can be explicitly adopted without replaying
 the task:
@@ -183,12 +221,15 @@ 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 itself Claude JSONL and must not be treated as structured
+permission evidence; only the Supervisor bridge's private framed records are
+authoritative. 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. Manual owned tmux
+sessions survive a Pi disconnect and require an explicit `adopt-tmux` after
+restart; automatic owned sessions are terminated by their parent-death guardian
+when the Supervisor disappears. Use plan/read-only flags for live testing.
 
 ## Development
 
@@ -202,7 +243,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