machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/process-execution.mjs

@@ -2,29 +2,24 @@ import { spawn } from "node:child_process";
 import { basename } from "node:path";
 import { stat } from "node:fs/promises";
 import { BoundedOutput } from "./bounded-output.mjs";
+import { attachChildProcessSettlement } from "./child-process-settlement.mjs";
 import { executionEnv, workspaceShellCommand } from "./shell.mjs";
 import { MAX_COMMAND_BYTES, validateArgv } from "./process-contract.mjs";
 import { terminateProcessTreeWithEscalation } from "./process-tree.mjs";
 import { BridgeError } from "./errors.mjs";
-import { clampInteger } from "./numbers.mjs";
+import { delegatedProcessCommand } from "./delegated-process-sandbox.mjs";
 import { ProcessOutputStream } from "./process-output-stream.mjs";
+import { processForegroundTimeoutSeconds, registeredCommandTimeoutSeconds } from "./process-foreground-timeout.mjs";
 import { processFailureMessage, publicProcessToolResult } from "./process-result-projection.mjs";
-import {
-  DEFAULT_PROCESS_OUTPUT_BYTES,
-  MAX_PROCESS_SESSION_OUTPUT_BYTES,
-  MAX_PROCESS_STDIN_BYTES,
-  MAX_PROCESS_TIMEOUT_SECONDS,
-  MIN_PROCESS_TIMEOUT_SECONDS,
-  PROCESS_SESSION_RETENTION_MS,
-  PUBLIC_PROCESS_INLINE_OUTPUT_BYTES,
-} from "./execution-limits.mjs";
-
-const PROCESS_OUTPUT_CAPTURE = Symbol("process-output-capture");
-const CONTINUATION_READ_BYTES = 64 * 1024;
-
+import { processCancellationFailure, processChildErrorFailure, processPostSpawnFailure, processPreSpawnFailure, processTimeoutFailure } from "./process-nonreplayable-settlement.mjs";
+import { acquireProcessResources, bindProcessResources, releaseProcessResources, releaseProcessResourcesQuietly } from "./resource-process-admission.mjs";
+import { foregroundResourceWaitMs } from "./resource-foreground-wait.mjs";
+import { validateFixedProcessEnvironment } from "./fixed-process-environment.mjs";
+import { EXECUTION_SURFACE, withExecutionSurface } from "./execution-surface.mjs";
+import { DEFAULT_PROCESS_OUTPUT_BYTES, MAX_PROCESS_SESSION_OUTPUT_BYTES, MAX_PROCESS_STDIN_BYTES, PROCESS_SESSION_RETENTION_MS, PUBLIC_PROCESS_INLINE_OUTPUT_BYTES } from "./execution-limits.mjs";
+const PROCESS_OUTPUT_CAPTURE = Symbol("process-output-capture"); const CONTINUATION_READ_BYTES = 64 * 1024;
 function spawnDirectProcess(command, args, options) {
-  // Keep the production child_process API call structurally separate from the
-  // injectable test seam and enforce non-shell execution at the final boundary.
+  // Keep the production child_process API separate from the injectable test seam and enforce non-shell execution.
   return spawn(command, args, {
     cwd: options.cwd,
     env: options.env,
@@ -33,55 +28,53 @@ function spawnDirectProcess(command, args, options) {
     shell: false,
   });
 }
-
 export class ProcessExecutionService {
-  constructor({ workspace, policy, policyGate, runtimeDir, processTracker, resolveExistingPath, resolveLocalCommand, displayPath, throwIfCancelled, retainCompletedOutput = null, spawnProcess = spawnDirectProcess, terminateProcess = terminateProcessTreeWithEscalation }) {
+  constructor({ workspace, policy, policyGate, policyForContext = null, runtimeDir, processTracker, resourceCoordinator = null, resourceWaitMs = undefined, resolveExistingPath, resolveLocalCommand, displayPath, throwIfCancelled, retainCompletedOutput = null, spawnProcess = spawnDirectProcess, terminateProcess = terminateProcessTreeWithEscalation, childSettlementOptions = {} }) {
     this.workspace = workspace;
     this.policy = policy;
     this.policyGate = policyGate;
+    this.policyForContext = typeof policyForContext === "function" ? policyForContext : () => this.policy;
     this.runtimeDir = runtimeDir;
     this.processTracker = processTracker;
+    this.resourceCoordinator = resourceCoordinator;
+    this.resourceWaitMs = resourceWaitMs;
     this.resolveExistingPath = resolveExistingPath;
     this.resolveLocalCommand = resolveLocalCommand;
     this.displayPath = displayPath;
     this.throwIfCancelled = throwIfCancelled;
     this.retainCompletedOutput = typeof retainCompletedOutput === "function" ? retainCompletedOutput : null;
-    this.spawnProcess = spawnProcess;
-    this.terminateProcess = terminateProcess;
+    this.spawnProcess = spawnProcess; this.terminateProcess = terminateProcess; this.childSettlementOptions = childSettlementOptions;
   }
-
   async runDirect(args, context = {}) {
     this.policyGate.assert("run_process");
     const argv = validateArgv(args.argv);
-    const cwd = await this.resolveExistingPath(args.cwd || ".");
+    const cwd = await this.resolveExistingPath(args.cwd || ".", context);
     if (!(await stat(cwd)).isDirectory()) throw new BridgeError("invalid_request", "cwd is not a directory");
+    const timeoutSeconds = processForegroundTimeoutSeconds("run_process", args.timeout_seconds, context);
     const result = await this.runPublic(
-      argv[0], argv.slice(1),
-      clampInteger(args.timeout_seconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000,
+      argv[0], argv.slice(1), timeoutSeconds * 1000,
       context, cwd,
     );
     return publicProcessToolResult(result);
   }
-
   async runRegistered(args, context = {}) {
     this.policyGate.assert("run_local_command");
     const command = await this.resolveLocalCommand(args, context);
     const argv = validateArgv(command.argv);
-    const cwd = await this.resolveExistingPath(command.cwd);
+    const cwd = await this.resolveExistingPath(command.cwd, context);
     if (!(await stat(cwd)).isDirectory()) throw new BridgeError("invalid_request", "registered command cwd is not a directory");
-    const requested = args.timeout_seconds === undefined
-      ? command.timeoutSeconds
-      : clampInteger(args.timeout_seconds, command.timeoutSeconds, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS);
-    const timeoutSeconds = Math.min(requested, command.timeoutSeconds);
+    const timeoutSeconds = registeredCommandTimeoutSeconds(args, command, context);
     const result = await this.runPublic(argv[0], argv.slice(1), timeoutSeconds * 1000, context, cwd);
-    return publicProcessToolResult({ name: command.name, cwd: this.displayPath(cwd), timeout_seconds: timeoutSeconds, ...result });
+    return publicProcessToolResult({ name: command.name, cwd: this.displayPath(cwd, context), timeout_seconds: timeoutSeconds, ...result });
   }
-
-  async probeShell(context = {}) {
+  async probeShell(context = {}, timeoutMs = 5_000) {
     const shell = workspaceShellCommand(process.platform === "win32" ? "cd" : "pwd");
-    return this.run(shell.cmd, shell.args, 5000, true, 64 * 1024, context);
+    return this.run(shell.cmd, shell.args, timeoutMs, true, 64 * 1024, context, this.workspace, null, { internalFixed: true });
+  }
+  async runFixedInternal(cmd, args, timeoutMs, allowFailure = false, maxOutputBytes = DEFAULT_PROCESS_OUTPUT_BYTES, context = {}, cwd = this.workspace, stdin = null, environment = {}) {
+    const argv = validateArgv([cmd, ...args]);
+    return this.run(argv[0], argv.slice(1), timeoutMs, allowFailure, maxOutputBytes, context, cwd, stdin, { internalFixed: true, internalEnvironment: validateFixedProcessEnvironment(environment) });
   }
-
   async runShell(command, timeoutSeconds, context = {}) {
     this.policyGate.assert("exec_command");
     if (!command || typeof command !== "string") throw new BridgeError("invalid_request", "command is required");
@@ -90,16 +83,14 @@ export class ProcessExecutionService {
     const shell = workspaceShellCommand(command);
     const result = await this.runPublic(
       shell.cmd, shell.args,
-      clampInteger(timeoutSeconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000,
+      processForegroundTimeoutSeconds("exec_command", timeoutSeconds, context) * 1000,
       context, this.workspace,
     );
     return publicProcessToolResult(result);
   }
-
   terminateAll(signal = "SIGTERM", escalate = false) {
     this.processTracker.terminateAll(signal, escalate);
   }
-
   async runPublic(cmd, args, timeoutMs, context, cwd) {
     const startedAt = Date.now();
     const result = await this.run(
@@ -114,7 +105,7 @@ export class ProcessExecutionService {
         command: basename(cmd), cwd,
         stdout: capture.stdout, stderr: capture.stderr,
         exitCode: result.code, startedAt, closedAt: Date.now(),
-      });
+      }, context);
       if (session) {
         continuation = {
           output_session_id: session.session_id,
@@ -141,13 +132,22 @@ export class ProcessExecutionService {
     }
     return publicResult;
   }
-
   async run(cmd, args, timeoutMs, allowFailure = false, maxOutputBytes = DEFAULT_PROCESS_OUTPUT_BYTES, context = {}, cwd = this.workspace, stdin = null, options = {}) {
     this.throwIfCancelled(context);
     if (stdin !== null && Buffer.byteLength(String(stdin)) > MAX_PROCESS_STDIN_BYTES) {
       throw new BridgeError("limit_exceeded", "process stdin exceeds 1 MiB");
     }
-
+    const internalFixed = options.internalFixed === true;
+    const baseEnvironment = executionEnv(this.workspace, {
+      fullEnv: internalFixed ? false : this.policyForContext(context).minimalEnv === false, runtimeDir: this.runtimeDir,
+    });
+    if (internalFixed) Object.assign(baseEnvironment, options.internalEnvironment || {});
+    const executionEnvironment = internalFixed ? baseEnvironment : withExecutionSurface(baseEnvironment, EXECUTION_SURFACE.foregroundProcess);
+    const admitted = internalFixed || !this.resourceCoordinator
+      ? { lease: null, environment: executionEnvironment, command: cmd, args }
+      : await acquireProcessResources(this.resourceCoordinator, cmd, args, executionEnvironment, {
+          cwd, priority: options.resourcePriority || "interactive", waitMs: options.resourceWaitMs ?? foregroundResourceWaitMs(timeoutMs, this.resourceWaitMs), signal: context.signal,
+        });
     return new Promise((resolvePromise, rejectPromise) => {
       const stdout = new BoundedOutput(maxOutputBytes);
       const stderr = new BoundedOutput(maxOutputBytes);
@@ -155,62 +155,64 @@ export class ProcessExecutionService {
       const retainedStderr = options.retainOutput ? new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES) : null;
       let child;
       try {
-        child = this.spawnProcess(cmd, args, {
+        const launch = internalFixed
+          ? { command: cmd, args }
+          : delegatedProcessCommand({ command: admitted.command, args: admitted.args, workspace: this.workspace, runtimeDir: this.runtimeDir, context });
+        child = this.spawnProcess(launch.command, launch.args, {
           cwd,
-          env: executionEnv(this.workspace, { fullEnv: this.policy.minimalEnv === false, runtimeDir: this.runtimeDir }),
+          env: admitted.environment,
           detached: process.platform !== "win32",
           windowsHide: true,
           shell: false,
         });
       } catch (error) {
-        rejectPromise(error);
+        void releaseProcessResourcesQuietly(admitted.lease).then(() => rejectPromise(
+          processPreSpawnFailure(error, options.nonReplayableMutation === true),
+        ));
         return;
       }
-
       this.processTracker.track(child, context.callId);
+      let resourceBindError = null; let childError = null;
+      const resourceBinding = bindProcessResources(admitted.lease, child).catch((error) => { resourceBindError = error; this.terminateProcess(child); });
       if (stdin !== null) {
         child.stdin?.on?.("error", () => {});
         child.stdin?.end?.(String(stdin));
       }
-
       let settled = false;
       let processClosed = false;
       let terminationTimer = null;
       let timeoutTimer = null;
       const signal = context.signal;
-
-      const cleanupAfterClose = () => {
+      const nonReplayableMutation = options.nonReplayableMutation === true;
+      const cleanupAfterClose = async () => {
         if (processClosed) return;
         processClosed = true;
         clearTimeout(timeoutTimer);
         signal?.removeEventListener?.("abort", onAbort);
         this.processTracker.untrack(child);
+        await resourceBinding;
+        await releaseProcessResources(admitted.lease);
       };
-
       const settle = (callback) => {
         if (settled) return false;
         settled = true;
         callback();
         return true;
       };
-
       const terminate = () => {
         if (terminationTimer || processClosed) return;
         terminationTimer = this.terminateProcess(child);
       };
-
       const rejectCancelled = () => {
         terminate();
-        const reason = signal?.reason;
-        settle(() => rejectPromise(reason instanceof Error ? reason : new BridgeError("cancelled", "tool call cancelled")));
+        settle(() => rejectPromise(processCancellationFailure(nonReplayableMutation, signal)));
       };
-
       const onAbort = () => rejectCancelled();
       signal?.addEventListener?.("abort", onAbort, { once: true });
 
       timeoutTimer = setTimeout(() => {
         terminate();
-        settle(() => rejectPromise(new BridgeError("timeout", `command timed out after ${timeoutMs}ms`, { retryable: true })));
+        settle(() => rejectPromise(processTimeoutFailure(nonReplayableMutation, timeoutMs)));
       }, timeoutMs);
       timeoutTimer.unref?.();
 
@@ -223,31 +225,42 @@ export class ProcessExecutionService {
         retainedStderr?.append(chunk);
       });
 
-      child.on("error", (error) => {
-        cleanupAfterClose();
-        settle(() => {
-          if (allowFailure) resolvePromise(processResult(127, stdout, error.message || stderr.text(), retainedStdout, retainedStderr));
-          else rejectPromise(error);
-        });
-      });
-
-      child.on("close", (code) => {
-        cleanupAfterClose();
-        if (settled) return;
-        try { this.throwIfCancelled(context); } catch (error) {
-          settle(() => rejectPromise(error));
-          return;
-        }
-        const result = processResult(code, stdout, stderr, retainedStdout, retainedStderr);
-        if (code === 0 || allowFailure) settle(() => resolvePromise(result));
-        else settle(() => rejectPromise(new BridgeError("execution_failed", processFailureMessage(result), { details: { process: result } })));
+      child.on("error", (error) => { childError ||= error; });
+      attachChildProcessSettlement(child, {
+        ...this.childSettlementOptions,
+        onSettle: (code) => {
+          void cleanupAfterClose().then(() => {
+          if (settled) return;
+          if (resourceBindError) {
+            settle(() => rejectPromise(processPostSpawnFailure(nonReplayableMutation, "resource_binding", resourceBindError)));
+            return;
+          }
+          if (childError) {
+            const failure = processResult(127, stdout, childError.message || stderr.text(), retainedStdout, retainedStderr);
+            settle(() => {
+              if (nonReplayableMutation) rejectPromise(processChildErrorFailure(true, childError, Boolean(child?.pid)));
+              else if (allowFailure) resolvePromise(failure);
+              else rejectPromise(childError);
+            });
+            return;
+          }
+          try { this.throwIfCancelled(context); } catch (error) {
+            const trigger = signal?.reason instanceof BridgeError && signal.reason.code === "timeout" ? "timeout" : "cancelled";
+            settle(() => rejectPromise(processPostSpawnFailure(nonReplayableMutation, trigger, error)));
+            return;
+          }
+          const result = processResult(code, stdout, stderr, retainedStdout, retainedStderr);
+          if (code === 0 || allowFailure) settle(() => resolvePromise(result));
+          else settle(() => rejectPromise(processPostSpawnFailure(nonReplayableMutation, "nonzero_exit",
+            new BridgeError("execution_failed", processFailureMessage(result), { details: { process: result } }), { process: result })));
+          }, rejectPromise);
+        },
       });
 
       if (signal?.aborted) rejectCancelled();
     });
   }
 }
-
 function processResult(code, stdout, stderr, retainedStdout = null, retainedStderr = null) {
   const stderrBuffer = stderr instanceof BoundedOutput ? stderr : null;
   const result = {
@@ -265,7 +278,6 @@ function processResult(code, stdout, stderr, retainedStdout = null, retainedStde
   }
   return result;
 }
-
 export function boundedErrorMessage(error) {
   const message = error instanceof Error ? error.message : String(error);
   return message.replace(/[\r\n]+/g, " ").slice(0, 4096) || "tool call failed";

package/src/local/process-foreground-timeout.mjs

@@ -0,0 +1,50 @@
+import {
+  effectiveForegroundTimeoutSeconds,
+  remoteForegroundDefaultSeconds,
+  remoteDurableProcessTimeoutSeconds,
+} from "../shared/foreground-timeout.mjs";
+import { MAX_PROCESS_TIMEOUT_SECONDS } from "./execution-limits.mjs";
+
+// Relay-origin process one-shots should be routed through durable delivery before reaching this module.
+// Keep a narrower defense-in-depth ceiling for any accidental direct foreground entry without advertising
+// that value as a supported remote process delivery contract.
+const REMOTE_PROCESS_FOREGROUND_DEFENSE_MAX_SECONDS = 30;
+
+export function processForegroundTimeoutSeconds(tool, value, context = {}) {
+  const remote = context.origin === "relay";
+  const timeout = effectiveForegroundTimeoutSeconds({
+    tool,
+    value,
+    remote,
+    localDefault: 120,
+    localMaximum: MAX_PROCESS_TIMEOUT_SECONDS,
+  });
+  if (remote && timeout > REMOTE_PROCESS_FOREGROUND_DEFENSE_MAX_SECONDS) {
+    throw new RangeError(`foreground timeout must be an integer from 1 to ${REMOTE_PROCESS_FOREGROUND_DEFENSE_MAX_SECONDS}`);
+  }
+  return timeout;
+}
+
+export function registeredCommandTimeoutSeconds(args, command, context = {}) {
+  const remote = context.origin === "relay";
+  const requested = args.timeout_seconds === undefined
+    ? (remote ? remoteForegroundDefaultSeconds("run_local_command") : command.timeoutSeconds)
+    : processForegroundTimeoutSeconds("run_local_command", args.timeout_seconds, context);
+  return Math.min(
+    requested,
+    command.timeoutSeconds,
+    remote ? REMOTE_PROCESS_FOREGROUND_DEFENSE_MAX_SECONDS : MAX_PROCESS_TIMEOUT_SECONDS,
+  );
+}
+
+export function durableProcessExecutionTimeoutSeconds(value) {
+  return remoteDurableProcessTimeoutSeconds(value);
+}
+
+export function durableRegisteredCommandTimeoutSeconds(args, command) {
+  return Math.min(
+    remoteDurableProcessTimeoutSeconds(args.timeout_seconds),
+    command.timeoutSeconds,
+    MAX_PROCESS_TIMEOUT_SECONDS,
+  );
+}

package/src/local/process-identity.mjs

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
 import { performance } from "node:perf_hooks";
 
 const COMMAND_TIMEOUT_MS = 3000;
@@ -25,15 +25,30 @@ export function processStartTimeMs(pid) {
   const parsed = normalizePid(pid);
   if (!parsed) return null;
   if (parsed === process.pid) return currentProcessStartTimeMs();
-  if (process.platform === "win32") {
-    const command = `(Get-CimInstance Win32_Process -Filter "ProcessId = ${parsed}").CreationDate.ToUniversalTime().ToString('o')`;
-    const result = runBounded("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command]);
-    return result.ok ? parseTime(result.stdout) : null;
-  }
-  const result = runBounded("ps", ["-p", String(parsed), "-o", "lstart="]);
+  const [command, args] = processStartCommand(parsed);
+  const result = runBounded(command, args);
+  return result.ok ? parseTime(result.stdout) : null;
+}
+
+export async function processStartTimeMsAsync(pid) {
+  const parsed = normalizePid(pid);
+  if (!parsed) return null;
+  if (parsed === process.pid) return currentProcessStartTimeMs();
+  const [command, args] = processStartCommand(parsed);
+  const result = await runBoundedAsync(command, args);
   return result.ok ? parseTime(result.stdout) : null;
 }
 
+export function processState(pid) {
+  const parsed = normalizePid(pid);
+  if (!parsed || process.platform === "win32") return "unknown";
+  const result = runBounded("ps", ["-p", String(parsed), "-o", "state="]);
+  if (!result.ok) return "unknown";
+  const state = result.stdout.trim().charAt(0).toUpperCase();
+  if (state === "Z") return "zombie";
+  return state ? "running" : "unknown";
+}
+
 export function processCommandLine(pid) {
   const parsed = normalizePid(pid);
   if (!parsed) return "";
@@ -119,10 +134,19 @@ export function inspectProcessInstance(owner, options = {}) {
   };
 }
 
+function processStartCommand(pid) {
+  if (process.platform === "win32") {
+    const command = `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CreationDate.ToUniversalTime().ToString('o')`;
+    return ["powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command]];
+  }
+  return ["ps", ["-p", String(pid), "-o", "lstart="]];
+}
+
 function runBounded(command, args) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
     timeout: COMMAND_TIMEOUT_MS,
+    killSignal: "SIGKILL",
     maxBuffer: COMMAND_OUTPUT_BYTES,
     windowsHide: true,
     env: process.platform === "win32" ? process.env : { ...process.env, LC_ALL: "C", LANG: "C" },
@@ -131,6 +155,16 @@ function runBounded(command, args) {
   return { ok: !result.error && result.status === 0, stdout: String(result.stdout || "") };
 }
 
+function runBoundedAsync(command, args) {
+  return new Promise((resolvePromise) => {
+    execFile(command, args, {
+      encoding: "utf8", timeout: COMMAND_TIMEOUT_MS, killSignal: "SIGKILL",
+      maxBuffer: COMMAND_OUTPUT_BYTES, windowsHide: true,
+      env: process.platform === "win32" ? process.env : { ...process.env, LC_ALL: "C", LANG: "C" },
+    }, (error, stdout) => resolvePromise({ ok: !error, stdout: String(stdout || "") }));
+  });
+}
+
 function normalizePid(value) {
   const parsed = Number(value);
   return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;

package/src/local/process-nonreplayable-settlement.mjs

@@ -0,0 +1,50 @@
+// @ts-check
+import { BridgeError } from "./errors.mjs";
+import { processOutcomeUnknownAfterSpawn } from "./process-result-projection.mjs";
+
+/** @param {unknown} error @param {boolean} nonReplayable */
+export function processPreSpawnFailure(error, nonReplayable) {
+  if (!nonReplayable || error instanceof BridgeError) return error;
+  return new BridgeError("execution_failed", "process failed before spawn", {
+    cause: error instanceof Error ? error : undefined,
+    retryable: false,
+    details: { reason: "process_failed_before_spawn" },
+  });
+}
+
+/** @param {boolean} nonReplayable @param {AbortSignal | undefined} signal */
+export function processCancellationFailure(nonReplayable, signal) {
+  const reason = signal?.reason;
+  const code = reason instanceof BridgeError && reason.code === "timeout" ? "timeout" : "cancelled";
+  if (nonReplayable) return processOutcomeUnknownAfterSpawn(code);
+  return new BridgeError(code, reason instanceof Error ? reason.message : "tool call cancelled", {
+    retryable: false,
+    cause: reason instanceof Error ? reason : undefined,
+    details: { side_effects_started: true, termination_requested: true, effect_settlement: "pending" },
+  });
+}
+
+/** @param {boolean} nonReplayable @param {number} timeoutMs */
+export function processTimeoutFailure(nonReplayable, timeoutMs) {
+  if (nonReplayable) return processOutcomeUnknownAfterSpawn("timeout");
+  return new BridgeError("timeout", `command timed out after ${timeoutMs}ms`, {
+    retryable: false,
+    details: { side_effects_started: true, termination_requested: true, effect_settlement: "pending" },
+  });
+}
+
+/** @param {boolean} nonReplayable @param {string} trigger @param {unknown} fallback @param {Record<string, unknown>} [details] */
+export function processPostSpawnFailure(nonReplayable, trigger, fallback, details = {}) {
+  return nonReplayable ? processOutcomeUnknownAfterSpawn(trigger, details) : fallback;
+}
+
+/** @param {boolean} nonReplayable @param {unknown} error @param {boolean} started */
+export function processChildErrorFailure(nonReplayable, error, started) {
+  if (!nonReplayable) return error;
+  if (started) return processOutcomeUnknownAfterSpawn("process_error");
+  return new BridgeError("execution_failed", "process failed before spawn", {
+    cause: error instanceof Error ? error : undefined,
+    retryable: false,
+    details: { reason: "process_failed_before_spawn" },
+  });
+}

package/src/local/process-result-projection.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { MCP_TEXT_PROJECTION_KEY } from "../shared/result-projection.mjs";
+import { BridgeError } from "./errors.mjs";
 
 /** @param {Record<string, any>} value */
 export function publicProcessToolResult(value) {
@@ -12,6 +13,27 @@ export function publicProcessToolResult(value) {
   return { ...value, [MCP_TEXT_PROJECTION_KEY]: summary };
 }
 
+/** @param {string} trigger @param {Record<string, unknown>} [details] */
+export function processOutcomeUnknownAfterSpawn(trigger, details = {}) {
+  const terminationRequested = trigger === "cancelled" || trigger === "timeout" || trigger === "resource_binding";
+  return new BridgeError(
+    "execution_failed",
+    "command execution may have partially completed; the outcome is unknown. Inspect command effects before retrying.",
+    {
+      expose: true,
+      retryable: false,
+      details: {
+        ...details,
+        reason: "process_outcome_unknown_after_spawn",
+        trigger: String(trigger || "unknown").slice(0, 64),
+        side_effects_started: "unknown",
+        termination_requested: terminationRequested,
+        effect_settlement: terminationRequested ? "pending" : "unknown",
+      },
+    },
+  );
+}
+
 /** @param {Record<string, any>} result */
 export function processFailureMessage(result) {
   const source = String(result.stderr || result.stdout || `process exited ${result.code}`)

package/src/local/process-session-events.mjs

@@ -0,0 +1,47 @@
+export function waitForSpawn(child) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const onSpawn = () => { cleanup(); resolvePromise(); };
+    const onError = (error) => { cleanup(); rejectPromise(error); };
+    const cleanup = () => {
+      child.off("spawn", onSpawn);
+      child.off("error", onError);
+    };
+    child.once("spawn", onSpawn);
+    child.once("error", onError);
+  });
+}
+
+export function sessionHasOutputAfter(session, stdoutOffset, stderrOffset) {
+  return session.stdout.totalBytes > stdoutOffset || session.stderr.totalBytes > stderrOffset;
+}
+
+export function notifySessionWaiters(session) {
+  for (const waiter of [...session.waiters]) waiter();
+}
+
+export function waitForSessionChange(session, waitMs, cancellationCheck, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let timer;
+    const done = () => {
+      cleanup();
+      try {
+        cancellationCheck();
+        resolvePromise();
+      } catch (error) {
+        rejectPromise(error);
+      }
+    };
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      session.waiters.delete(done);
+    };
+    session.waiters.add(done);
+    timer = setTimeout(done, waitMs);
+    if (options.keepAlive !== true) timer.unref?.();
+  });
+}
+
+export function boundedErrorMessage(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/[\r\n]+/g, " ").slice(0, 4096) || "process failed";
+}

package/src/local/process-session-remote-activity.mjs

@@ -0,0 +1,10 @@
+export function beginRemoteProcessSessionActivity(context, guard) {
+  if (context?.origin !== "relay" || !guard) return false;
+  try { guard.beginActivity?.(); } catch { /* Auxiliary power management must not change session startup. */ }
+  return true;
+}
+
+export function endRemoteProcessSessionActivity(held, guard) {
+  if (!held || !guard) return;
+  try { guard.endActivity?.(); } catch { /* Auxiliary power management must not change session settlement. */ }
+}

package/src/local/process-session-termination.mjs

@@ -0,0 +1,73 @@
+import { BridgeError } from "./errors.mjs";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+import { notifySessionWaiters, waitForSessionChange } from "./process-session-events.mjs";
+
+export async function terminateProcessSessions({
+  sessions,
+  matches = () => true,
+  terminateTree,
+  signal = "SIGKILL",
+  waitMs = 5_000,
+  mode = "shutdown",
+}) {
+  const contract = terminationContract(mode);
+  let settledCount = 0;
+  let failure = null;
+  const settlements = [];
+  for (const [id, session] of [...sessions.entries()]) {
+    if (!matches(session)) continue;
+    notifySessionWaiters(session);
+    if (session.closedAt !== null) {
+      if (sessions.get(id) === session) sessions.delete(id);
+      settledCount += 1;
+      continue;
+    }
+    if (!session.child) {
+      failure ||= new Error(contract.missingChild);
+      continue;
+    }
+    let requested = false;
+    try { requested = terminateTree(session.child, signal) === true; }
+    catch { /* The retained session handle makes failed termination delivery retryable. */ }
+    if (!requested) {
+      failure ||= new Error(contract.requestFailure);
+      continue;
+    }
+    settlements.push(settleProcessSession(sessions, id, session, waitMs).then((settled) => {
+      if (settled) settledCount += 1;
+      else failure ||= new Error(contract.settlementFailure);
+    }));
+  }
+  await Promise.all(settlements);
+  if (failure) {
+    throw new BridgeError("unavailable", contract.unavailable, { cause: failure, retryable: true });
+  }
+  return settledCount;
+}
+
+async function settleProcessSession(sessions, id, session, waitMs) {
+  const deadline = createMonotonicDeadline(waitMs);
+  while (session.closedAt === null && !deadline.expired()) {
+    await waitForSessionChange(session, Math.max(1, deadline.remainingMs()), () => {}, { keepAlive: true });
+  }
+  if (session.closedAt === null) return false;
+  if (sessions.get(id) === session) sessions.delete(id);
+  return true;
+}
+
+function terminationContract(mode) {
+  if (mode === "authority_revocation") {
+    return {
+      missingChild: "process-session termination request could not be delivered",
+      requestFailure: "process-session termination request could not be delivered",
+      settlementFailure: "process-session termination did not settle before the revocation deadline",
+      unavailable: "process-session authority revocation was incomplete; retained revocation must be retried",
+    };
+  }
+  return {
+    missingChild: "process-session shutdown has no retained child handle",
+    requestFailure: "process-session shutdown request could not be delivered",
+    settlementFailure: "process-session shutdown did not settle before the runtime teardown deadline",
+    unavailable: "process-session shutdown was incomplete; runtime ownership must be retained",
+  };
+}