pi-claude-supervisor 0.2.2 → 0.4.0

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,15 @@ 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;
+  /** Persisted identity required when handing off an existing tmux lease. */
+  tmuxExpectedIdentity?: WorkerStartInput["tmuxExpectedIdentity"];
+  /** 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;
@@ -94,6 +103,11 @@ export class Supervisor {
   #humanRequired = false;
   #onDecisionSessionProgress?: (info: { taskId: string; turn: number }) => Promise<void> | void;
   #onDecisionSessionClosed?: (taskId: string) => Promise<void> | void;
+  #startAbortController?: AbortController;
+  #startToken?: string;
+  #startStopReason?: string;
+  #startAbortError?: unknown;
+  #startAbortCompletion?: Promise<void>;
 
   constructor(adapter: WorkerAdapter, events = new EventLog(), hooks: { onHumanRequired?: (notice: HumanInterventionNotice) => Promise<void> | void } = {}) {
     this.#adapter = adapter;
@@ -131,6 +145,11 @@ export class Supervisor {
     this.#noOutputTimeoutMs = options.noOutputTimeoutMs ?? 20 * 60_000;
     this.#clearWatchdog();
     this.#machine.transition("starting");
+    const startAbortController = new AbortController();
+    this.#startAbortController = startAbortController;
+    this.#startToken = randomUUID();
+    this.#startStopReason = undefined;
+    this.#startAbortError = undefined;
     try {
       await this.#appendEvent({
         type: "task_started",
@@ -141,9 +160,10 @@ 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");
       }
+      this.#assertStartNotAborted(startAbortController.signal);
       if (this.#automation) {
         this.#decision = new PiDecisionWorker({
           context: { taskId, task: options.task, cwd: options.cwd, state: this.#machine.state, turn: this.#turn, maxTurns: this.#task.maxTurns },
@@ -166,6 +186,7 @@ export class Supervisor {
         });
         await this.#decision.start();
       }
+      this.#assertStartNotAborted(startAbortController.signal);
       const input: WorkerStartInput = {
         task: options.initialInput ?? options.task,
         cwd: options.cwd,
@@ -173,35 +194,68 @@ export class Supervisor {
         args: options.args,
         env: options.env,
         approval: options.approval,
+        tmuxSession: options.tmuxSession,
+        tmuxSocket: options.tmuxSocket,
+        tmuxExpectedIdentity: options.tmuxExpectedIdentity,
+        sendInitialInput: options.sendInitialInput,
         eventListener: (event) => this.#receiveWorkerEvent(event),
+        abortSignal: startAbortController.signal,
+        startupToken: this.#startToken,
       };
       this.#handle = await this.#adapter.start(input);
+      this.#assertStartNotAborted(startAbortController.signal);
       this.#machine.transition("running");
       await this.#appendEvent({ type: "worker_started", taskId, workerId: this.#handle.id, data: { pid: this.#handle.pid } });
       this.#armWatchdog();
+      this.#startAbortController = undefined;
+      this.#startToken = undefined;
+      this.#startStopReason = undefined;
+      this.#startAbortError = undefined;
       return this.#handle;
     } catch (error) {
-      const startFailureHandle = (error as { workerHandle?: WorkerHandle }).workerHandle;
-      if (!this.#handle && startFailureHandle?.pid) this.#handle = startFailureHandle;
+      const startupError = error instanceof Error ? error : new Error(String(error));
+      const startFailure = startupError as Error & { 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;
+      const startupCancelled = Boolean(this.#startStopReason || startAbortController.signal.aborted);
+      let startupCleanupError: unknown = this.#startAbortError;
+      const abortCompletion = this.#startAbortCompletion;
+      if (abortCompletion) {
+        try { await abortCompletion; }
+        catch (error) { startupCleanupError ??= error; }
+      }
       if (handle) {
         try {
-          await this.#adapter.stop(handle, "startup failed");
-        } catch {
-          try { await this.#adapter.killProcessGroup(handle, "startup cleanup"); } catch { /* preserve startup error */ }
+          await this.#adapter.stop(handle, startupCancelled ? (this.#startStopReason ?? "startup aborted") : "startup failed");
+        } catch (error) {
+          startupCleanupError = error;
+          try { await this.#adapter.killProcessGroup(handle, "startup cleanup"); }
+          catch (cleanupError) { startupCleanupError ??= cleanupError; }
         }
       }
-      if (["starting", "running"].includes(this.#machine.state)) this.#machine.transition("failed");
+      if (startupCleanupError && !startFailure.workerCleanupRequired) {
+        Object.defineProperty(startupError, "workerCleanupRequired", { value: true, enumerable: false });
+      }
+      if (["starting", "running"].includes(this.#machine.state)) this.#machine.transition(startupCancelled && !startupCleanupError ? "stopped" : "failed");
       try {
-        await this.#appendEvent({ type: "worker_start_failed", taskId, data: { error: safeMessage(error) } });
+        await this.#appendEvent({ type: "worker_start_failed", taskId, data: { error: safeMessage(startupError) } });
       } catch { /* logging failure must not hide the startup failure */ }
       await this.#decision?.close().catch(() => {});
       this.#decision = undefined;
       await Promise.resolve(this.#onDecisionSessionClosed?.(taskId)).catch(() => {});
-      throw error;
+      this.#startAbortController = undefined;
+      this.#startToken = undefined;
+      this.#startStopReason = undefined;
+      this.#startAbortError = undefined;
+      throw startupError;
     }
   }
 
+  #assertStartNotAborted(signal: AbortSignal): void {
+    if (signal.aborted) throw new Error(`worker startup aborted: ${this.#startStopReason ?? "startup cancellation requested"}`);
+  }
+
   async poll(): Promise<{ status: WorkerStatus; output: WorkerOutputChunk[] }> {
     return this.#exclusive(() => this.#pollInternal());
   }
@@ -289,7 +343,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 +404,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 +452,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 +499,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");
@@ -478,14 +539,66 @@ export class Supervisor {
   }
 
   async abortStart(reason = "startup aborted"): Promise<void> {
+    if (this.#machine.state !== "starting" && !this.#startAbortController) return;
     // This path intentionally bypasses #exclusive(): start() may be blocked in
     // a Decision Worker model call and shutdown must still dispose that session.
+    this.#startStopReason = reason;
+    const completion = (async () => {
+      this.#startAbortController?.abort(reason);
+      let cleanupError: unknown;
+      const abort = this.#adapter.abortStart?.(reason, this.#startToken);
+      if (abort) {
+        try { await abort; }
+        catch (error) { cleanupError = error; }
+      }
+      await this.#decision?.close().catch(() => {});
+      this.#decision = undefined;
+      if (this.#handle) {
+        try { await this.#adapter.stop(this.#handle, reason); }
+        catch (error) { cleanupError ??= error; }
+      }
+      if (cleanupError) throw cleanupError;
+    })();
+    this.#startAbortCompletion = completion;
+    try {
+      await completion;
+    } catch (error) {
+      this.#startAbortError = error;
+      throw error;
+    } finally {
+      if (this.#startAbortCompletion === completion) this.#startAbortCompletion = undefined;
+    }
+  }
+
+  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.#machine.state === "starting" || this.#startAbortController
+        ? this.abortStart(reason)
+        : Promise.resolve();
     await this.#decision?.close().catch(() => {});
     this.#decision = undefined;
-    if (this.#handle) await this.#adapter.stop(this.#handle, reason).catch(() => {});
+    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> {
+    // A stop must be able to preempt startup rather than waiting behind a
+    // startup operation that is blocked in a provider or adapter call.
+    if (this.#machine.state === "starting") {
+      this.#startStopReason = reason;
+      this.#startAbortController?.abort(reason);
+      if (!this.#handle) {
+        await withTimeout(this.abortStart(reason), 15_000, "worker startup cancellation");
+        return;
+      }
+    }
     // Start the adapter stop immediately so a queued/hung send cannot delay
     // process termination. State/event changes still remain serialized below.
     if (!this.#preemptiveStop && this.#handle && ["starting", "running", "waiting", "paused"].includes(this.#machine.state)) {
@@ -498,30 +611,63 @@ export class Supervisor {
   async #stopInternal(reason: string, flushPendingEvents = true): Promise<void> {
     if (flushPendingEvents) await this.#flushPendingEvents();
     if (!this.#handle) throw new Error("no active task");
-    if (this.#machine.state === "stopped") return;
+    if (this.#machine.state === "stopped") {
+      const preemptiveStop = this.#preemptiveStop;
+      this.#preemptiveStop = undefined;
+      if (preemptiveStop) await preemptiveStop;
+      return;
+    }
     if (this.#machine.state === "failed") {
       // A failed startup or cleanup attempt may still retain a live handle.
       // Retry group termination during shutdown instead of treating the state
       // as fully reclaimed.
-      if (this.#handle) await this.#adapter.stop(this.#handle, reason);
+      const preemptiveStop = this.#preemptiveStop;
+      this.#preemptiveStop = undefined;
+      if (preemptiveStop) await preemptiveStop;
+      else if (this.#handle) await this.#adapter.stop(this.#handle, reason);
       await this.#decision?.close().catch(() => {});
       this.#decision = undefined;
       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 +675,71 @@ 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 (cleanup.cgroupError && cleanup.cgroupRequired !== false) throw new Error(`worker cgroup cleanup failed after verification: ${cleanup.cgroupError}`);
+        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 +818,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 +840,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,25 @@ 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;
+  /** Persisted identity required when handing off an existing tmux lease. */
+  tmuxExpectedIdentity?: {
+    pid?: number;
+    startTime?: string;
+    tmuxTarget?: string;
+    tmuxPaneId?: string;
+    paneStartTime?: string;
+    paneCommand?: string;
+  };
+  /** Adopted sessions must not replay the task as a new user message. */
+  sendInitialInput?: boolean;
+  /** Cancel startup before a worker is fully returned to the supervisor. */
+  abortSignal?: AbortSignal;
+  /** Internal token that scopes out-of-band startup cancellation. */
+  startupToken?: string;
 }
 
 export interface WorkerHandle {
@@ -44,6 +63,15 @@ export interface WorkerHandle {
   startedAt: string;
   cwd: string;
   sessionId?: string;
+  sessionName?: string;
+  tmuxSocket?: string;
+  ownership?: "owned" | "adopted";
+  /** Verified process-boundary metadata persisted in the cwd lease registry. */
+  cgroupPath?: string;
+  tmuxTarget?: string;
+  tmuxPaneId?: string;
+  paneStartTime?: string;
+  paneCommand?: string;
 }
 
 export interface WorkerStatus {
@@ -59,6 +87,8 @@ export interface WorkerStatus {
   processGroupCleaned?: boolean;
   /** Whether a Linux cgroup provided descendant cleanup for this worker. */
   cgroupCleaned?: boolean;
+  /** Whether cgroup attachment was required for this worker. */
+  cgroupRequired?: boolean;
   /** cgroup attachment was unavailable and a fallback may have been used. */
   cgroupError?: string;
   /** Cleanup failure is diagnostic and must be treated as a safety failure. */
@@ -75,6 +105,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, startupToken?: string): Promise<void>;
   getStatus(handle: WorkerHandle): Promise<WorkerStatus>;
   readOutput(handle: WorkerHandle): Promise<WorkerOutputChunk[]>;
   /** Restore chunks when diagnostic event persistence fails before acknowledgement. */
@@ -87,6 +119,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 +132,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 {