pi-claude-supervisor 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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)
 
 
@@ -43,10 +50,12 @@ All notable changes to this project will be documented here.
 - 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
 
-- 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`.
+- 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,14 +8,14 @@
 
 用于 Pi 的 Claude Code Worker 监督扩展。MVP 中 Pi 负责生命周期、状态机、策略门和独立验收；Worker 只是被显式启动的子进程。
 
-> `v0.5.2` 已发布为单 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 通过。确认的产品目标是本地开发
 > 完全无人值守；详见 [自动化目标](docs/autonomy-target.md)。代码进入远程仓库或
-> main/integration 分支必须经过独立边界，Worker 不拥有 push/merge 权限；自动模式仅使用
-> JSONL，tmux 保留为手动交互 transport。
+> main/integration 分支必须经过独立边界，Worker 不拥有 push/merge 权限。
 >
 > **无人值守状态：** 自动模式会自主完成本地修改、测试、有限修复、验收、独立 Review
 > 和本地提交检查；无法形成候选时自动挂起为不可发布候选。可选出站通知不授予权限，
@@ -55,9 +55,10 @@ 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 中使用：
 
@@ -114,8 +115,9 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 自动模式会将 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。
+进程组已消失且 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—结构化修复轮次—再次验收”闭环。
@@ -124,7 +126,7 @@ Worker 应使用 `adopt-tmux`，而不是 takeover。
 Reviewer 只能使用 `read`、`grep`、`find`、`ls`，不会修改工作树或批准权限。自动模式在
 Worker 启动前捕获 git baseline，要求完整的 baseline-relative tracked/commit/untracked evidence，
 并在默认情况下要求 Worker 在非保护分支本地 commit；无效输出、证据不完整、重复 finding、P0/P1 或预算耗尽
-会自动挂起候选。自动模式拒绝 process-pipe 和 tmux，并在模型执行前检查目录、可执行文件、依赖
+会自动挂起候选。自动模式拒绝 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 仍需由集成方提供。
 
@@ -134,8 +136,10 @@ Worker 启动前捕获 git baseline，要求完整的 baseline-relative tracked/
 
 ```bash
 export PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux
-export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode plan'
-# tmux 仅为手动交互；无人值守 Decision Worker 必须使用 JSONL。
+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
 ```
@@ -143,8 +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、审计和独立验收流程；由于 tmux 没有结构化权限边界，
-不会在 tmux 中启用自动 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 中启动，可以显式接管且不会重放原始任务：
 
@@ -159,7 +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：

package/README.md

@@ -10,10 +10,10 @@ 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.2` 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 only; tmux is manual-only because it has no structured
-> permission boundary. Repairable-vs-persistent capabilities,
+> 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
@@ -148,6 +148,10 @@ candidate from crossing the remote/main boundary. Automatic mode rejects explici
 `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. Full host-level sandboxing and low-privilege execution for custom
@@ -175,9 +179,11 @@ 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.
-# tmux is manual-only; automatic Decision Worker supervision requires JSONL.
+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
 ```
@@ -187,10 +193,14 @@ literal attach command. Use that command in another terminal to watch or
 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` 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.
+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:
@@ -211,13 +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 and must not be treated as structured
-permission evidence. TUI decisions follow the configured autonomy policy and are
+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. Owned tmux sessions
-survive a Pi disconnect and require an explicit `adopt-tmux` after restart. Use
-plan/read-only flags for live testing.
+`--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
 

package/docs/architecture.md

@@ -77,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`
@@ -104,25 +105,37 @@ 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
@@ -139,9 +152,12 @@ 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

package/docs/automation-hardening-plan.md

@@ -144,7 +144,8 @@ diff:   (none)
 - Reviewer evidence 使用任务 baseline-relative diff、baseline 后 commit summaries、受限 untracked regular-file 内容、路径组件/symlink 门禁，并对 incomplete/truncated fail-closed。
 - Acceptance 子进程、证据收集和 Reviewer 共享 abort signal；Pi UI 可看到 startup、Worker heartbeat、acceptance、review、repair 和 candidate/decision phases。
 - 自动模式启动前检查运行目录、cwd、Worker 可执行文件、transport 依赖和 required cgroup；显式
-`process-pipe` 和 `tmux` 不再进入自动模式，后者保留为手动 PTY transport。
+`process-pipe` 仍仅限手动模式，Supervisor 自有 tmux bridge 可进入自动模式，被接管的
+session 仍仅限手动 PTY transport。
 - Reviewer/Decision Worker 只解析 assistant message 边界的最终文本；permission pending 会在自动响应后清除，候选状态不会被错误解除；扩大的 exec buffer 避免普通大测试报告被误判为命令失败。
 
 本轮已完成：

package/docs/autonomy-target.md

@@ -28,13 +28,15 @@ complete audit trail. These are reliability and containment mechanisms, not requ
 to approve every development action. Automatic mode also records and revalidates a full existing
 repository baseline, captures the startup HEAD and requires that exact HEAD again at
 final pre-spawn, requires a non-protected branch and a pinned operator-owned direct Claude
-JSONL Worker, and by default requires a local commit before a candidate is deliverable.
+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 the structured JSONL transport; the interactive tmux transport
-remains manual-only because it has no equivalent permission-response boundary. The Worker and local
-automation do **not** receive authority or credentials for:
+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;
@@ -100,8 +102,9 @@ Automatic mode implements the local loop: policy decisions allow ordinary local
 continue/redirect/answer/repair, acceptance and independent Review run without a human callback,
 and unresolved situations become `blocked` candidates. The default task autonomy is unattended, requires a local commit, and permits two bounded
 Decision Worker request retries. Automatic startup rejects non-Git/detached/bare/protected
-repository states, malformed baselines, startup-HEAD races, non-JSONL transports and
-non-Claude or untrusted executable identities before Worker startup. The resolved
+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.
 

package/docs/engineering-plan.md

@@ -36,7 +36,7 @@ Claude Code Worker
 4. Supervisor 因误判导致无限循环、危险操作或不可审计的修改。
 5. 人工无法随时接管或恢复任务。
 
-**当前状态：`v0.5.2` 已正式发布，已完成固定 Claude Code `2.1.270` 稳定性验证、单 Worker recovery、真实只读 Review drill、隔离临时 worktree 的允许编辑 repair/reacceptance drill、exact-head 独立 Review 和受保护发布。当前工作树已落实 repairable/persistent 能力拆分、verifying stop、paused watchdog、baseline-relative repository evidence、可取消验收/Reviewer、启动 preflight、无人值守权限决策、local-commit enforcement、候选挂起和阶段进度通知。自动模式现在要求 direct Claude JSONL、完整 Git baseline、非保护分支，并请求不可用即失败的 Claude Code sandbox 和无出站域名；任意自定义可执行文件不会进入自动模式。Legacy human/takeover APIs 仅保留显式兼容控制；普通不确定性不再阻塞本地循环。协同多 Worker、手动/自定义集成的 host-level 低权限和网络隔离仍是独立后续里程碑。**
+**当前状态：`v0.5.3` 已正式发布，已完成固定 Claude Code `2.1.270` 稳定性验证、单 Worker recovery、真实只读 Review drill、隔离临时 worktree 的允许编辑 repair/reacceptance drill、exact-head 独立 Review 和受保护发布。当前工作树已落实 repairable/persistent 能力拆分、verifying stop、paused watchdog、baseline-relative repository evidence、可取消验收/Reviewer、启动 preflight、无人值守权限决策、local-commit enforcement、候选挂起和阶段进度通知。自动模式现在要求 direct Claude JSONL 或 Supervisor 自有 tmux bridge、完整 Git baseline、非保护分支，并请求不可用即失败的 Claude Code sandbox 和无出站域名；任意自定义可执行文件不会进入自动模式。Legacy human/takeover APIs 仅保留显式兼容控制；普通不确定性不再阻塞本地循环。协同多 Worker、手动/自定义集成的 host-level 低权限和网络隔离仍是独立后续里程碑。**
 
 ---
 

package/docs/implementation-review.md

@@ -39,6 +39,14 @@ boundary.
 
 ## Residual risks and follow-up hardening
 
+The final independent review also raised a pathname TOCTOU concern for Claude
+file-tool authorization. That finding is intentionally recorded as a false positive
+for this release's trusted local-development threat model: normal edits may replace
+file contents, but automatic workers are not treated as hostile same-UID filesystem
+actors, and this policy is a metadata guard rather than a host filesystem isolation
+boundary. A future untrusted-worker mode would need a host-side broker or an OS
+sandbox that prevents `.git` writes.
+
 These are verified limitations and follow-up work after the automatic boundary
 hardening:
 

package/docs/testing.md

@@ -57,7 +57,9 @@ uses Claude Code 2.1.270 at
 `/home/yancao/.local/share/mise/installs/claude/2.1.270/claude`, including real
 owned tmux turns, pause/resume, and restart re-adoption.
 The adapter regression suite also verifies event subscription, parsed
-`permission_request` events, and the exact nested `control_response` envelope.
+`permission_request` events, the exact nested `control_response` envelope, and
+that an automatic tmux Worker cannot launch a second Claude executable from a
+Worker-created script.
 The automation spike additionally exercises a real Pi SDK Decision Worker with
 Claude: ordinary completion, harmless Bash permission handling, and an
 `AskUserQuestion` denial-to-text fallback followed by automatic verification.
@@ -118,19 +120,24 @@ relevant checks from a clean host perspective.
 
 Automatic mode is enabled with `PI_CLAUDE_SUPERVISOR_MODE=auto`; it defaults to
 JSONL and routes `result`, permission, and process-exit events to the persistent
-Pi Decision Worker. Task autonomy defaults to unattended local work, a required
+Pi Decision Worker. Setting `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux` selects the
+Supervisor-owned live bridge, which carries the same structured records through
+private framing on the PTY rather than an independent JSONL sidecar. Task autonomy
+defaults to unattended local work, a required
 local commit on a non-protected task branch and two bounded Decision Worker retries. Configure
 `PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT=0` or task `autonomy.requireLocalCommit`
 only to disable the local-commit deliverability check; automatic mode still requires a Git
-baseline and non-protected worktree. An explicit `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux` selection
-remains screen-based and does not use the JSONL permission protocol. `process-pipe` remains the manual compatibility mode. Candidate/failure notification is optional and outbound-only through
+baseline and non-protected worktree. Adopted tmux sessions remain manual-only; the automatic bridge requires
+Supervisor ownership. `process-pipe` remains the manual compatibility mode. Candidate/failure notification is optional and outbound-only through
 `PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL`; it is not a synchronous approval
 callback. Approval callbacks are deliberately not accepted without a separately
 authenticated endpoint.
 
 The tmux transport is selected with `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`.
-Automatic mode rejects explicit `process-pipe` and `tmux` transports; use JSONL for
-bounded decisions and repair. Built-in Claude workers also receive a fail-closed
+Automatic mode rejects explicit `process-pipe`; use JSONL or the Supervisor-owned
+bridge for bounded decisions and repair. Automatic JSONL and tmux workers also
+require Linux cgroup v2 containment (and the tmux parent-death guardian); startup
+fails closed when it is unavailable. Built-in Claude workers also receive a fail-closed
 sandbox setting (`failIfUnavailable`, `allowUnsandboxedCommands=false`, no outbound
 network domains); verify that startup fails if the sandbox cannot be initialized.
 Automatic startup also requires a full existing Git baseline, non-bare non-protected
@@ -141,7 +148,7 @@ compares the exact startup HEAD again immediately before spawn. Before release,
 private-socket attach,
 multi-line paste, prompt stability while
 Claude is busy, trust/permission policy handling, duplicate send prevention, pane
-replacement refusal, pause/resume, owned-session stop, adopted-session
+replacement refusal, live bridge event framing, pause/resume, owned-session stop, adopted-session
 detach/re-adoption, bounded shutdown, and Pi shutdown without closing an
 attached window. The two gated real-Claude spikes above cover the trust prompt,
 permission prompt, exact output, optional takeover, and adopted detach paths. Use
@@ -156,7 +163,8 @@ response.
 The automated adapter matrix covers external `SIGTERM`, `SIGINT`, `SIGKILL`,
 `SIGSTOP`/`SIGCONT`, SIGTERM refusal/escalation, leader-early-exit descendant
 cleanup, required cgroup bootstrap containment of a pre-attachment detached
-and `setsid()` descendant, repeated stop, spawn failure, output truncation,
+and `setsid()` descendant, automatic nested-Claude detection across the worker
+cgroup, repeated stop, spawn failure, output truncation,
 blocked stdin write timeouts, and immediate JSONL results. The Supervisor
 matrix also covers retrying failed lifecycle events, preserving startup event
 order, stopping under persistent timeout-event failure, and restoring output
@@ -185,8 +193,12 @@ isolated temporary worktree. The current hardening plan and evidence paths are r
 in [`docs/automation-hardening-plan.md`](automation-hardening-plan.md). Deterministic
 coverage now includes repairable-vs-persistent capability assertions, cancellation
 of acceptance commands, stop-from-verifying precedence, paused watchdog baselining,
-staged/untracked evidence and untracked symlink rejection. The remaining release gate
-is the exact-head independent read-only review.
+staged/untracked evidence, and untracked symlink/hard-link rejection. The exact-head
+independent read-only review was rerun. Its pathname TOCTOU finding is recorded as a
+false positive for the trusted local-development threat model: automatic workers are
+trusted development agents, and this policy is a metadata guard rather than a host
+filesystem isolation boundary. A hostile same-UID worker would require a separate
+sandbox/broker design and is out of scope for this release.
 
 ### Acceptance and Reviewer fixtures
 

package/package.json

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

package/src/decision-session-store.ts

@@ -168,9 +168,16 @@ export class DecisionSessionStore {
       const record = await this.#loadUnlocked(taskId);
       if (!record || record.state !== "active") throw new Error(`Decision Worker recovery record is unavailable: ${taskId}`);
       if (record.recoveryState === "ready" || record.recoveryState === "interrupted") return;
-      if (!record.recoveryOwnerPid || await processExists(record.recoveryOwnerPid)) {
+      if (!record.recoveryOwnerPid || !record.recoveryOwnerStartTime) {
+        throw new Error(`Decision Worker recovery owner identity is unavailable: ${taskId}`);
+      }
+      const currentOwnerStartTime = await processStartTime(record.recoveryOwnerPid);
+      if (currentOwnerStartTime === record.recoveryOwnerStartTime) {
         throw new Error(`Decision Worker recovery owner is still live: ${taskId}`);
       }
+      if (!currentOwnerStartTime && await processExists(record.recoveryOwnerPid)) {
+        throw new Error(`Decision Worker recovery owner identity is unavailable: ${taskId}`);
+      }
       await this.#saveUnlocked({
         ...record,
         recoveryState: "interrupted",

package/src/index.ts

@@ -39,19 +39,19 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   if (!["off", "auto", "required"].includes(cgroupMode)) {
     throw new Error(`Unsupported PI_CLAUDE_SUPERVISOR_CGROUP_MODE: ${cgroupMode}; expected off, auto, or required`);
   }
-  if (transport === "tmux" && cgroupMode === "required") {
-    throw new Error("PI_CLAUDE_SUPERVISOR_CGROUP_MODE=required is unsupported with tmux; use process-pipe/jsonl or set cgroup mode to auto/off");
+  if (transport === "tmux" && cgroupMode === "required" && !automation) {
+    throw new Error("PI_CLAUDE_SUPERVISOR_CGROUP_MODE=required is unsupported with manual tmux; use automatic mode or cgroup mode auto/off");
   }
-  if (automation && transport !== "jsonl") {
-    throw new Error("automatic supervision requires PI_CLAUDE_SUPERVISOR_TRANSPORT=jsonl; process-pipe and tmux are manual-only");
+  if (automation && !["jsonl", "tmux"].includes(transport)) {
+    throw new Error("automatic supervision requires PI_CLAUDE_SUPERVISOR_TRANSPORT=jsonl or tmux; process-pipe is manual-only");
   }
   const adapter = transport === "tmux"
-    ? new TmuxWorkerAdapter({ stateDir })
+    ? new TmuxWorkerAdapter({ stateDir, cgroupMode: automation ? "required" : cgroupMode as "off" | "auto" | "required" })
     : new ProcessWorkerAdapter({
       // Automatic decisions require Claude's structured event stream. The pipe
       // transport remains available for manual/compatibility sessions.
       mode: automation || transport === "jsonl" ? "claude-jsonl" : "process-pipe",
-      cgroupMode: cgroupMode as "off" | "auto" | "required",
+      cgroupMode: automation ? "required" : cgroupMode as "off" | "auto" | "required",
     });
   const humanWebhook = new HumanWebhookNotifier({
     url: process.env.PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL,
@@ -232,7 +232,10 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           const fileSpec = specPath ? await readTaskSpecFile(specPath, ctx.cwd) : undefined;
           const spec = fileSpec ?? { autonomy: autonomyDefaults() };
           const goal = fileSpec?.goal ?? task;
-          const taskAutomation = automation && spec.autonomy.unattended;
+          // Adopted sessions are explicit manual compatibility controls. They
+          // never enter the automatic Reviewer/decision loop, even when the
+          // extension is globally configured for unattended starts.
+          const taskAutomation = operation !== "adopt-tmux" && automation && spec.autonomy.unattended;
           if (!goal) throw new Error(operation === "adopt-tmux" ? "Usage: /supervise adopt-tmux [--spec <file>] <tmux-session> <task>" : "Usage: /supervise start [--spec <file>] <task>");
           if (operation === "adopt-tmux" && adapter.capabilities().transport !== "tmux") throw new Error("/supervise adopt-tmux requires PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux");
           const [command, ...workerArgs] = parseCommand(process.env.PI_CLAUDE_SUPERVISOR_WORKER ?? "claude");
@@ -259,7 +262,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           }
           pendingCwds.add(cwdKey);
           const session = new Supervisor(adapter, events, {
-            reviewer,
+            reviewer: taskAutomation ? reviewer : undefined,
             onCandidate: async (notice) => {
               if (ctx.hasUI) notify(ctx, `Candidate ${notice.status}: ${notice.reason}`, notice.status === "ready" ? "info" : "warning");
               if (humanWebhook.enabled) {
@@ -475,7 +478,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           }
           pendingCwds.add(cwdKey);
           const session = new Supervisor(adapter, events, {
-            reviewer,
+            reviewer: automaticRecovery ? reviewer : undefined,
             onCandidate: async (notice) => {
               if (ctx.hasUI) notify(ctx, `Candidate ${notice.status}: ${notice.reason}`, notice.status === "ready" ? "info" : "warning");
               if (humanWebhook.enabled) {