pi-claude-supervisor 0.2.2 → 0.3.0

package/src/index.ts

@@ -3,7 +3,9 @@ import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { realpath } from "node:fs/promises";
 import { EventLog } from "./events.ts";
+import { redactSensitive } from "./redaction.ts";
 import { ProcessWorkerAdapter } from "./worker/process-adapter.ts";
+import { TmuxWorkerAdapter, attachCommand } from "./worker/tmux-adapter.ts";
 import { Supervisor } from "./supervisor.ts";
 import { evaluateCommand } from "./policy.ts";
 import { HumanWebhookNotifier } from "./notifications.ts";
@@ -20,17 +22,24 @@ import { DecisionSessionStore, type DecisionSessionRecord } from "./decision-ses
 export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   loadSupervisorEnvironment();
   const automation = process.env.PI_CLAUDE_SUPERVISOR_MODE === "auto" || process.env.PI_CLAUDE_SUPERVISOR_AUTOMATION === "1";
-  const adapter = new ProcessWorkerAdapter({
-    // Automatic decisions require Claude's structured event stream. The pipe
-    // transport remains available for manual/compatibility sessions.
-    mode: automation || process.env.PI_CLAUDE_SUPERVISOR_TRANSPORT === "jsonl" ? "claude-jsonl" : "process-pipe",
-  });
+  const stateDir = process.env.PI_CLAUDE_SUPERVISOR_STATE_DIR ?? join(homedir(), ".pi", "agent", "claude-supervisor");
+  const configuredTransport = process.env.PI_CLAUDE_SUPERVISOR_TRANSPORT;
+  const transport = configuredTransport ?? (automation ? "jsonl" : "process-pipe");
+  if (!(["process-pipe", "jsonl", "tmux"] as string[]).includes(transport)) {
+    throw new Error(`Unsupported PI_CLAUDE_SUPERVISOR_TRANSPORT: ${transport}; expected process-pipe, jsonl, or tmux`);
+  }
+  const adapter = transport === "tmux"
+    ? new TmuxWorkerAdapter({ stateDir })
+    : 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",
+    });
   const humanWebhook = new HumanWebhookNotifier({
     url: process.env.PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL,
     format: process.env.PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_FORMAT === "wecom" ? "wecom" : "generic",
     secret: process.env.PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_SECRET,
   });
-  const stateDir = process.env.PI_CLAUDE_SUPERVISOR_STATE_DIR ?? join(homedir(), ".pi", "agent", "claude-supervisor");
   const events = new EventLog(join(stateDir, "events.jsonl"));
   const decisionStore = new DecisionSessionStore(join(stateDir, "decision-sessions"));
   const sessions = new Map<string, Supervisor>();
@@ -43,7 +52,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   let shutdownPromise: Promise<void> | undefined;
 
   const notify = (ctx: ExtensionContext, message: string, type: "info" | "warning" = "info") => {
-    if (ctx.hasUI) ctx.ui.notify(message, type);
+    if (ctx.hasUI) ctx.ui.notify(redactText(message), type);
   };
   const activeSessions = () => [...sessions.entries()].filter(([, session]) =>
     ["starting", "running", "waiting", "paused"].includes(session.state));
@@ -63,6 +72,14 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     }
   };
   const stopSession = async (session: Supervisor, reason: string): Promise<void> => {
+    const handle = session.handle;
+    const persistent = adapter.capabilities().persistentSession && Boolean(handle);
+    const adoptedPersistent = persistent && handle?.ownership === "adopted";
+    const healthyPersistent = persistent && !["failed", "completed", "stopped"].includes(session.state);
+    if (adoptedPersistent || healthyPersistent) {
+      await session.release(reason);
+      return;
+    }
     let lifecycleError: unknown;
     try {
       await session.stop(reason);
@@ -70,7 +87,6 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
       lifecycleError = error;
     }
 
-    const handle = session.handle;
     if (!handle) {
       if (lifecycleError) throw lifecycleError;
       return;
@@ -81,7 +97,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     while (Date.now() <= deadline) {
       try {
         const status = await adapter.getStatus(handle);
-        if (!status.running && status.processGroupCleaned === true) {
+        if (!status.running && status.processGroupCleaned === true && !status.cleanupError) {
           if (lifecycleError) throw lifecycleError;
           return;
         }
@@ -109,9 +125,11 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
         const tokens = args.trim() ? args.trim().split(/\s+/u) : [];
         const [operation = "status", ...rest] = tokens;
         let message = "";
-        if (operation === "start") {
+        if (operation === "start" || operation === "adopt-tmux") {
+          const tmuxSession = operation === "adopt-tmux" ? rest.shift() : undefined;
           const task = rest.join(" ").trim();
-          if (!task) throw new Error("Usage: /supervise start <task>");
+          if (!task) throw new Error(operation === "adopt-tmux" ? "Usage: /supervise adopt-tmux <tmux-session> <task>" : "Usage: /supervise start <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");
           if (!command) throw new Error("PI_CLAUDE_SUPERVISOR_WORKER must contain an executable");
           const policy = evaluateCommand(command, workerArgs);
@@ -137,15 +155,15 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           pendingCwds.add(cwdKey);
           const session = new Supervisor(adapter, events, {
             onHumanRequired: async (notice) => {
-              if (ctx.hasUI) ctx.ui.notify(`Claude Worker needs human intervention: ${notice.reason}`, "warning");
+              if (ctx.hasUI) notify(ctx, `Claude Worker needs human intervention: ${notice.reason}`, "warning");
               if (humanWebhook.enabled) {
                 try {
                   await humanWebhook.notify(notice);
                 } catch (error) {
-                  console.error(`pi-claude-supervisor human webhook failed: ${error instanceof Error ? error.message : String(error)}`);
+                  console.error(`pi-claude-supervisor human webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`);
                 }
               } else {
-                console.error(`pi-claude-supervisor human intervention required: ${notice.reason}`);
+                console.error(`pi-claude-supervisor human intervention required: ${redactText(notice.reason)}`);
               }
             },
           });
@@ -160,6 +178,9 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 env: selectedWorkerEnvironment(),
                 approval,
                 automation,
+                tmuxSession,
+                tmuxSocket: process.env.PI_CLAUDE_SUPERVISOR_TMUX_SOCKET,
+                sendInitialInput: !tmuxSession,
                 decisionSessionDir: decisionStore.directory,
                 onDecisionSessionReady: (info) => decisionStore.save({
                   taskId: info.taskId,
@@ -200,7 +221,8 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 }
                 throw new Error("Pi session shut down during worker start");
               }
-              message = `Worker started: task=${taskId} worker=${handle.id} (pid ${handle.pid ?? "unknown"}); transport=${adapter.capabilities().transport}`;
+              const attach = handle.sessionName ? ` attach=${attachCommand(handle)}` : "";
+              message = `${tmuxSession ? "Tmux worker adopted" : "Worker started"}: task=${taskId} worker=${handle.id} (pid ${handle.pid ?? "unknown"}); transport=${adapter.capabilities().transport}${attach}`;
             } catch (error) {
               // Register failed starts before the promise settles, so shutdown
               // cannot snapshot sessions before a returned handle is retained.
@@ -263,12 +285,12 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           pendingCwds.add(cwdKey);
           const session = new Supervisor(adapter, events, {
             onHumanRequired: async (notice) => {
-              if (ctx.hasUI) ctx.ui.notify(`Claude Worker needs human intervention: ${notice.reason}`, "warning");
+              if (ctx.hasUI) notify(ctx, `Claude Worker needs human intervention: ${notice.reason}`, "warning");
               if (humanWebhook.enabled) {
                 try { await humanWebhook.notify(notice); }
-                catch (error) { console.error(`pi-claude-supervisor human webhook failed: ${error instanceof Error ? error.message : String(error)}`); }
+                catch (error) { console.error(`pi-claude-supervisor human webhook failed: ${redactText(error instanceof Error ? error.message : String(error))}`); }
               } else {
-                console.error(`pi-claude-supervisor human intervention required: ${notice.reason}`);
+                console.error(`pi-claude-supervisor human intervention required: ${redactText(notice.reason)}`);
               }
             },
           });
@@ -282,6 +304,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 // must explicitly send the next instruction.
                 task: record.task,
                 initialInput: "",
+                sendInitialInput: false,
                 cwd: record.cwd,
                 command: record.command,
                 args: record.args,
@@ -386,7 +409,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           } else if (operation === "resume-auto") {
             await session.resumeAutomation(); message = `Automatic decisions resumed: ${sessionId}.`;
           } else {
-            throw new Error("Usage: /supervise start|recover|sessions|status|poll [all|taskId]|send [taskId]|pause [taskId]|resume [taskId]|stop [taskId]|verify [taskId]|approve [taskId] <allow|deny>|takeover [taskId]|resume-auto [taskId]|capabilities");
+            throw new Error("Usage: /supervise start|adopt-tmux|recover|sessions|status|poll [all|taskId]|send [taskId]|pause [taskId]|resume [taskId]|stop [taskId]|verify [taskId]|approve [taskId] <allow|deny>|takeover [taskId]|resume-auto [taskId]|capabilities");
           }
         }
         notify(ctx, message);
@@ -401,15 +424,20 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
     shuttingDown = true;
     shutdownPromise = (async () => {
       const pending = [...pendingStarts];
+      let startupFailures: PromiseRejectedResult[] = [];
       await Promise.race([Promise.allSettled(pending), delay(5_000)]);
       if (pendingStarts.size > 0) {
-        await Promise.allSettled([...pendingStartSessions].map((session) => session.abortStart("Pi session shutdown during startup")));
-        await Promise.race([Promise.allSettled([...pendingStarts]), delay(5_000)]);
+        const abortResults = await Promise.allSettled([...pendingStartSessions].map((session) => session.abortStart("Pi session shutdown during startup")));
+        startupFailures = abortResults.filter((result): result is PromiseRejectedResult => result.status === "rejected");
+        // Startup adapters own their cleanup and expose bounded cancellation;
+        // do not exit while one of those cleanups is still in flight. A model
+        // provider can still fail to honor disposal, so retain a final bound.
+        await Promise.race([Promise.allSettled([...pendingStarts]), delay(30_000)]);
       }
       const results = await Promise.allSettled([...sessions.values()].map((session) => stopSession(session, "Pi session shutdown")));
-      const failures = results.filter((result): result is PromiseRejectedResult => result.status === "rejected");
+      const failures = [...startupFailures, ...results.filter((result): result is PromiseRejectedResult => result.status === "rejected")];
       if (failures.length > 0) {
-        for (const failure of failures) console.error(`pi-claude-supervisor shutdown cleanup failed: ${failure.reason instanceof Error ? failure.reason.message : String(failure.reason)}`);
+        for (const failure of failures) console.error(`pi-claude-supervisor shutdown cleanup failed: ${redactText(failure.reason instanceof Error ? failure.reason.message : String(failure.reason))}`);
         if (exitCode === undefined) process.exitCode = 1;
       }
       if (exitCode !== undefined) process.exitCode = exitCode;
@@ -493,8 +521,5 @@ function delay(ms: number): Promise<void> {
 }
 
 function redactText(value: string): string {
-  return value
-    .replace(/\b(sk-ant-[A-Za-z0-9_-]+)\b/gu, "[REDACTED]")
-    .replace(/\b(Bearer\s+)[^\s]+/giu, "$1[REDACTED]")
-    .replace(/(--?(?:token|api[-_]?key|secret|password|authorization)(?:=|\s+))[^\s]+/giu, "$1[REDACTED]");
+  return String(redactSensitive(value));
 }

package/src/notifications.ts

@@ -1,5 +1,6 @@
 import { createHmac, randomUUID } from "node:crypto";
 import type { HumanInterventionNotice } from "./supervisor.ts";
+import { redactSensitive } from "./redaction.ts";
 
 export interface HumanWebhookOptions {
   url?: string;
@@ -46,38 +47,36 @@ function toGeneric(notice: HumanInterventionNotice): Record<string, unknown> {
     eventId: randomUUID(),
     event: "human_intervention_required",
     occurredAt: new Date().toISOString(),
-    task: { id: notice.taskId, goal: notice.task, cwd: notice.cwd },
-    worker: { id: notice.workerId },
-    reason: notice.reason,
-    question: notice.question,
-    permission: notice.permission ? { ...notice.permission, input: sanitize(notice.permission.input) } : undefined,
+    task: { id: sanitize(notice.taskId), goal: sanitize(notice.task), cwd: sanitize(notice.cwd) },
+    worker: { id: sanitize(notice.workerId) },
+    reason: sanitize(notice.reason),
+    question: sanitize(notice.question),
+    permission: notice.permission ? sanitize(notice.permission) : undefined,
     actions: ["approve_or_deny_permission", "send_instruction", "stop_worker", "takeover"],
     note: "This is an outbound notification. Use the Pi session or a separately authenticated callback service to approve actions.",
   };
 }
 
 function toWeCom(notice: HumanInterventionNotice): Record<string, unknown> {
-  const permission = notice.permission ? `\n工具: ${notice.permission.toolName}\n请求 ID: ${notice.permission.requestId}` : "";
-  const question = notice.question ? `\n问题: ${notice.question}` : "";
+  const permission = notice.permission ? `\n工具: ${safeText(notice.permission.toolName)}\n请求 ID: ${safeText(notice.permission.requestId)}` : "";
+  const question = notice.question ? `\n问题: ${safeText(notice.question)}` : "";
   return {
     msgtype: "markdown",
     markdown: {
-      content: `### Claude Supervisor 需要人工介入\n> 任务: ${escapeMarkdown(notice.task)}\n> Task ID: ${notice.taskId}\n> 原因: ${escapeMarkdown(notice.reason)}${escapeMarkdown(question)}${escapeMarkdown(permission)}\n\n请在 Pi 中执行对应的 approve/deny、send、stop 或 takeover 操作。`,
+      content: `### Claude Supervisor 需要人工介入\n> 任务: ${safeText(notice.task)}\n> Task ID: ${safeText(notice.taskId)}\n> 原因: ${safeText(notice.reason)}${escapeMarkdown(question)}${escapeMarkdown(permission)}\n\n请在 Pi 中执行对应的 approve/deny、send、stop 或 takeover 操作。`,
     },
   };
 }
 
 function sanitize(value: unknown, key?: string): unknown {
-  if (key && /(password|secret|token|api[-_]?key|authorization|credential)/iu.test(key)) return "[REDACTED]";
-  if (typeof value === "string") {
-    return value
-      .replace(/\\b(sk-ant-[A-Za-z0-9_-]+)\\b/gu, "[REDACTED]")
-      .replace(/\\b(Bearer\\s+)[^\\s]+/giu, "$1[REDACTED]")
-      .slice(0, 4_000);
-  }
+  if (typeof value === "string") return String(redactSensitive(value, key)).slice(0, 4_000);
   if (Array.isArray(value)) return value.slice(0, 50).map((item) => sanitize(item, key));
   if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).slice(0, 50).map(([childKey, childValue]) => [childKey, sanitize(childValue, childKey)]));
-  return value;
+  return redactSensitive(value, key);
+}
+
+function safeText(value: unknown): string {
+  return String(sanitize(value));
 }
 
 function escapeMarkdown(value: string): string {

package/src/redaction.ts

@@ -0,0 +1,20 @@
+const sensitiveKeyPattern = /(password|secret|token|api[-_]?key|authorization|credential)/iu;
+
+/** Recursively redact credential-shaped values before persistence or model prompts. */
+export function redactSensitive(value: unknown, key?: string): unknown {
+  if (key && sensitiveKeyPattern.test(key)) return "[REDACTED]";
+  if (typeof value === "string") {
+    return value
+      .replace(/\b(sk-ant-[A-Za-z0-9_-]+)\b/gu, "[REDACTED]")
+      .replace(/\b(?:gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}|npm_[A-Za-z0-9]{20,})\b/gu, "[REDACTED]")
+      .replace(/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/gu, "[REDACTED]")
+      .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[REDACTED]")
+      .replace(/\b(Bearer\s+)[^\s]+/giu, "$1[REDACTED]")
+      .replace(/\b((?:AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN|[A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)))=([^\s]+)/gu, "$1=[REDACTED]")
+      .replace(/\b((?:authorization|x-api-key|api-key)\s*:\s*)[^\s]+/giu, "$1[REDACTED]")
+      .replace(/(--?(?:token|api[-_]?key|secret|password|authorization)(?:=|\s+))[^\s]+/giu, "$1[REDACTED]");
+  }
+  if (Array.isArray(value)) return value.map((item) => redactSensitive(item, key));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([childKey, childValue]) => [childKey, redactSensitive(childValue, childKey)]));
+  return value;
+}

package/src/supervisor.ts

@@ -5,6 +5,7 @@ import { SupervisorStateMachine } from "./state.ts";
 import { evaluatePermission } from "./policy.ts";
 import { PiDecisionWorker, type DecisionAction } from "./decision-worker.ts";
 import { verify, type VerificationCommand } from "./verifier.ts";
+import { redactSensitive } from "./redaction.ts";
 import type {
   TaskContext,
   VerificationResult,
@@ -48,7 +49,13 @@ export interface SupervisorStartOptions {
   noOutputTimeoutMs?: number;
   /** Human approval for a review-level worker command. */
   approval?: { actor: "human"; reason: string };
-  /** Enable the event-driven Pi Decision Worker. Requires claude-jsonl. */
+  /** Adopt an existing tmux session instead of starting a new worker. */
+  tmuxSession?: string;
+  /** Optional socket path for an existing non-default tmux server. */
+  tmuxSocket?: string;
+  /** Do not replay the task when adopting an existing interactive session. */
+  sendInitialInput?: boolean;
+  /** Enable the event-driven Pi Decision Worker. Requires claude-jsonl or tmux. */
   automation?: boolean;
   /** Persistent Pi session location for the Decision Worker. */
   decisionSessionFile?: string;
@@ -141,8 +148,8 @@ export class Supervisor {
           ...(options.approval ? { approval: options.approval } : {}),
         },
       });
-      if (this.#automation && this.#adapter.capabilities().transport !== "jsonl") {
-        throw new Error("automatic supervision requires claude-jsonl transport");
+      if (this.#automation && !["jsonl", "tmux"].includes(this.#adapter.capabilities().transport)) {
+        throw new Error("automatic supervision requires claude-jsonl or tmux transport");
       }
       if (this.#automation) {
         this.#decision = new PiDecisionWorker({
@@ -173,6 +180,9 @@ export class Supervisor {
         args: options.args,
         env: options.env,
         approval: options.approval,
+        tmuxSession: options.tmuxSession,
+        tmuxSocket: options.tmuxSocket,
+        sendInitialInput: options.sendInitialInput,
         eventListener: (event) => this.#receiveWorkerEvent(event),
       };
       this.#handle = await this.#adapter.start(input);
@@ -181,8 +191,9 @@ export class Supervisor {
       this.#armWatchdog();
       return this.#handle;
     } catch (error) {
-      const startFailureHandle = (error as { workerHandle?: WorkerHandle }).workerHandle;
-      if (!this.#handle && startFailureHandle?.pid) this.#handle = startFailureHandle;
+      const startFailure = error as { workerHandle?: WorkerHandle; workerCleanupRequired?: boolean };
+      const startFailureHandle = startFailure.workerHandle;
+      if (!this.#handle && startFailureHandle && (startFailure.workerCleanupRequired || startFailureHandle.ownership || startFailureHandle.sessionName)) this.#handle = startFailureHandle;
       const handle = this.#handle;
       if (handle) {
         try {
@@ -289,7 +300,7 @@ export class Supervisor {
     }
     try {
       if (this.#onHumanRequired) await this.#onHumanRequired(notice);
-      else console.error(`pi-claude-supervisor human intervention required: ${reason}`);
+      else console.error(`pi-claude-supervisor human intervention required: ${safeMessage(reason)}`);
     } catch (notifyError) {
       console.error(`pi-claude-supervisor human intervention notification failed: ${safeMessage(notifyError)}`);
     }
@@ -350,6 +361,11 @@ export class Supervisor {
         return;
       }
       if (action.action === "verify") {
+        if (this.#machine.state === "waiting" && this.#adapter.capabilities().persistentSession) {
+          this.#machine.transition("verifying");
+          await this.#verifyInternal();
+          return;
+        }
         if (this.#machine.state === "waiting") {
           await this.#adapter.stop(handle, "Decision Worker requested verification");
           await this.#pollInternal(true);
@@ -393,7 +409,7 @@ export class Supervisor {
     // Alert delivery is independent from event-log persistence: a broken audit
     // path must not suppress the operator notification.
     if (this.#onHumanRequired) await this.#onHumanRequired(notice);
-    else console.error(`pi-claude-supervisor human intervention required: ${reason}`);
+    else console.error(`pi-claude-supervisor human intervention required: ${safeMessage(reason)}`);
     if (logError) throw logError;
   }
 
@@ -440,7 +456,9 @@ export class Supervisor {
     if (!["running", "waiting"].includes(this.#machine.state)) throw new Error(`cannot send from ${this.#machine.state}`);
     const status = await this.#adapter.getStatus(handle);
     if (status.activeRequests !== undefined && status.activeRequests > 0) {
-      throw new Error("worker has an active JSONL request; poll until its result before sending another turn");
+      throw new Error(this.#adapter.capabilities().transport === "jsonl"
+        ? "worker has an active JSONL request; poll until its result before sending the next turn"
+        : "worker has an active turn; wait until its interactive prompt or structured result is ready before sending another turn");
     }
     if (status.activeRequests === 0 && this.#machine.state === "running") {
       this.#machine.transition("waiting");
@@ -480,9 +498,35 @@ export class Supervisor {
   async abortStart(reason = "startup aborted"): Promise<void> {
     // This path intentionally bypasses #exclusive(): start() may be blocked in
     // a Decision Worker model call and shutdown must still dispose that session.
+    let cleanupError: unknown;
+    const abort = this.#adapter.abortStart?.(reason);
+    if (abort) {
+      try { await abort; }
+      catch (error) { cleanupError = error; }
+    }
     await this.#decision?.close().catch(() => {});
     this.#decision = undefined;
-    if (this.#handle) await this.#adapter.stop(this.#handle, reason).catch(() => {});
+    if (this.#handle) {
+      try { await this.#adapter.stop(this.#handle, reason); }
+      catch (error) { cleanupError ??= error; }
+    }
+    if (cleanupError) throw cleanupError;
+  }
+
+  async release(reason = "Pi session disconnected"): Promise<void> {
+    const handle = this.#handle;
+    const preemptiveRelease = handle
+      ? this.#adapter.release
+        ? this.#adapter.release(handle, reason)
+        : this.#adapter.stop(handle, reason)
+      : this.#adapter.abortStart?.(reason) ?? Promise.resolve();
+    await this.#decision?.close().catch(() => {});
+    this.#decision = undefined;
+    await withTimeout(this.#exclusive(async () => {
+      this.#clearWatchdog();
+      await preemptiveRelease;
+      if (handle) await this.#appendEvent({ type: "worker_released", taskId: this.#task?.taskId, workerId: handle.id, data: { reason } });
+    }), 15_000, "persistent worker release");
   }
 
   async stop(reason = "human requested stop"): Promise<void> {
@@ -509,19 +553,44 @@ export class Supervisor {
       await Promise.resolve(this.#onDecisionSessionClosed?.(this.#task?.taskId ?? "")).catch(() => {});
       return;
     }
+    if (this.#machine.state === "completed") {
+      if (this.#handle) {
+        await this.#adapter.stop(this.#handle, reason);
+        await this.#drainOutputAfterStop(this.#handle);
+      }
+      return;
+    }
     if (!["running", "waiting", "paused", "starting"].includes(this.#machine.state)) return;
     this.#clearWatchdog();
     const preemptiveStop = this.#preemptiveStop;
     this.#preemptiveStop = undefined;
     if (preemptiveStop) await preemptiveStop;
     else await this.#adapter.stop(this.#handle, reason);
+    let outputError: unknown;
+    try {
+      await this.#drainOutputAfterStop(this.#handle);
+    } catch (error) {
+      outputError = error;
+    }
     this.#machine.transition("stopped");
     await this.#appendEvent({ type: "worker_stopped", taskId: this.#task?.taskId, workerId: this.#handle.id, data: { reason } });
+    if (outputError) throw outputError;
     await this.#decision?.close().catch(() => {});
     this.#decision = undefined;
     await Promise.resolve(this.#onDecisionSessionClosed?.(this.#task?.taskId ?? "")).catch(() => {});
   }
 
+  async #drainOutputAfterStop(handle: WorkerHandle): Promise<void> {
+    const output = await this.#adapter.readOutput(handle);
+    if (!output.length) return;
+    try {
+      await this.#appendEvent({ type: "worker_output", taskId: this.#task?.taskId, workerId: handle.id, data: { chunks: output } });
+    } catch (error) {
+      if (this.#adapter.restoreOutput) await this.#adapter.restoreOutput(handle, output).catch(() => {});
+      throw error;
+    }
+  }
+
   async verify(command?: VerificationCommand): Promise<VerificationResult> {
     return this.#exclusive(() => this.#verifyInternal(command));
   }
@@ -529,17 +598,70 @@ export class Supervisor {
   async #verifyInternal(command?: VerificationCommand): Promise<VerificationResult> {
     await this.#flushPendingEvents();
     if (!this.#task) throw new Error("no active task");
+    if (this.#machine.state === "waiting" && this.#adapter.capabilities().persistentSession) this.#machine.transition("verifying");
     if (this.#machine.state !== "verifying") throw new Error(`cannot verify from ${this.#machine.state}`);
-    const result = await verify(this.#task.cwd, command);
+    let result: VerificationResult;
+    try {
+      result = await verify(this.#task.cwd, command);
+    } catch (error) {
+      await this.#failVerification(error);
+      throw error;
+    }
+    this.#clearWatchdog();
+    let cleanupError: unknown;
+    if (this.#handle) {
+      try {
+        await this.#adapter.stop(this.#handle, result.ok ? "verification passed" : "verification failed");
+        await this.#drainOutputAfterStop(this.#handle);
+        const cleanup = await this.#adapter.getStatus(this.#handle);
+        if (cleanup.cleanupError) throw new Error(`worker cleanup failed after verification: ${cleanup.cleanupError}`);
+        if (this.#handle.ownership === "owned" && (cleanup.running || cleanup.processGroupCleaned !== true)) {
+          throw new Error("owned worker cleanup was not confirmed after verification");
+        }
+      } catch (error) {
+        cleanupError = error;
+      }
+    }
     this.#lastVerification = result;
-    this.#machine.transition(result.ok ? "completed" : "failed");
-    await this.#appendEvent({ type: result.ok ? "verification_passed" : "verification_failed", taskId: this.#task.taskId, workerId: this.#handle?.id, data: { ...result } });
+    const verificationSucceeded = result.ok && !cleanupError;
+    this.#machine.transition(verificationSucceeded ? "completed" : "failed");
+    await this.#appendEvent({ type: verificationSucceeded ? "verification_passed" : "verification_failed", taskId: this.#task.taskId, workerId: this.#handle?.id, data: { ...result, ...(cleanupError ? { cleanupError: safeMessage(cleanupError) } : {}) } });
     await this.#decision?.close().catch(() => {});
     this.#decision = undefined;
     await Promise.resolve(this.#onDecisionSessionClosed?.(this.#task.taskId)).catch(() => {});
+    if (cleanupError) throw cleanupError;
     return result;
   }
 
+  async #failVerification(error: unknown): Promise<void> {
+    this.#clearWatchdog();
+    let cleanupError: unknown;
+    if (this.#handle) {
+      try {
+        await this.#adapter.stop(this.#handle, "verification failed");
+        await this.#drainOutputAfterStop(this.#handle);
+      } catch (stopError) {
+        cleanupError = stopError;
+      }
+    }
+    if (this.#machine.state === "verifying") this.#machine.transition("failed");
+    if (this.#task) {
+      try {
+        await this.#appendEvent({
+          type: "verification_failed",
+          taskId: this.#task.taskId,
+          workerId: this.#handle?.id,
+          data: { error: safeMessage(error), ...(cleanupError ? { cleanupError: safeMessage(cleanupError) } : {}) },
+        });
+      } catch {
+        // Preserve the verifier error; the event remains a pending lifecycle record.
+      }
+      await this.#decision?.close().catch(() => {});
+      this.#decision = undefined;
+      await Promise.resolve(this.#onDecisionSessionClosed?.(this.#task.taskId)).catch(() => {});
+    }
+  }
+
   #armWatchdog(): void {
     if (this.#deadlineMs <= 0 && this.#noOutputTimeoutMs <= 0) return;
     this.#watchdog = setInterval(() => { void this.#checkWatchdog().catch(() => { /* lifecycle state is retained for the next explicit operation */ }); }, 1_000);
@@ -618,6 +740,19 @@ export class Supervisor {
   }
 }
 
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+    timer.unref();
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 function workerEventKey(event: WorkerEvent): string {
   if (event.type === "permission_request") return `${event.handle.id}:permission:${event.request.requestId}`;
   if (event.type === "turn_completed") return `${event.handle.id}:result:${event.sequence}`;
@@ -627,5 +762,5 @@ function workerEventKey(event: WorkerEvent): string {
 }
 
 function safeMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+  return String(redactSensitive(error instanceof Error ? error.message : String(error)));
 }

package/src/types.ts

@@ -36,6 +36,12 @@ export interface WorkerStartInput {
   env?: NodeJS.ProcessEnv;
   approval?: { actor: "human"; reason: string };
   eventListener?: WorkerEventListener;
+  /** Attach to an existing tmux session instead of starting a new worker. */
+  tmuxSession?: string;
+  /** Optional tmux socket path; omitted means the user's default server. */
+  tmuxSocket?: string;
+  /** Adopted sessions must not replay the task as a new user message. */
+  sendInitialInput?: boolean;
 }
 
 export interface WorkerHandle {
@@ -44,6 +50,9 @@ export interface WorkerHandle {
   startedAt: string;
   cwd: string;
   sessionId?: string;
+  sessionName?: string;
+  tmuxSocket?: string;
+  ownership?: "owned" | "adopted";
 }
 
 export interface WorkerStatus {
@@ -75,6 +84,8 @@ export interface PermissionDecision {
 export interface WorkerAdapter {
   capabilities(): WorkerCapabilities;
   start(input: WorkerStartInput): Promise<WorkerHandle>;
+  /** Cancel adapter-owned startup work before a WorkerHandle is returned. */
+  abortStart?(reason: string): Promise<void>;
   getStatus(handle: WorkerHandle): Promise<WorkerStatus>;
   readOutput(handle: WorkerHandle): Promise<WorkerOutputChunk[]>;
   /** Restore chunks when diagnostic event persistence fails before acknowledgement. */
@@ -87,6 +98,8 @@ export interface WorkerAdapter {
   pause(handle: WorkerHandle): Promise<void>;
   resume(handle: WorkerHandle): Promise<void>;
   stop(handle: WorkerHandle, reason: string): Promise<void>;
+  /** Disconnect the supervisor without stopping a persistent worker, if supported. */
+  release?(handle: WorkerHandle, reason: string): Promise<void>;
   killProcessGroup(handle: WorkerHandle, reason: string): Promise<void>;
   resumeSession(sessionId: string): Promise<WorkerHandle>;
 }
@@ -98,11 +111,13 @@ export interface WorkerOutputChunk {
 }
 
 export interface WorkerCapabilities {
-  transport: "process-pipe" | "pty" | "jsonl";
+  transport: "process-pipe" | "pty" | "jsonl" | "tmux";
   interactiveInput: boolean;
   pause: boolean;
   resumeSession: boolean;
   processGroupControl: boolean;
+  /** The worker can remain alive while Pi disconnects from it. */
+  persistentSession?: boolean;
 }
 
 export interface TaskContext {

package/src/worker/process-adapter.ts

@@ -192,7 +192,11 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
     } catch (error) {
       try { await this.#ensureGroupCleanup(record); } catch (cleanupError) { record.cleanupError = cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError)); }
       const startupError = error instanceof Error ? error : new Error(String(error));
-      Object.defineProperty(startupError, "workerHandle", { value: handle, enumerable: false });
+      if (record.cleanupError) {
+        startupError.message = `${startupError.message}; startup cleanup failed: ${record.cleanupError.message}`;
+        Object.defineProperty(startupError, "workerHandle", { value: handle, enumerable: false });
+        Object.defineProperty(startupError, "workerCleanupRequired", { value: true, enumerable: false });
+      }
       throw startupError;
     }
     if (input.task) {
@@ -200,7 +204,16 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
       try {
         await this.#writeInput(record, this.#encodeMessage(input.task));
       } catch (error) {
-        await this.stop(handle, "initial worker input failed");
+        let cleanupError: unknown;
+        try { await this.stop(handle, "initial worker input failed"); }
+        catch (stopError) { cleanupError = stopError; }
+        if (cleanupError) {
+          const startupError = error instanceof Error ? error : new Error(String(error));
+          startupError.message = `${startupError.message}; startup cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`;
+          Object.defineProperty(startupError, "workerHandle", { value: handle, enumerable: false });
+          Object.defineProperty(startupError, "workerCleanupRequired", { value: true, enumerable: false });
+          throw startupError;
+        }
         throw error;
       }
     }