pi-claude-supervisor 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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)
 
 

package/README.cn.md

@@ -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

@@ -127,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

@@ -136,7 +136,10 @@ 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.
+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

package/docs/testing.md

@@ -73,15 +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
 ```
 
 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:
+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;
@@ -103,14 +112,17 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {
@@ -57,6 +57,7 @@
     "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/index.ts

@@ -63,6 +63,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   let activeTaskId: string | undefined;
   let shuttingDown = false;
   let shutdownPromise: Promise<void> | undefined;
+  let detachedLeaseSweepTimer: NodeJS.Timeout | undefined;
 
   const notify = (ctx: ExtensionContext, message: string, type: "info" | "warning" = "info") => {
     if (ctx.hasUI) ctx.ui.notify(redactText(message), type);
@@ -81,29 +82,41 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
       return false;
     }
   };
+  const forgetSession = (taskId: string): void => {
+    sessions.delete(taskId);
+    reservedCwds.delete(taskId);
+    cleanupRequiredTasks.delete(taskId);
+    if (activeTaskId === taskId) activeTaskId = undefined;
+  };
   const releaseSettledReservations = async (): Promise<void> => {
     for (const [taskId, session] of sessions) {
-      if (!["completed", "stopped", "failed"].includes(session.state)) continue;
+      const terminal = ["completed", "stopped", "failed"].includes(session.state);
+      const detached = session.released;
+      if (!terminal && !detached) continue;
       if (!session.handle) {
-        if (await releaseLease(taskId)) {
-          reservedCwds.delete(taskId);
-          cleanupRequiredTasks.delete(taskId);
-        }
+        if (await releaseLease(taskId)) forgetSession(taskId);
         continue;
       }
       try {
         const status = await adapter.getStatus(session.handle);
-        if (!status.running && status.processGroupCleaned === true && !status.cleanupError && (!status.cgroupError || status.cgroupRequired === false)) {
-          if (await releaseLease(taskId)) {
-            reservedCwds.delete(taskId);
-            cleanupRequiredTasks.delete(taskId);
-          }
+        const adoptedDetachConfirmed = detached
+          && session.handle.ownership === "adopted"
+          && !status.running;
+        const cleanupConfirmed = status.processGroupCleaned === true || adoptedDetachConfirmed;
+        if (!status.running && cleanupConfirmed && !status.cleanupError && (!status.cgroupError || status.cgroupRequired === false)) {
+          if (await releaseLease(taskId)) forgetSession(taskId);
         }
       } catch {
         // Keep the reservation when cleanup status cannot be confirmed.
       }
     }
   };
+  detachedLeaseSweepTimer = setInterval(() => {
+    void releaseSettledReservations().catch((error) => {
+      console.error(`pi-claude-supervisor detached lease sweep failed: ${redactText(error instanceof Error ? error.message : String(error))}`);
+    });
+  }, 1_000);
+  detachedLeaseSweepTimer.unref();
   const stopSession = async (session: Supervisor, reason: string, releasePersistent = false): Promise<void> => {
     const handle = session.handle;
     const persistent = adapter.capabilities().persistentSession && Boolean(handle);
@@ -572,6 +585,10 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     if (shutdownPromise) return shutdownPromise;
     shuttingDown = true;
     shutdownPromise = (async () => {
+      if (detachedLeaseSweepTimer) {
+        clearInterval(detachedLeaseSweepTimer);
+        detachedLeaseSweepTimer = undefined;
+      }
       const pending = [...pendingStarts];
       let startupFailures: PromiseRejectedResult[] = [];
       await Promise.race([Promise.allSettled(pending), delay(5_000)]);

package/src/supervisor.ts

@@ -108,6 +108,7 @@ export class Supervisor {
   #startStopReason?: string;
   #startAbortError?: unknown;
   #startAbortCompletion?: Promise<void>;
+  #released = false;
 
   constructor(adapter: WorkerAdapter, events = new EventLog(), hooks: { onHumanRequired?: (notice: HumanInterventionNotice) => Promise<void> | void } = {}) {
     this.#adapter = adapter;
@@ -120,6 +121,8 @@ export class Supervisor {
   get handle() { return this.#handle; }
   get lastVerification() { return this.#lastVerification; }
   get humanRequired() { return this.#humanRequired; }
+  /** True after the persistent worker was detached from this Supervisor. */
+  get released() { return this.#released; }
 
   async start(options: SupervisorStartOptions): Promise<WorkerHandle> {
     return this.#exclusive(() => this.#startInternal(options));
@@ -139,6 +142,7 @@ export class Supervisor {
     this.#handledEvents.clear();
     this.#pendingPermissions.clear();
     this.#humanRequired = false;
+    this.#released = false;
     this.#task = { taskId, task: options.task, cwd: options.cwd, maxTurns: options.maxTurns ?? 100, startedAt: options.startedAt ?? new Date().toISOString() };
     this.#turn = options.initialTurn ?? 0;
     this.#deadlineMs = options.deadlineMs ?? 4 * 60 * 60_000;
@@ -584,6 +588,7 @@ export class Supervisor {
     await withTimeout(this.#exclusive(async () => {
       this.#clearWatchdog();
       await preemptiveRelease;
+      this.#released = true;
       if (handle) await this.#appendEvent({ type: "worker_released", taskId: this.#task?.taskId, workerId: handle.id, data: { reason } });
     }), 15_000, "persistent worker release");
   }

package/src/worker/tmux-adapter.ts

@@ -264,10 +264,16 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
         const pane = await this.#paneStatus(record);
         record.paneDead = pane.dead;
         record.panePid = pane.pid;
-        if (!pane.dead) await this.#rememberPaneIdentity(record, pane.pid);
+        if (pane.dead) record.cleanupError = undefined;
+        else await this.#rememberPaneIdentity(record, pane.pid);
       } catch (error) {
-        if (isMissingSession(error) || isPaneIdentityError(error)) record.paneDead = true;
-        else record.cleanupError = asError(error);
+        if (isMissingSession(error)) {
+          record.paneDead = true;
+          record.cleanupError = undefined;
+        } else if (isPaneIdentityError(error)) {
+          record.paneDead = false;
+          record.cleanupError = asError(error);
+        } else record.cleanupError = asError(error);
       }
       return this.#status(record, !record.paneDead);
     }
@@ -284,10 +290,11 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
     } catch (error) {
       if (isMissingSession(error)) {
         record.paneDead = true;
+        record.cleanupError = undefined;
         if (!record.cleanupComplete && record.owned) await this.#cleanup(record, false);
       } else {
         record.cleanupError = asError(error);
-        if (isPaneIdentityError(error)) record.paneDead = true;
+        if (isPaneIdentityError(error)) record.paneDead = false;
       }
     }
     return this.#status(record, !record.paneDead && !record.released);
@@ -485,7 +492,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
   #startMonitor(record: TmuxRecord): void {
     record.monitor = setInterval(() => {
       void this.#monitor(record).catch((error) => {
-        if (isPaneIdentityError(error)) record.paneDead = true;
+        if (isPaneIdentityError(error)) record.paneDead = false;
         if (!record.cleanupComplete && !isMissingSession(error)) record.cleanupError = asError(error);
       });
     }, this.#pollIntervalMs);