chainlesschain 0.166.76 → 0.166.78

package/src/lib/claude-code-bridge.js

@@ -17,6 +17,11 @@ import { EventEmitter } from "events";
 import crypto from "crypto";
 import runtimeClaimsContract from "@chainlesschain/session-core/runtime-claims";
 import executionBroker from "./process-execution-broker/index.js";
+import { PROCESS_OWNERSHIP_UNCONFIRMED } from "./process-execution-broker/process-ownership-quarantine.js";
+import {
+  PROCESS_OWNERSHIP_PENDING,
+  PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE,
+} from "./process-execution-broker/process-ownership-journal.js";
 import {
   createExternalAgentAdapter,
   EXTERNAL_AGENT_ERROR,
@@ -68,6 +73,7 @@ export const AGENT_STATUS = {
   FAILED: "failed",
   TIMEOUT: "timeout",
   CANCELLED: "cancelled",
+  QUARANTINED: "quarantined",
 };
 
 // Bound how much of a child's stdout/stderr we retain in memory. A verbose or
@@ -157,8 +163,20 @@ export class ClaudeCodeAgent extends EventEmitter {
    * @param {string} options.context     - Extra context prepended to task
    * @param {string} options.allowedTools - Comma-separated tool allow-list
    * @returns {Promise<{success, output, exitCode, duration, taskId}>}
+   * A quarantined failure report does not release process ownership. It emits
+   * task:quarantined instead of task:complete and the agent cannot be reused.
    */
   async executeTask(taskDescription, options = {}) {
+    if (this.status === AGENT_STATUS.QUARANTINED) {
+      const error = new Error(
+        "External agent still owns an unconfirmed process tree",
+      );
+      error.code = EXTERNAL_AGENT_ERROR.CLEANUP_UNCONFIRMED;
+      throw error;
+    }
+    if (this.status === AGENT_STATUS.RUNNING) {
+      throw new Error("External agent already has a running task");
+    }
     const {
       cwd = process.cwd(),
       timeout = 300_000,
@@ -174,7 +192,29 @@ export class ClaudeCodeAgent extends EventEmitter {
 
     this.status = AGENT_STATUS.RUNNING;
     this.currentTask = taskDescription;
+    this._cancelRequested = false;
     this.emit("task:start", { agentId: this.id, task: taskDescription });
+    if (this._cancelRequested) {
+      this.status = AGENT_STATUS.CANCELLED;
+      this.currentTask = null;
+      const result = {
+        success: false,
+        status: AGENT_STATUS.CANCELLED,
+        output: "",
+        exitCode: -1,
+        duration: 0,
+        timedOut: false,
+        cancelled: true,
+        agentId: this.id,
+        error: "External agent was cancelled before spawn",
+        errorCode: EXTERNAL_AGENT_ERROR.CANCELLED,
+        protocol: this.adapter.capabilities().protocol,
+        runtimeClaims: VALIDATION_ONLY_CLAIMS,
+        terminalEvidence: [],
+      };
+      this.emit("task:complete", result);
+      return result;
+    }
 
     let args;
     try {
@@ -201,8 +241,6 @@ export class ClaudeCodeAgent extends EventEmitter {
       return result;
     }
 
-    this._cancelRequested = false;
-
     return new Promise((resolve) => {
       const startTime = Date.now();
       const outputChunks = [];
@@ -213,6 +251,114 @@ export class ClaudeCodeAgent extends EventEmitter {
       const outDecoder = new TextDecoder("utf-8");
       const errDecoder = new TextDecoder("utf-8");
       let timedOut = false;
+      let finalized = false;
+      let stopping = false;
+      let proc = null;
+      let timer = null;
+      let killTimer = null;
+      let processError = null;
+      let spawnFailure = null;
+      let brokerCloseFence = null;
+      const finalize = (result) => {
+        if (finalized) return;
+        finalized = true;
+        clearTimeout(timer);
+        clearTimeout(killTimer);
+        this._proc = null;
+        this._stop = null;
+        this.currentTask = null;
+        this.emit("task:complete", result);
+        resolve(result);
+      };
+      const failSpawn = (err) => {
+        if (finalized) return;
+        const admissionBlocked = [
+          PROCESS_OWNERSHIP_UNCONFIRMED,
+          PROCESS_OWNERSHIP_PENDING,
+          PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE,
+        ].includes(err.code);
+        this.status = AGENT_STATUS.FAILED;
+        finalize({
+          success: false,
+          status: admissionBlocked ? "not-started" : "failed",
+          output: "",
+          exitCode: -1,
+          duration: Date.now() - startTime,
+          timedOut,
+          cancelled: this._cancelRequested && !timedOut,
+          agentId: this.id,
+          error: err.message,
+          errorCode: admissionBlocked
+            ? err.code
+            : EXTERNAL_AGENT_ERROR.SPAWN_FAILED,
+          protocol: this.adapter.capabilities().protocol,
+          runtimeClaims: admissionBlocked
+            ? VALIDATION_ONLY_CLAIMS
+            : REAL_EXECUTION_CLAIMS,
+          terminalEvidence: [],
+          ...(admissionBlocked
+            ? { executionStarted: false, recoveryRequired: true }
+            : {}),
+        });
+      };
+      const quarantine = (receipt) => {
+        if (finalized || receipt?.cleanup?.confirmed !== false) return;
+        // Return a failure report without declaring task completion or releasing
+        // the process handle, task identity or pool slot. No synthetic close.
+        finalized = true;
+        clearTimeout(timer);
+        clearTimeout(killTimer);
+        this._stop = null;
+        this.status = AGENT_STATUS.QUARANTINED;
+        const rawOutput = outputChunks.join("");
+        const result = {
+          success: false,
+          status: AGENT_STATUS.QUARANTINED,
+          output: rawOutput.slice(-4000),
+          rawOutput,
+          outputTruncated,
+          stderr: errorChunks.join("").slice(-2000),
+          exitCode: null,
+          duration: Date.now() - startTime,
+          timedOut,
+          cancelled: this._cancelRequested && !timedOut,
+          agentId: this.id,
+          error:
+            "External agent process-tree cleanup is unconfirmed; recovery is required",
+          errorCode: EXTERNAL_AGENT_ERROR.CLEANUP_UNCONFIRMED,
+          protocol: this.adapter.capabilities().protocol,
+          runtimeClaims: REAL_EXECUTION_CLAIMS,
+          terminalEvidence: [],
+          processOwnershipReleased: false,
+          recoveryRequired: true,
+          cleanup: { ...receipt.cleanup },
+        };
+        resolve(result);
+        this.emit("task:quarantined", result);
+      };
+      const stop = () => {
+        if (finalized || stopping) return;
+        stopping = true;
+        clearTimeout(timer);
+        // Schedule before TERM: a child can close synchronously in adapters.
+        // Use the broker's child handle (including its sandbox supervisor),
+        // never a delayed numeric PID which may have been reused.
+        killTimer = setTimeout(() => {
+          if (!finalized) {
+            try {
+              proc.kill("SIGKILL");
+            } catch (err) {
+              processError = err;
+            }
+          }
+        }, killGraceMs);
+        killTimer.unref?.();
+        try {
+          proc.kill("SIGTERM");
+        } catch (err) {
+          processError = err;
+        }
+      };
       // Tail-bounded byte counters for the two buffers (see MAX_AGENT_OUTPUT_BYTES).
       let outBytes = 0;
       let errBytes = 0;
@@ -227,33 +373,49 @@ export class ClaudeCodeAgent extends EventEmitter {
         return bytes;
       };
 
-      const proc = _deps.spawn(this.adapter.command, args, {
-        cwd,
-        env: { ...process.env },
-        windowsHide: true,
-        origin: "claude-code-bridge:agent",
-        policy: "allow",
-        scope: "orchestrator",
-        shell: false,
-      });
+      try {
+        proc = _deps.spawn(this.adapter.command, args, {
+          cwd,
+          env: { ...process.env },
+          windowsHide: true,
+          origin: "claude-code-bridge:agent",
+          policy: "allow",
+          scope: "orchestrator",
+          shell: false,
+          ...(process.platform === "linux"
+            ? { linuxSubreaper: { graceMs: killGraceMs } }
+            : {}),
+        });
+      } catch (err) {
+        // Broker admission/bookkeeping can fail after native spawn. Its
+        // attached child remains ours until close; a kill request is not exit
+        // evidence and must not release this agent for another task.
+        if (!err?.spawnedProcess) {
+          failSpawn(err);
+          return;
+        }
+        proc = err.spawnedProcess;
+        processError = err;
+        spawnFailure = err;
+        brokerCloseFence = err.workspaceProcessClosed;
+      }
       this._proc = proc;
+      this._stop = stop;
 
       // SIGKILL-escalation timer is hoisted so the close/error handlers can
       // clear it — otherwise, when the process dies promptly from SIGTERM, this
       // inner timer still fires a redundant SIGKILL on a dead pid AND holds the
       // event loop open for the full grace period. unref() is a second guard so
       // it never keeps the process alive on its own.
-      let killTimer = null;
-      const timer = setTimeout(() => {
-        timedOut = true;
-        proc.kill("SIGTERM");
-        killTimer = setTimeout(() => proc.kill("SIGKILL"), killGraceMs);
-        if (killTimer && typeof killTimer.unref === "function") {
-          killTimer.unref();
-        }
-      }, timeout);
+      if (!spawnFailure) {
+        timer = setTimeout(() => {
+          timedOut = true;
+          stop();
+        }, timeout);
+      }
 
       proc.stdout.on("data", (data) => {
+        if (finalized) return;
         const chunk =
           typeof data === "string"
             ? data
@@ -270,6 +432,7 @@ export class ClaudeCodeAgent extends EventEmitter {
       });
 
       proc.stderr.on("data", (data) => {
+        if (finalized) return;
         const chunk =
           typeof data === "string"
             ? data
@@ -281,19 +444,24 @@ export class ClaudeCodeAgent extends EventEmitter {
         }
       });
 
-      proc.on("close", (code) => {
-        clearTimeout(timer);
-        if (killTimer) clearTimeout(killTimer);
-        this._proc = null;
+      const completeClosed = (code) => {
+        if (finalized) return;
         const duration = Date.now() - startTime;
         const rawOutput = outputChunks.join("");
         const cancelled = this._cancelRequested && !timedOut;
-        const projection = this.adapter.parseTranscript(rawOutput);
+        let projection;
+        try {
+          projection = this.adapter.parseTranscript(rawOutput);
+        } catch (err) {
+          projection = { terminal: "failed", error: err.message };
+        }
         const missingTerminal =
           this.adapter.capabilities().requiresTerminalEvent &&
           projection.terminal === null;
         const protocolFailed =
-          projection.terminal === "failed" || missingTerminal;
+          projection.terminal === "failed" ||
+          missingTerminal ||
+          Boolean(processError);
         const status = timedOut
           ? AGENT_STATUS.TIMEOUT
           : cancelled
@@ -336,11 +504,15 @@ export class ClaudeCodeAgent extends EventEmitter {
           ? EXTERNAL_AGENT_ERROR.TIMEOUT
           : cancelled
             ? EXTERNAL_AGENT_ERROR.CANCELLED
-            : code !== 0
-              ? EXTERNAL_AGENT_ERROR.EXIT_NONZERO
-              : protocolFailed
-                ? EXTERNAL_AGENT_ERROR.PROTOCOL_FAILED
-                : null;
+            : spawnFailure
+              ? EXTERNAL_AGENT_ERROR.SPAWN_FAILED
+              : processError?.code === PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE
+                ? PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE
+                : code !== 0
+                  ? EXTERNAL_AGENT_ERROR.EXIT_NONZERO
+                  : protocolFailed
+                    ? EXTERNAL_AGENT_ERROR.PROTOCOL_FAILED
+                    : null;
 
         const result = {
           success,
@@ -356,7 +528,8 @@ export class ClaudeCodeAgent extends EventEmitter {
           stderr: errorChunks.join("").slice(-2000),
           error: success
             ? undefined
-            : projection.error ||
+            : processError?.message ||
+              projection.error ||
               (missingTerminal
                 ? "External agent JSONL stream ended without a terminal event"
                 : null) ||
@@ -374,44 +547,72 @@ export class ClaudeCodeAgent extends EventEmitter {
           malformedLineCount: projection.malformedLineCount,
           runtimeClaims: REAL_EXECUTION_CLAIMS,
           terminalEvidence,
+          ...(processError?.code === PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE
+            ? { recoveryRequired: true }
+            : {}),
         };
 
-        this.emit("task:complete", result);
-        resolve(result);
-      });
+        finalize(result);
+      };
+      proc.on("close", completeClosed);
 
       proc.on("error", (err) => {
-        clearTimeout(timer);
-        if (killTimer) clearTimeout(killTimer);
-        this._proc = null;
-        this.status = AGENT_STATUS.FAILED;
-        this.currentTask = null;
-        const result = {
-          success: false,
-          status: "failed",
-          output: "",
-          exitCode: -1,
-          duration: Date.now() - startTime,
-          timedOut: false,
-          cancelled: false,
-          agentId: this.id,
-          error: err.message,
-          errorCode: EXTERNAL_AGENT_ERROR.SPAWN_FAILED,
-          protocol: this.adapter.capabilities().protocol,
-          runtimeClaims: REAL_EXECUTION_CLAIMS,
-          terminalEvidence: [],
-        };
-        this.emit("task:complete", result);
-        resolve(result);
+        if (finalized) return;
+        if (err.code === PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE) {
+          // The actual child has run. A failed durable settlement must not be
+          // mislabeled as an admission denial or evidence that nothing started.
+          processError = err;
+          return;
+        }
+        if (err.code === EXTERNAL_AGENT_ERROR.CLEANUP_UNCONFIRMED) {
+          quarantine(proc.ownedProcessTreeEvidence);
+          if (finalized) return;
+        }
+        if (
+          err.code === EXTERNAL_AGENT_ERROR.SPAWN_FAILED &&
+          proc.ownedProcessTreeClosed
+        ) {
+          processError = err;
+          spawnFailure = err;
+        }
+        if (spawnFailure) {
+          // Keep the original admission failure and wait for the owned child;
+          // another signal/transport error is still not proof of its exit.
+          stop();
+          return;
+        }
+        // A post-spawn error (e.g. signal failure) is not proof of exit.
+        // Retain ownership and wait for close, escalating cancellation.
+        if (proc.pid && proc.exitCode == null && proc.signalCode == null) {
+          processError = err;
+          stop();
+        } else {
+          failSpawn(err);
+        }
       });
+      proc.on("cleanup:unconfirmed", quarantine);
+      if (spawnFailure) {
+        if (brokerCloseFence?.then) {
+          Promise.resolve(brokerCloseFence).then(
+            (receipt) => {
+              if (receipt?.observed === true) completeClosed(receipt.exitCode);
+            },
+            () => {
+              // A failed close observer proves nothing. Keep the actual
+              // ChildProcess close listener and termination deadline active.
+            },
+          );
+        }
+        stop();
+      }
     });
   }
 
   /** Abort the currently running task. */
   abort() {
-    if (this._proc) {
+    if (this.status === AGENT_STATUS.RUNNING) {
       this._cancelRequested = true;
-      this._proc.kill("SIGTERM");
+      this._stop?.();
     }
   }
 
@@ -422,6 +623,9 @@ export class ClaudeCodeAgent extends EventEmitter {
       cliCommand: this.cliCommand,
       protocol: this.adapter.capabilities().protocol,
       currentTask: this.currentTask,
+      ...(this.status === AGENT_STATUS.QUARANTINED
+        ? { processOwnershipReleased: false, recoveryRequired: true }
+        : {}),
     };
   }
 }
@@ -475,6 +679,10 @@ export class ClaudeCodePool extends EventEmitter {
 
     // Process in batches of maxParallel
     for (let i = 0; i < tasks.length; i += this.maxParallel) {
+      if (this._hasQuarantinedAgent()) {
+        results.push(...tasks.slice(i).map((task) => this._blockedTask(task)));
+        break;
+      }
       const batch = tasks.slice(i, i + this.maxParallel);
       this.emit("batch:start", {
         batchIndex: i / this.maxParallel,
@@ -496,8 +704,9 @@ export class ClaudeCodePool extends EventEmitter {
   }
 
   async _runTask(task, { cwd }) {
+    if (this._hasQuarantinedAgent()) return this._blockedTask(task);
     const agent = new ClaudeCodeAgent({
-      id: `agent-${task.id}`,
+      id: `agent-${task.id}-${crypto.randomUUID()}`,
       cliCommand: this.cliCommand,
       model: this.model,
       sandbox: this.sandbox,
@@ -505,6 +714,12 @@ export class ClaudeCodePool extends EventEmitter {
 
     this._agents.set(agent.id, agent);
     agent.on("output", (ev) => this.emit("agent:output", ev));
+    agent.on("task:quarantined", (result) => {
+      // Stop already admitted siblings through their retained handles. Their
+      // own close fences still decide release; no new batch may start.
+      this.abortAll();
+      this.emit("agent:quarantined", { taskId: task.id, ...result });
+    });
 
     const result = await agent.executeTask(task.description, {
       cwd,
@@ -513,6 +728,9 @@ export class ClaudeCodePool extends EventEmitter {
       allowedTools: task.allowedTools || null,
     });
 
+    if (agent.status === AGENT_STATUS.QUARANTINED) {
+      return { taskId: task.id, ...result };
+    }
     this._agents.delete(agent.id);
     this._completed.push({ ...result, taskId: task.id });
     if (this._completed.length > this.maxCompleted) {
@@ -523,6 +741,30 @@ export class ClaudeCodePool extends EventEmitter {
     return { taskId: task.id, ...result };
   }
 
+  _hasQuarantinedAgent() {
+    return [...this._agents.values()].some(
+      (agent) => agent.status === AGENT_STATUS.QUARANTINED,
+    );
+  }
+
+  _blockedTask(task) {
+    return {
+      taskId: task.id,
+      agentId: null,
+      success: false,
+      status: "not-started",
+      output: "",
+      exitCode: null,
+      duration: 0,
+      executionStarted: false,
+      recoveryRequired: true,
+      error: "External agent pool retains an unconfirmed process tree",
+      errorCode: EXTERNAL_AGENT_ERROR.EXECUTION_BLOCKED,
+      runtimeClaims: VALIDATION_ONLY_CLAIMS,
+      terminalEvidence: [],
+    };
+  }
+
   /** Current pool status snapshot. */
   status() {
     const active = [...this._agents.values()].map((a) => a.toJSON());