pi-claude-supervisor 0.3.0 → 0.4.1

package/src/supervisor.ts

@@ -53,6 +53,8 @@ export interface SupervisorStartOptions {
   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. */
@@ -101,6 +103,12 @@ 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>;
+  #released = false;
 
   constructor(adapter: WorkerAdapter, events = new EventLog(), hooks: { onHumanRequired?: (notice: HumanInterventionNotice) => Promise<void> | void } = {}) {
     this.#adapter = adapter;
@@ -113,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));
@@ -132,12 +142,18 @@ 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;
     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",
@@ -151,6 +167,7 @@ export class Supervisor {
       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 },
@@ -173,6 +190,7 @@ export class Supervisor {
         });
         await this.#decision.start();
       }
+      this.#assertStartNotAborted(startAbortController.signal);
       const input: WorkerStartInput = {
         task: options.initialInput ?? options.task,
         cwd: options.cwd,
@@ -182,37 +200,66 @@ export class Supervisor {
         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 startFailure = error as { workerHandle?: WorkerHandle; workerCleanupRequired?: boolean };
+      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());
   }
@@ -496,21 +543,35 @@ 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.
-    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) {
-      try { await this.#adapter.stop(this.#handle, reason); }
-      catch (error) { cleanupError ??= error; }
+    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;
     }
-    if (cleanupError) throw cleanupError;
   }
 
   async release(reason = "Pi session disconnected"): Promise<void> {
@@ -519,17 +580,30 @@ export class Supervisor {
       ? this.#adapter.release
         ? this.#adapter.release(handle, reason)
         : this.#adapter.stop(handle, reason)
-      : this.#adapter.abortStart?.(reason) ?? Promise.resolve();
+      : this.#machine.state === "starting" || this.#startAbortController
+        ? this.abortStart(reason)
+        : Promise.resolve();
     await this.#decision?.close().catch(() => {});
     this.#decision = undefined;
     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");
   }
 
   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)) {
@@ -542,12 +616,20 @@ 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(() => {});
@@ -615,6 +697,7 @@ export class Supervisor {
         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");
         }

package/src/types.ts

@@ -40,8 +40,21 @@ export interface WorkerStartInput {
   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 {
@@ -53,6 +66,12 @@ export interface WorkerHandle {
   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 {
@@ -68,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. */
@@ -85,7 +106,7 @@ 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>;
+  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. */

package/src/worker/process-adapter.ts

@@ -29,6 +29,8 @@ export interface ProcessWorkerAdapterOptions {
   inputWriteTimeoutMs?: number;
   /** Linux descendant cleanup mode; auto uses cgroup v2 when available. */
   cgroupMode?: "off" | "auto" | "required";
+  /** Override the detected cgroup parent for controlled integration tests. */
+  cgroupParentPath?: string;
 }
 
 interface ProcessRecord {
@@ -61,6 +63,10 @@ interface ProcessRecord {
   listeners: Set<WorkerEventListener>;
   permissionResponses: Set<string>;
   stopping?: boolean;
+  starting: boolean;
+  abortRequested: boolean;
+  startupToken?: string;
+  abortListener?: () => void;
 }
 
 /**
@@ -79,6 +85,7 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
   readonly #maxOutputBytes: number;
   readonly #inputWriteTimeoutMs: number;
   readonly #cgroupMode: "off" | "auto" | "required";
+  readonly #cgroupParentPath?: string;
 
   constructor(options: ProcessWorkerAdapterOptions = {}) {
     this.#mode = options.mode ?? "process-pipe";
@@ -88,6 +95,7 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
     this.#maxOutputBytes = boundedPositiveInteger(options.maxOutputBytes ?? 8 * 1024 * 1024, "maxOutputBytes");
     this.#inputWriteTimeoutMs = boundedDelay(options.inputWriteTimeoutMs ?? 10_000);
     this.#cgroupMode = options.cgroupMode ?? "auto";
+    this.#cgroupParentPath = options.cgroupParentPath;
   }
 
   capabilities(): WorkerCapabilities {
@@ -101,6 +109,7 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
   }
 
   async start(input: WorkerStartInput): Promise<WorkerHandle> {
+    if (input.abortSignal?.aborted) throw new Error("worker startup aborted before spawn");
     const args = this.#mode === "claude-jsonl" ? claudeJsonlArgs(input.args) : (input.args ?? []);
     assertSafeWorkerCommand(input.command, args, input.approval);
     const handle: WorkerHandle = {
@@ -141,8 +150,21 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
       inputTail: Promise.resolve(),
       listeners: new Set(input.eventListener ? [input.eventListener] : []),
       permissionResponses: new Set(),
+      starting: true,
+      abortRequested: false,
+      startupToken: input.startupToken,
     };
+    const abortListener = () => {
+      record.abortRequested = true;
+      record.stopping = true;
+      if (record.exitCode === undefined) {
+        try { record.child.kill("SIGTERM"); } catch { /* cleanup below remains authoritative */ }
+      }
+    };
+    record.abortListener = abortListener;
+    input.abortSignal?.addEventListener("abort", abortListener, { once: true });
     this.#records.set(handle.id, record);
+    if (input.abortSignal?.aborted) abortListener();
     const capture = (stream: "stdout" | "stderr") => (chunk: Buffer | string) => {
       const text = String(chunk);
       record.lastOutputAt = new Date().toISOString();
@@ -187,37 +209,69 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
       });
     });
     try {
-      await record.spawned;
-      await this.#attachCgroup(record);
-    } 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));
-      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) {
-      record.lastInputAt = new Date().toISOString();
       try {
-        await this.#writeInput(record, this.#encodeMessage(input.task));
+        await record.spawned;
+        this.#assertNotAborted(record);
+        await this.#attachCgroup(record);
+        this.#assertNotAborted(record);
       } catch (error) {
-        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)}`;
+        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));
+        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;
         }
-        throw error;
+        throw startupError;
+      }
+      if (input.task) {
+        this.#assertNotAborted(record);
+        record.lastInputAt = new Date().toISOString();
+        try {
+          await this.#writeInput(record, this.#encodeMessage(input.task));
+        } catch (error) {
+          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;
+        }
+      }
+      return handle;
+    } finally {
+      record.starting = false;
+      if (record.abortListener) input.abortSignal?.removeEventListener("abort", record.abortListener);
+      record.abortListener = undefined;
+    }
+  }
+
+  async abortStart(reason = "startup aborted", startupToken?: string): Promise<void> {
+    const records = [...this.#records.values()].filter((record) => record.starting && (startupToken === undefined || record.startupToken === startupToken));
+    for (const record of records) {
+      record.abortRequested = true;
+      record.stopping = true;
+      if (record.exitCode === undefined) {
+        try { record.child.kill("SIGTERM"); } catch { /* cleanup below remains authoritative */ }
+      }
+    }
+    const deadline = Date.now() + Math.max(this.#terminationGraceMs, 1_000);
+    while (records.some((record) => record.starting) && Date.now() < deadline) await delay(10);
+    for (const record of records) {
+      if (record.exitCode === undefined) {
+        try { await this.#ensureGroupCleanup(record); }
+        catch (error) { record.cleanupError = error instanceof Error ? error : new Error(`${reason}: ${String(error)}`); }
       }
     }
-    return handle;
   }
 
   async getStatus(handle: WorkerHandle): Promise<WorkerStatus> {
@@ -241,6 +295,7 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
       exitReason: running ? undefined : record.signal ? "crashed" : record.exitCode === 0 ? "completed" : "failed",
       processGroupCleaned: record.groupCleanupComplete,
       cgroupCleaned: record.cgroupPath ? record.groupCleanupComplete : undefined,
+      cgroupRequired: this.#cgroupMode === "required",
       cgroupError: record.cgroupError?.message,
       cleanupError: record.cleanupError?.message,
       runtimeError: record.runtimeError?.message,
@@ -356,6 +411,10 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
     throw new Error("process-pipe transport does not support session resume");
   }
 
+  #assertNotAborted(record: ProcessRecord): void {
+    if (record.abortRequested) throw new Error("worker startup aborted");
+  }
+
   async #writeInput(record: ProcessRecord, message: string): Promise<void> {
     const stdin = record.child.stdin;
     if (record.stdinError) throw new Error(`worker stdin is unavailable: ${record.stdinError.message}`);
@@ -464,14 +523,27 @@ export class ProcessWorkerAdapter implements WorkerAdapter {
   }
 
   async #attachCgroup(record: ProcessRecord): Promise<void> {
-    if (this.#cgroupMode === "off" || process.platform !== "linux" || !record.handle.pid) return;
+    if (this.#cgroupMode === "off") return;
+    if (!record.handle.pid) {
+      const error = new Error("worker pid was unavailable for cgroup attachment");
+      record.cgroupError = error;
+      if (this.#cgroupMode === "required") throw new Error(`unable to attach worker to a cgroup: ${error.message}`, { cause: error });
+      throw error;
+    }
+    if (process.platform !== "linux") {
+      const error = new Error("cgroups are unavailable on this platform");
+      record.cgroupError = error;
+      if (this.#cgroupMode === "required") throw new Error(`unable to attach worker to a cgroup: ${error.message}`, { cause: error });
+      return;
+    }
     let path: string | undefined;
     try {
-      const parent = await currentCgroupPath();
+      const parent = this.#cgroupParentPath ?? await currentCgroupPath();
       path = `${parent}/pi-claude-supervisor-${record.handle.id}`;
       await mkdir(path);
       await writeFile(`${path}/cgroup.procs`, `${record.handle.pid}\n`);
       record.cgroupPath = path;
+      record.handle.cgroupPath = path;
     } catch (error) {
       if (path) await rm(path, { recursive: true, force: true }).catch(() => {});
       record.cgroupError = error instanceof Error ? error : new Error(String(error));