pi-claude-supervisor 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -2,12 +2,31 @@
 
 All notable changes to this project will be documented here.
 
+## [0.4.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.4.0...v0.4.1) (2026-09-14)
+
+
+### Bug Fixes
+
+* reconcile detached tmux leases and validate prompts ([d20262c](https://github.com/btnalit/pi-claude-supervisor/commit/d20262c8481ca761a48f7dc2b877951173d4681e))
+
+## [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)
 
@@ -47,7 +66,7 @@ All notable changes to this project will be documented here.
 - 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.
@@ -55,5 +74,5 @@ All notable changes to this project will be documented here.
 
 ### Limitations
 
-- 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. 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 中使用：
 
@@ -108,7 +108,9 @@ export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode plan'
 /supervise adopt-tmux <tmux-session-name> <task description>
 ```
 
-接管会检查 cwd、pane 中的进程，并拒绝已有其他输出 pipe 的 pane；但不宣称拥有该 session。对被接管的 session，
+接管会检查 cwd、pane 中的进程，并拒绝已有其他输出 pipe 的 pane；但不宣称拥有该 session。owned session 使用自动生成的私有 tmux socket，
+请保存 `start` 输出的完整 `attach=...` 命令。Pi 重启后重新接管时，先把该命令中的 socket 路径设置到
+`PI_CLAUDE_SUPERVISOR_TMUX_SOCKET`；只有默认 server 才能只使用 session 名称。对被接管的 session，
 `/supervise stop` 和 Pi 关闭只会断开监督，不会杀掉你的 tmux 窗口；需要关闭时请由你执行
 `tmux kill-session`。`/supervise takeover <task-id>` 会暂停 Decision Worker 自动发送，只有
 `/supervise resume-auto <task-id>` 才恢复。

package/README.md

@@ -104,6 +104,7 @@ 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:
@@ -126,11 +127,16 @@ the task:
 ```
 
 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>`.
+pane that already has another output pipe. Owned sessions use a generated
+private tmux socket, so preserve the complete `attach=...` command printed by
+`start`. When re-adopting after a Pi restart, set
+`PI_CLAUDE_SUPERVISOR_TMUX_SOCKET` to the socket path from that command before
+running `adopt-tmux`; the session name alone is sufficient only for the default
+server. Adoption 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

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
@@ -62,11 +63,14 @@ signals.
 ## tmux/PTY transport
 
 `TmuxWorkerAdapter` is an explicit second transport, selected with
-`PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. An owned worker gets a private tmux
-server/socket and a launcher file containing only the validated command, args and
-cwd. The worker environment is supplied to the tmux server through the same
-least-privilege environment builder; environment credentials are not copied into
-the launcher file; credential-shaped command arguments are rejected.
+`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.
@@ -114,6 +118,37 @@ 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. A detached adopted session retains its lease while the verified pane
+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.
+
+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

@@ -49,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
@@ -70,10 +73,24 @@ 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_PATH=/home/yancao/.local/share/mise/installs/claude/2.1.270/claude \
+PI_CLAUDE_SUPERVISOR_REAL_CLAUDE=1 npm run spike:tmux
+PI_CLAUDE_SUPERVISOR_REAL_CLAUDE_PATH=/home/yancao/.local/share/mise/installs/claude/2.1.270/claude \
+PI_CLAUDE_SUPERVISOR_REAL_CLAUDE=1 npm run spike:tmux-interactive
 ```
 
-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 with a fixed `opus` model, records only protocol metadata, and
+verifies three real Claude turns, exact screen-result markers, pause/resume,
+automation enabled with human takeover, direct human PTY input, owned detach,
+and identity-bound restart re-adoption. The interactive spike uses a fresh temporary
+cwd to verify Claude's trust prompt, a real Bash permission prompt, an allow-once
+response, and an exact result marker; it also records metadata only.
+
+For each release, pin and record the validated Claude Code version, resolved
+executable path, and model. The spikes reject an unpinned/mismatched executable
+version. For this release the validated version is `2.1.270` with model `opus`.
+Record:
 
 1. exact version and resolved executable path;
 2. license and source revision;
@@ -86,22 +103,26 @@ 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.
+release, 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. The two gated real-Claude spikes above cover the trust prompt,
+permission prompt, exact output, human takeover, and adopted detach paths. Use
+`--permission-mode plan` and read-only tools for ordinary live Claude checks;
+the interactive spike is restricted to one harmless `rm -f` in a disposable
+fresh directory. 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
 

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.3.0",
+  "version": "0.4.1",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {
@@ -56,6 +56,8 @@
     "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:tmux-interactive": "node scripts/spike-claude-tmux-interactive.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

@@ -7,9 +7,11 @@ 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",