pi-claude-supervisor 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented here.
 
+## [0.4.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.3.0...v0.4.0) (2026-09-13)
+
+
+### Features
+
+* add cross-process cwd leases and cancellable startup ([#17](https://github.com/btnalit/pi-claude-supervisor/issues/17)) ([448cbdb](https://github.com/btnalit/pi-claude-supervisor/commit/448cbdb4c6b5dd02b9ea07ba660d3689b7e2ace8))
+
+## [0.3.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.2.2...v0.3.0) (2026-09-13)
+
+
+### Features
+
+* add safe tmux Claude worker transport ([1706153](https://github.com/btnalit/pi-claude-supervisor/commit/1706153289f9a6f7f9f59b2763ed98d061b79204))
+* add cross-process canonical cwd leases and identity-bound tmux handoff
+* make startup cancellation scoped per start and shutdown cleanup fail closed
+* add cgroup-v2 required/auto/off policies with verified fallback cleanup
+* harden owned/adopted tmux lifecycle, pane identity validation, and restart re-adoption
+* validate real Claude Code 2.1.270 tmux multi-turn, pause/resume, and re-adoption behavior
+
 ## [0.2.2](https://github.com/btnalit/pi-claude-supervisor/compare/v0.2.1...v0.2.2) (2026-09-12)
 
 
@@ -35,11 +54,12 @@ All notable changes to this project will be documented here.
 - Deterministic Policy Gate and independent verification phase.
 - Minimal worker environment, argv-aware permission policy, watchdog timeouts and startup cleanup.
 - Opt-in Claude JSONL framing with duplicate-message suppression and transport Spike evidence for prompt, multi-turn and session resume.
+- Opt-in tmux/PTY transport with private owned sessions, explicit existing-session adoption, human takeover and prompt-gated multi-line input.
 - Event-log sequence recovery and credential-shaped redaction.
 - Bounded output capture, stdin-write timeout, process-group cleanup retry and stop preemption.
 - Linux cgroup-v2 descendant cleanup, including a `setsid()` regression fixture, with required/auto modes.
 - Lifecycle event retry/order preservation, output restoration after log failure and shutdown cleanup retries.
-- Claude CLI 2.1.268 permission allow/deny and SIGTERM/SIGINT transport spike evidence.
+- Historical Claude CLI 2.1.268 permission allow/deny and SIGTERM/SIGINT transport spike evidence; current release validation uses Claude CLI 2.1.270.
 - Event-driven JSONL `control_request`/`result`/exit events, permission responses, persistent Pi Decision Worker automation, bounded duplicate/turn handling, and outbound human-intervention webhooks.
 - Long-task defaults are now 100 automatic turns, 4 hours wall time and 20 minutes without output; Decision Worker API failures alert human operators directly instead of attempting an LLM fallback.
 - Automatic Decision Worker sessions now persist as Pi JSONL with a 0600 task registry. Unclean Pi restarts expose explicit `/supervise recover <task-id>` recovery; Claude work is not silently duplicated.
@@ -47,5 +67,5 @@ All notable changes to this project will be documented here.
 
 ### Limitations
 
-- PTY transport and cross-version Claude CLI permission/session semantics are out of scope for this pinned release; Claude JSONL support remains opt-in outside automatic mode. The installed 2.1.268 CLI is covered by local permission and signal spikes, while the cgroup startup-attachment window remains.
+- tmux/PTY screen state is not Claude JSONL: trust, permission and ambiguous TUI states require human handling. Cross-version Claude CLI permission/session semantics remain outside the pinned compatibility claim. Historical permission and signal spikes use 2.1.268; current tmux validation uses 2.1.270, while the cgroup startup-attachment window remains.
 - No automatic merge, deployment, release or publication is implemented.

package/README.cn.md

@@ -42,9 +42,9 @@ 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；不会依赖 `/supervise poll` 轮询。本版本固定按已验证设备的
-Claude CLI `2.1.268` 运行，跨版本兼容性不在本轮范围内。
+自动模式默认使用 `claude-jsonl`，通过 `result`、`control_request` 和进程
+`exit` 事件唤醒 Decision Worker；显式选择 tmux 时仍使用屏幕交互，不使用 JSONL 权限协议，也不会依赖 `/supervise poll` 轮询。本版本固定按已验证设备的
+Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 
 然后在 Pi 中使用：
 
@@ -84,6 +84,39 @@ Claude CLI `2.1.268` 运行，跨版本兼容性不在本轮范围内。
 再根据任务和仓库证据自动回答；无法确定时才升级人工。如需微信内闭环，需要另建带签名验证、
 一次性 action token 和重放保护的入站 callback 服务。
 
+### tmux/PTY 交互模式
+
+如果希望在可见的 Claude Code 终端中工作，可显式启用 tmux transport：
+
+```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 server 时可选：
+# export PI_CLAUDE_SUPERVISOR_TMUX_SOCKET=/path/to/tmux.sock
+```
+
+`/supervise start <task>` 会在私有 tmux server 中启动 Claude，并返回可复制的 attach 命令。
+可以在另一个终端 attach 到同一个 PTY，观察或人工输入。多行消息通过 tmux buffer 和 Enter
+发送，不会把消息拼接进 shell 命令；`pipe-pane` 记录原始输出，`capture-pane` 检测稳定的 Claude
+输入提示，并复用 watchdog、Decision Worker、审计和独立验收流程。
+
+如果 Claude 已由你在 tmux 中启动，可以显式接管且不会重放原始任务：
+
+```text
+/supervise adopt-tmux <tmux-session-name> <task description>
+```
+
+接管会检查 cwd、pane 中的进程，并拒绝已有其他输出 pipe 的 pane；但不宣称拥有该 session。对被接管的 session，
+`/supervise stop` 和 Pi 关闭只会断开监督，不会杀掉你的 tmux 窗口；需要关闭时请由你执行
+`tmux kill-session`。`/supervise takeover <task-id>` 会暂停 Decision Worker 自动发送，只有
+`/supervise resume-auto <task-id>` 才恢复。
+
+PTY 屏幕文字不是 Claude JSONL。权限/信任对话框和无法确定的 TUI 状态必须升级人工，不能把
+屏幕文字当作结构化权限证据。普通终端里已经运行的 Claude 不能安全迁移进 tmux；`--resume`
+是读取历史的新进程，不是实时 attach。实时测试请使用 plan/read-only 参数。
+
 可以从不同工作目录启动多个任务会话；活动会话不能共享同一 cwd，建议每个任务使用独立 worktree：
 
 ```text

package/README.md

@@ -97,6 +97,49 @@ 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`.
 
+### tmux/PTY transport
+
+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
+# 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
+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.
+
+A session that you started yourself can be explicitly adopted without replaying
+the task:
+
+```text
+/supervise adopt-tmux <tmux-session-name> <task description>
+```
+
+Adoption checks the session's working directory and pane command, and refuses a
+pane that already has another output pipe. It does not claim ownership: `/supervise stop` and Pi shutdown detach supervision rather
+than killing the user's tmux session. Use `tmux 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.
+
 ## Development
 
 ```bash

package/docs/architecture.md

@@ -39,8 +39,9 @@ are also awaited during Pi shutdown.
 
 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`) forces Claude JSONL and uses the CLI contract
-validated by the fixed-version spike.
+(`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.
 
 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
@@ -59,6 +60,47 @@ The Pi host installs graceful `SIGTERM`/`SIGINT` handlers, but `SIGSTOP` and
 `SIGKILL` cannot be handled; no orphan guarantee is claimed for those 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
+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.
+
+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.
+
+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`.
+
+`/supervise adopt-tmux` is explicit and validates the pinned pane's cwd and
+process identity before attaching. Every later input, capture and signal uses
+that immutable pane target; a replacement process is refused. Adopted sessions
+are not owned: stop and Pi shutdown detach rather than kill them. Tmux commands
+and serialized input waits have bounded deadlines so shutdown cannot hang
+forever. Sessions started by the adapter also survive a Pi disconnect, but
+recovery after restart is explicit re-adoption; the extension never claims to
+attach to an arbitrary non-tmux PTY. A normal Claude
+`--resume` starts another process from history and is not a live PTY migration.
+
 ## State machine
 
 ```text
@@ -76,6 +118,34 @@ lifecycle event append fails after the state transition, it remains pending and
 is retried before the next lifecycle operation; output events restore their
 chunks for a lossless retry.
 
+### Cross-process cwd leases and startup cancellation
+
+Every start and explicit recovery acquires an atomic lease in the shared lease
+registry before spawning Claude. The default registry is
+`~/.pi/agent/claude-supervisor/cwd-leases`; `PI_CLAUDE_SUPERVISOR_CWD_LEASE_DIR`
+may point all Pi processes at an alternate shared directory. Canonical paths
+conflict with both their parents and descendants, and the registry lock
+serializes acquisition across independent Pi processes. A lease is released
+only after the adapter confirms the worker and its descendant cleanup; an
+unconfirmed lease left by a crashed Pi is intentionally retained and requires
+operator verification/manual cleanup rather than unsafe automatic reclamation.
+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
+cannot consume another task's lease. If post-start worker identity registration
+fails, owned workers are stopped before the lease is released; cleanup failure
+retains both the worker and lease fail-closed. Explicit `stop` cleans owned tmux
+sessions, while Pi shutdown detaches persistent sessions so they remain explicitly
+re-adoptable.
+
+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
+startup cleanup without waiting behind the serialized start operation. Each
+startup carries an opaque token, so cancelling one concurrent session cannot
+abort another. Process and tmux adapters terminate or detach their startup
+work, and the Supervisor rechecks cancellation before reporting `running`; a cancelled startup becomes
+`stopped` and never reports a worker that was not cleanup-verified.
+
 ## Event log
 
 Events are JSONL with a monotonic sequence number, timestamp, task ID and worker

package/docs/releasing.md

@@ -104,7 +104,8 @@ Major updates remain separate for explicit review. There is no blanket auto-merg
 A maintainer can retry an existing stable release from Actions:
 
 ```bash
-gh workflow run release.yml --ref main -f tag=v0.1.1
+TAG=v0.3.0
+gh workflow run release.yml --ref main -f tag="$TAG"
 ```
 
 The workflow verifies that the release tag is stable and belongs to `main`, then

package/docs/testing.md

@@ -28,6 +28,12 @@ the published TypeScript source directly and there is no second runtime bundle.
 - `worker/process-adapter.test.ts`: spawn failure is observable, JSONL framing and
   idempotent duplicate suppression work, and a child does not remain indefinitely
   in a running state.
+- `worker/tmux-adapter.test.ts`: an owned private tmux socket accepts multi-line
+  input, emits a stable-prompt turn event, preserves PTY output and cleans its
+  session on stop. It also verifies explicit idle startup does not submit a
+  blank turn, idle adoption emits no synthetic completion, adopted pipe
+  detachment permits re-adoption, and adopted stop preserves the user's
+  session.
 - `worker/environment.test.ts`: unrelated host credentials are excluded unless
   explicitly supplied.
 - `supervisor.test.ts`: the no-output watchdog stops a stalled worker, lifecycle event failures are retried, and output is restored when event persistence fails.
@@ -43,8 +49,11 @@ non-sensitive prompt, and prints protocol metadata rather than raw model output.
 It must not be added to the normal CI gate because authentication is an owner
 controlled prerequisite.
 
-The current fixtures validate one prompt, multiple turns, session resume,
+The historical fixtures validate one prompt, multiple turns, session resume,
 permission allow/deny and SIGTERM/SIGINT behavior with Claude Code 2.1.268.
+The current release validation 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.
 The automation spike additionally exercises a real Pi SDK Decision Worker with
@@ -64,10 +73,15 @@ npm run spike:signals
 npm run spike:automation
 SPIKE_AUTOMATION_PERMISSION=1 npm run spike:automation
 SPIKE_AUTOMATION_QUESTION=1 npm run spike:automation
+PI_CLAUDE_SUPERVISOR_REAL_CLAUDE=1 npm run spike:tmux
 ```
 
-For this release, pin and record Claude Code `2.1.268` and its resolved
-executable path. Record:
+The tmux spike is gated, authenticated, and excluded from normal CI. It uses
+plan mode, records only protocol metadata, and verifies two real Claude turns,
+pause/resume, owned detach, and identity-bound restart re-adoption.
+
+For each release, pin and record the validated Claude Code version and resolved
+executable path. For this release the validated version is `2.1.270`. Record:
 
 1. exact version and resolved executable path;
 2. license and source revision;
@@ -80,13 +94,24 @@ executable path. Record:
 A passing worker task is not sufficient. The independent verifier must repeat the
 relevant checks from a clean host perspective.
 
-Automatic mode is enabled with `PI_CLAUDE_SUPERVISOR_MODE=auto`; it forces JSONL
-and routes `result`, permission, and process-exit events to the persistent Pi
-Decision Worker. `process-pipe` remains the manual compatibility mode. Human
+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. 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. Human
 escalation is outbound-only through `PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL`;
 approval callbacks are deliberately not accepted without a separately
 authenticated endpoint.
 
+The tmux transport is selected with `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. Before
+release, manually verify: private-socket attach, multi-line paste, prompt
+stability while Claude is busy, trust/permission dialog takeover, duplicate
+send prevention, pane replacement refusal, pause/resume, owned-session stop,
+adopted-session detach/re-adoption, bounded shutdown, and Pi shutdown without
+closing an attached window. Use `--permission-mode plan`
+and read-only tools for live Claude checks. Do not run JSONL and tmux control
+against the same Claude process, and do not treat `capture-pane` text as a
+structured permission response.
+
 ## Failure injection
 
 The automated adapter matrix covers external `SIGTERM`, `SIGINT`, `SIGKILL`,

package/docs/transport-spike-2026-09-12.md

@@ -8,7 +8,7 @@ without exposing credentials or allowing repository changes.
 ## Environment
 
 - Node: `v26.8.1` (declared package minimum remains `>=22.19`)
-- Claude Code: `2.1.268`
+- Claude Code: `2.1.268` (historical headless probe; current release validation uses `2.1.270`)
 - Executable: resolved through `PATH` as `claude`
 - Working directory: `/home/yancao/Work`
 - Session persistence: disabled for the stateless fixture; enabled for the separate resume fixture
@@ -56,7 +56,7 @@ existing default remains generic `process-pipe`.
 
 ## Required follow-up
 
-Additional evidence was collected with Claude Code `2.1.268` using
+Historical permission evidence was collected with Claude Code `2.1.268` using
 `--permission-prompt-tool stdio --permission-mode default --tools Bash`:
 
 - The CLI emitted `control_request` with `request.subtype=can_use_tool`,
@@ -72,7 +72,7 @@ Additional evidence was collected with Claude Code `2.1.268` using
   decision at the wrong envelope level is rejected as an invalid permission
   result.
 
-The exact signal fixture also passed for `2.1.268`: after `system/init`, a group
+The exact signal fixture also passed for historical version `2.1.268`: after `system/init`, a group
 `SIGTERM` produced exit code `143` with no terminal result; group `SIGINT`
 produced exit code `0` and a terminal result with `terminal_reason=
 "aborted_streaming"` and `is_error=true`. The new adapter cgroup-v2 fixture
@@ -87,8 +87,8 @@ npm run spike:signals
 ```
 
 Remaining evidence is malformed/duplicate CLI input, no secret leakage in
-captured events, and the cgroup startup-attachment window. Release scope is
-pinned to Claude Code `2.1.268` on the validated device; cross-version
-portability is explicitly out of scope for this iteration. The adapter-level
-lifecycle track is now **GO** for the installed CLI and host; atomic OS process
-containment remains follow-up work.
+captured events, and the cgroup startup-attachment window. The current release
+also passed a real Claude Code `2.1.270` tmux validation: owned multi-turn
+interaction, pause/resume, explicit detach, and identity-bound restart
+re-adoption. The adapter-level lifecycle track is now **GO** for the installed
+CLI and host; atomic OS process containment remains follow-up work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {
@@ -56,6 +56,7 @@
     "test:install": "node scripts/test-install.mjs",
     "test:pi": "node scripts/test-pi.mjs",
     "spike:transport": "node scripts/spike-claude-transport.mjs",
+    "spike:tmux": "node scripts/spike-claude-tmux.mjs",
     "spike:permissions": "node scripts/spike-claude-permissions.mjs",
     "spike:signals": "node scripts/spike-claude-signals.mjs",
     "spike:automation": "node scripts/spike-claude-automation.mjs",

package/src/config.ts

@@ -1,13 +1,17 @@
 import { chmodSync, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { redactSensitive } from "./redaction.ts";
 
 const allowed = new Set([
   "PI_CLAUDE_SUPERVISOR_MODE",
   "PI_CLAUDE_SUPERVISOR_AUTOMATION",
   "PI_CLAUDE_SUPERVISOR_TRANSPORT",
+  "PI_CLAUDE_SUPERVISOR_CGROUP_MODE",
+  "PI_CLAUDE_SUPERVISOR_TMUX_SOCKET",
   "PI_CLAUDE_SUPERVISOR_WORKER",
   "PI_CLAUDE_SUPERVISOR_STATE_DIR",
+  "PI_CLAUDE_SUPERVISOR_CWD_LEASE_DIR",
   "PI_CLAUDE_SUPERVISOR_WORKER_ENV",
   "PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL",
   "PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_FORMAT",
@@ -29,7 +33,7 @@ export function loadSupervisorEnvironment(): string | undefined {
     }
     return path;
   } catch (error) {
-    console.error(`pi-claude-supervisor could not read env file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    console.error(`pi-claude-supervisor could not read env file ${String(redactSensitive(path))}: ${String(redactSensitive(error instanceof Error ? error.message : String(error)))}`);
     return undefined;
   }
 }