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

package/src/local/process-sessions.mjs

@@ -1,51 +1,83 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { basename } from "node:path";
+import { performance } from "node:perf_hooks";
 import { executionEnv } from "./shell.mjs";
+import { attachChildProcessSettlement } from "./child-process-settlement.mjs";
+import { assertOwnedByContext, principalBinding, visibleToContext } from "./authority-context.mjs";
+import { recordMatchesAuthorityRevocation } from "../shared/authority-revocation.mjs";
+import { delegatedProcessCommand } from "./delegated-process-sandbox.mjs";
 import { validateArgv } from "./process-contract.mjs";
 import { terminateProcessTree, terminateProcessTreeWithEscalation } from "./process-tree.mjs";
 import { createToolAuthorizer } from "./policy.mjs";
+import { BridgeError, errorCode } from "./errors.mjs";
 import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
 import { clampInteger } from "./numbers.mjs";
 import { ProcessOutputStream } from "./process-output-stream.mjs";
-import {
-  MAX_PROCESS_SESSIONS, MAX_PROCESS_SESSION_OUTPUT_BYTES, MAX_PROCESS_SESSION_STDIN_BYTES, PROCESS_SESSION_RETENTION_MS,
-} from "./execution-limits.mjs";
-
+import { boundedErrorMessage, notifySessionWaiters, sessionHasOutputAfter, waitForSessionChange, waitForSpawn } from "./process-session-events.mjs";
+import { terminateProcessSessions } from "./process-session-termination.mjs";
+import { acquireProcessResources, bindProcessResources, releaseProcessResources, releaseProcessResourcesQuietly } from "./resource-process-admission.mjs";
+import { processSessionResourceWaitMs } from "./resource-foreground-wait.mjs";
+import { beginRemoteProcessSessionActivity, endRemoteProcessSessionActivity } from "./process-session-remote-activity.mjs";
+import { EXECUTION_SURFACE, withExecutionSurface } from "./execution-surface.mjs";
+import { MAX_PROCESS_SESSIONS, MAX_PROCESS_SESSION_OUTPUT_BYTES, MAX_PROCESS_SESSION_STDIN_BYTES, PROCESS_SESSION_RETENTION_MS } from "./execution-limits.mjs";
+const PROCESS_SESSION_TERMINATION_SETTLEMENT_MS = 5_000;
 export class ProcessSessionManager {
-  constructor({ workspace, policy, authorizeTool = null, runtimeDir, processTracker, resolveCwd, displayPath, throwIfCancelled }) {
+  constructor({ workspace, policy, authorizeTool = null, policyForContext = null, runtimeDir, processTracker, resourceCoordinator = null, resourceWaitMs = undefined, terminationSettlementWaitMs = PROCESS_SESSION_TERMINATION_SETTLEMENT_MS, resolveCwd, displayPath, throwIfCancelled, terminateTree = terminateProcessTree, spawnProcess = spawn, childSettlementOptions = {}, remoteActivityGuard = null, now = () => performance.now(), wallNow = Date.now }) {
     this.workspace = workspace;
     this.policy = policy;
     this.authorizeTool = createToolAuthorizer(this.policy, authorizeTool);
+    this.policyForContext = typeof policyForContext === "function" ? policyForContext : () => this.policy;
     this.runtimeDir = runtimeDir;
     this.processTracker = processTracker;
+    this.resourceCoordinator = resourceCoordinator;
+    this.resourceWaitMs = resourceWaitMs;
+    this.terminationSettlementWaitMs = clampInteger(terminationSettlementWaitMs, PROCESS_SESSION_TERMINATION_SETTLEMENT_MS, 1, 30_000);
     this.resolveCwd = resolveCwd;
     this.displayPath = displayPath;
     this.throwIfCancelled = throwIfCancelled;
+    this.terminateTree = typeof terminateTree === "function" ? terminateTree : terminateProcessTree;
+    this.spawnProcess = spawnProcess;
+    this.childSettlementOptions = childSettlementOptions;
+    this.remoteActivityGuard = remoteActivityGuard;
+    this.now = typeof now === "function" ? now : () => performance.now();
+    this.wallNow = typeof wallNow === "function" ? wallNow : Date.now;
     this.sessions = new Map();
   }
 
-  status() {
+  status(context = {}) {
+    const visible = [...this.sessions.values()].filter((session) => visibleToContext(session, context));
     return {
-      active: [...this.sessions.values()].filter((session) => session.closedAt === null).length,
-      retained: this.sessions.size,
+      active: visible.filter((session) => session.closedAt === null).length,
+      retained: visible.length,
       maximum: MAX_PROCESS_SESSIONS,
     };
   }
 
-  clear() {
-    this.sessions.clear();
+  async clearAndWait(signal = "SIGKILL") {
+    return terminateProcessSessions({
+      sessions: this.sessions, terminateTree: this.terminateTree, signal,
+      waitMs: this.terminationSettlementWaitMs, mode: "shutdown",
+    });
+  }
+
+  async revokeAuthority(revocation) {
+    return terminateProcessSessions({
+      sessions: this.sessions, terminateTree: this.terminateTree, signal: "SIGKILL",
+      waitMs: this.terminationSettlementWaitMs, mode: "authority_revocation",
+      matches: (session) => recordMatchesAuthorityRevocation(session, revocation),
+    });
   }
 
   notifyCancellation() {
     for (const session of this.sessions.values()) notifySessionWaiters(session);
   }
 
-  retainCompletedOutput({ command, cwd, stdout, stderr, exitCode, startedAt, closedAt = Date.now() }) {
+  retainCompletedOutput({ command, cwd, stdout, stderr, exitCode, startedAt, closedAt = this.wallNow() }, context = {}) {
     this.prune();
     this.evictExitedForCapacity();
     if (this.sessions.size >= MAX_PROCESS_SESSIONS) return null;
-    const completedAt = Number.isFinite(Number(closedAt)) ? Number(closedAt) : Date.now();
+    const completedAt = Number.isFinite(Number(closedAt)) ? Number(closedAt) : this.wallNow();
     const session = {
       id: `proc_${randomBytes(24).toString("base64url")}`,
       child: null,
@@ -54,33 +86,44 @@ export class ProcessSessionManager {
       stdout,
       stderr,
       startedAt: Number.isFinite(Number(startedAt)) ? Number(startedAt) : completedAt,
-      lastActivity: completedAt,
+      lastActivityMonotonic: this.now(),
       closedAt: completedAt,
       exitCode: Number.isInteger(exitCode) ? exitCode : null,
       signal: null,
       stdinClosed: true,
       waiters: new Set(),
       terminationTimer: null,
+      ...principalBinding(context),
     };
     this.sessions.set(session.id, session);
-    return this.summary(session);
+    return this.summary(session, context);
   }
 
   async start(args, context = {}) {
     this.authorizeTool("start_process");
     const argv = validateArgv(args.argv);
-    const cwd = await this.resolveCwd(args.cwd || ".");
+    const cwd = await this.resolveCwd(args.cwd || ".", context);
     this.prune();
     this.evictExitedForCapacity();
     if (this.sessions.size >= MAX_PROCESS_SESSIONS) throw new Error(`process session limit reached (${MAX_PROCESS_SESSIONS})`);
     this.throwIfCancelled(context);
-
-    const child = spawn(argv[0], argv.slice(1), {
-      cwd,
-      env: executionEnv(this.workspace, { fullEnv: this.policy.minimalEnv === false, runtimeDir: this.runtimeDir }),
-      detached: process.platform !== "win32",
-      windowsHide: true,
+    const executionEnvironment = withExecutionSurface(executionEnv(this.workspace, { fullEnv: this.policyForContext(context).minimalEnv === false, runtimeDir: this.runtimeDir }), EXECUTION_SURFACE.processSession);
+    const admitted = await acquireProcessResources(this.resourceCoordinator, argv[0], argv.slice(1), executionEnvironment, {
+      cwd, priority: "interactive", waitMs: processSessionResourceWaitMs(this.resourceWaitMs, { remote: context?.authority?.origin === "relay" }), signal: context.signal,
     });
+    const launch = delegatedProcessCommand({ command: admitted.command, args: admitted.args, workspace: this.workspace, runtimeDir: this.runtimeDir, context });
+    const remoteActivityHeld = beginRemoteProcessSessionActivity(context, this.remoteActivityGuard);
+    let child;
+    try {
+      child = this.spawnProcess(launch.command, launch.args, { cwd, env: admitted.environment, detached: process.platform !== "win32", windowsHide: true });
+    } catch (error) {
+      endRemoteProcessSessionActivity(remoteActivityHeld, this.remoteActivityGuard);
+      await releaseProcessResources(admitted.lease);
+      throw error;
+    }
+    let resolveResourceBindingSettled;
+    const resourceBindingSettled = new Promise((resolvePromise) => { resolveResourceBindingSettled = resolvePromise; });
+    const startedAt = this.wallNow();
     const session = {
       id: `proc_${randomBytes(24).toString("base64url")}`,
       child,
@@ -88,57 +131,94 @@ export class ProcessSessionManager {
       cwd,
       stdout: new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES),
       stderr: new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES),
-      startedAt: Date.now(),
-      lastActivity: Date.now(),
+      startedAt,
+      lastActivityMonotonic: this.now(),
       closedAt: null,
       exitCode: null,
       signal: null,
       stdinClosed: false,
       waiters: new Set(),
       terminationTimer: null,
+      startupFailed: false,
+      resourceLease: admitted.lease,
+      resourceBindingSettled,
+      ...principalBinding(context),
     };
     this.sessions.set(session.id, session);
     this.trackChild(child, context.callId);
 
     child.stdout.on("data", (chunk) => {
       session.stdout.append(chunk);
-      session.lastActivity = Date.now();
+      this.markActivity(session);
       notifySessionWaiters(session);
     });
     child.stderr.on("data", (chunk) => {
       session.stderr.append(chunk);
-      session.lastActivity = Date.now();
+      this.markActivity(session);
       notifySessionWaiters(session);
     });
-    child.on("close", (code, signal) => {
-      session.exitCode = Number.isInteger(code) ? code : null;
-      session.signal = signal ? String(signal) : null;
-      session.closedAt = Date.now();
-      session.lastActivity = Date.now();
-      session.stdinClosed = true;
-      this.untrackChild(child);
-      notifySessionWaiters(session);
+    attachChildProcessSettlement(child, {
+      ...this.childSettlementOptions,
+      onSettle: (code, signal) => {
+        session.exitCode = Number.isInteger(code) ? code : null;
+        session.signal = signal ? String(signal) : null;
+        session.closedAt = this.wallNow();
+        this.markActivity(session);
+        session.stdinClosed = true;
+        this.untrackChild(child);
+        endRemoteProcessSessionActivity(remoteActivityHeld, this.remoteActivityGuard);
+        void session.resourceBindingSettled.then(() => releaseProcessResourcesQuietly(session.resourceLease));
+        if (session.startupFailed) this.sessions.delete(session.id);
+        notifySessionWaiters(session);
+      },
     });
 
     child.on("error", (error) => {
       session.stderr.append(Buffer.from(`${boundedErrorMessage(error)}\n`));
-      session.lastActivity = Date.now();
+      this.markActivity(session);
       notifySessionWaiters(session);
     });
     try {
       await waitForSpawn(child);
+      await bindProcessResources(admitted.lease, child);
+      resolveResourceBindingSettled();
     } catch (error) {
+      resolveResourceBindingSettled();
+      throw this.failedStartError(session, error);
+    }
+    try { this.throwIfCancelled(context); }
+    catch (error) { throw this.failedStartError(session, error); }
+    return this.summary(session, context);
+  }
+
+  failedStartError(session, error) {
+    session.startupFailed = true; session.stdinClosed = true;
+    try { session.child?.stdin?.destroy?.(); }
+    catch { /* Startup failure already owns the error path; closing stdin is best-effort cleanup. */ }
+    if (session.closedAt !== null) {
       this.sessions.delete(session.id);
-      this.untrackChild(child);
-      throw error;
+      return error;
     }
-    this.throwIfCancelled(context);
-    return this.summary(session);
+    let terminationRequested = false;
+    try { terminationRequested = this.terminateTree(session.child, "SIGKILL") === true; }
+    catch { /* The returned settlement metadata records that child termination could not be confirmed. */ }
+    this.markActivity(session);
+    const code = errorCode(error);
+    return new BridgeError(code, "process session start failed after the child was spawned", {
+      cause: error instanceof Error ? error : undefined,
+      retryable: false,
+      details: {
+        side_effects_started: true,
+        termination_requested: terminationRequested,
+        effect_settlement: terminationRequested ? "pending" : "unknown",
+        ownership_retained_until_close: true,
+      },
+    });
   }
 
   async read(args, context = {}) {
     this.authorizeTool("read_process");
-    const session = this.get(args.session_id);
+    const session = this.get(args.session_id, context);
     const stdoutOffset = clampInteger(args.stdout_offset, 0, 0, Number.MAX_SAFE_INTEGER);
     const stderrOffset = clampInteger(args.stderr_offset, 0, 0, Number.MAX_SAFE_INTEGER);
     const maxBytes = clampInteger(args.max_bytes, 64 * 1024, 1, 256 * 1024);
@@ -156,9 +236,9 @@ export class ProcessSessionManager {
       }
     }
     this.throwIfCancelled(context);
-    session.lastActivity = Date.now();
+    this.markActivity(session);
     return {
-      ...this.summary(session),
+      ...this.summary(session, context),
       stdout: session.stdout.read(stdoutOffset, maxBytes),
       stderr: session.stderr.read(stderrOffset, maxBytes),
     };
@@ -166,7 +246,7 @@ export class ProcessSessionManager {
 
   async write(args, context = {}) {
     this.authorizeTool("write_process");
-    const session = this.get(args.session_id);
+    const session = this.get(args.session_id, context);
     if (session.closedAt !== null) throw new Error("process session has already exited");
     const data = String(args.data ?? "");
     if (Buffer.byteLength(data) > MAX_PROCESS_SESSION_STDIN_BYTES) throw new Error(`stdin data exceeds maximum size (${MAX_PROCESS_SESSION_STDIN_BYTES} bytes)`);
@@ -181,43 +261,48 @@ export class ProcessSessionManager {
       session.child.stdin.end();
       session.stdinClosed = true;
     }
-    session.lastActivity = Date.now();
-    return { ...this.summary(session), bytes_written: Buffer.byteLength(data) };
+    this.markActivity(session);
+    return { ...this.summary(session, context), bytes_written: Buffer.byteLength(data) };
   }
 
   async kill(args, context = {}) {
     this.authorizeTool("kill_process");
-    const session = this.get(args.session_id);
+    const session = this.get(args.session_id, context);
     this.throwIfCancelled(context);
     const wasRunning = session.closedAt === null;
     const force = args.force === true;
-    if (wasRunning && force) terminateProcessTree(session.child, "SIGKILL");
-    else if (wasRunning && !session.terminationTimer) {
-      session.terminationTimer = terminateProcessTreeWithEscalation(session.child);
+    if (wasRunning && force && !this.terminateTree(session.child, "SIGKILL")) {
+      throw new BridgeError("unavailable", "process termination request could not be delivered", { retryable: true });
+    } else if (wasRunning && !force && !session.terminationTimer) {
+      session.terminationTimer = terminateProcessTreeWithEscalation(session.child, {
+        terminate: this.terminateTree,
+        onTerminationSettled: () => { session.terminationTimer = null; },
+      });
     }
-    session.lastActivity = Date.now();
+    this.markActivity(session);
     return {
-      ...this.summary(session),
+      ...this.summary(session, context),
       termination_requested: wasRunning,
       force,
       force_after_ms: wasRunning && !force ? 2000 : null,
     };
   }
 
-  get(sessionId) {
+  get(sessionId, context = {}) {
     this.prune();
     const id = String(sessionId || "");
     if (!/^proc_[A-Za-z0-9_-]{20,}$/.test(id)) throw new Error("invalid process session id");
     const session = this.sessions.get(id);
     if (!session) throw new Error("process session not found or expired");
+    assertOwnedByContext(session, context, "process session");
     return session;
   }
 
-  summary(session) {
+  summary(session, context = {}) {
     return {
       session_id: session.id,
       command: session.argv0,
-      cwd: this.displayPath(session.cwd),
+      cwd: this.displayPath(session.cwd, context),
       running: session.closedAt === null,
       exit_code: session.exitCode,
       signal: session.signal,
@@ -230,9 +315,9 @@ export class ProcessSessionManager {
   }
 
   prune() {
-    const cutoff = Date.now() - PROCESS_SESSION_RETENTION_MS;
+    const cutoff = this.now() - PROCESS_SESSION_RETENTION_MS;
     for (const [id, session] of this.sessions) {
-      if (session.closedAt !== null && session.lastActivity < cutoff) this.sessions.delete(id);
+      if (session.closedAt !== null && session.lastActivityMonotonic < cutoff) this.sessions.delete(id);
     }
   }
 
@@ -240,67 +325,14 @@ export class ProcessSessionManager {
     if (this.sessions.size < MAX_PROCESS_SESSIONS) return;
     const exited = [...this.sessions.values()]
       .filter((session) => session.closedAt !== null)
-      .sort((left, right) => left.lastActivity - right.lastActivity);
+      .sort((left, right) => left.lastActivityMonotonic - right.lastActivityMonotonic);
     for (const session of exited) {
       if (this.sessions.size < MAX_PROCESS_SESSIONS) break;
       this.sessions.delete(session.id);
     }
   }
 
-
-  trackChild(child, callId) {
-    this.processTracker.track(child, callId);
-  }
-
-  untrackChild(child) {
-    this.processTracker.untrack(child);
-  }
-}
-
-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);
-  });
-}
-
-function sessionHasOutputAfter(session, stdoutOffset, stderrOffset) {
-  return session.stdout.totalBytes > stdoutOffset || session.stderr.totalBytes > stderrOffset;
-}
-
-function notifySessionWaiters(session) {
-  for (const waiter of [...session.waiters]) waiter();
-}
-
-function waitForSessionChange(session, waitMs, cancellationCheck) {
-  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);
-    timer.unref?.();
-  });
-}
-
-function boundedErrorMessage(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  return message.replace(/[\r\n]+/g, " ").slice(0, 4096) || "process failed";
+  markActivity(session) { session.lastActivityMonotonic = this.now(); }
+  trackChild(child, callId) { this.processTracker.track(child, callId); }
+  untrackChild(child) { this.processTracker.untrack(child); }
 }

package/src/local/process-tracker.mjs

@@ -1,4 +1,8 @@
 import { terminateProcessTree, terminateProcessTreeWithEscalation } from "./process-tree.mjs";
+import { BridgeError } from "./errors.mjs";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+
+const DEFAULT_DRAIN_WAIT_MS = 5_000;
 
 export class ProcessTracker {
   constructor(options = {}) {
@@ -6,50 +10,173 @@ export class ProcessTracker {
     this.terminateWithEscalation = typeof options.terminateWithEscalation === "function"
       ? options.terminateWithEscalation
       : terminateProcessTreeWithEscalation;
+    this.clearScheduledTermination = typeof options.clearScheduledTermination === "function"
+      ? options.clearScheduledTermination
+      : clearTimeout;
     this.active = new Set();
     this.byCall = new Map();
+    this.childCall = new Map();
+    this.releasedCalls = new Set();
+    this.terminating = new Set();
+    this.terminationTimers = new Map();
+    this.drainSignal = null;
+    this.drainRequested = new Set();
+    this.changeWaiters = new Set();
   }
 
   track(child, callId = "") {
     if (!child) return;
     this.active.add(child);
-    if (!callId) return;
-    const id = String(callId);
-    const children = this.byCall.get(id) || new Set();
-    children.add(child);
-    this.byCall.set(id, children);
+    if (callId) {
+      const id = String(callId);
+      const children = this.byCall.get(id) || new Set();
+      children.add(child);
+      this.byCall.set(id, children);
+      this.childCall.set(child, id);
+    }
+    if (this.drainSignal) this.requestDrainTermination(child);
+    this.notifyChange();
   }
 
   untrack(child) {
     if (!child) return;
     this.active.delete(child);
-    for (const [callId, children] of this.byCall) {
+    this.terminating.delete(child);
+    this.drainRequested.delete(child);
+    const callId = this.childCall.get(child);
+    this.childCall.delete(child);
+    if (callId) {
+      const children = this.byCall.get(callId);
+      children?.delete(child);
+      if (!children?.size) {
+        this.byCall.delete(callId);
+        this.releasedCalls.delete(callId);
+      }
+      this.notifyChange();
+      return;
+    }
+    for (const [id, children] of this.byCall) {
       children.delete(child);
-      if (!children.size) this.byCall.delete(callId);
+      if (!children.size) {
+        this.byCall.delete(id);
+        this.releasedCalls.delete(id);
+      }
     }
+    this.notifyChange();
   }
 
   releaseCall(callId) {
-    if (callId) this.byCall.delete(String(callId));
+    const id = String(callId || "");
+    if (!id) return;
+    if (this.byCall.get(id)?.size) this.releasedCalls.add(id);
+    else {
+      this.byCall.delete(id);
+      this.releasedCalls.delete(id);
+    }
   }
 
   terminateCall(callId, { force = false } = {}) {
     const children = [...(this.byCall.get(String(callId || "")) || [])];
     for (const child of children) {
-      if (force) this.terminate(child, "SIGKILL");
-      else this.terminateWithEscalation(child);
+      this.terminating.add(child);
+      this.requestTermination(child, force);
     }
     return children.length;
   }
 
   terminateAll(signal = "SIGTERM", escalate = false) {
     for (const child of [...this.active]) {
-      if (escalate && signal !== "SIGKILL") this.terminateWithEscalation(child);
-      else this.terminate(child, signal);
+      this.terminating.add(child);
+      if (escalate && signal !== "SIGKILL") this.requestTermination(child, false);
+      else {
+        this.clearTermination(child);
+        this.terminate(child, signal);
+      }
+    }
+  }
+
+  async drain(signal = "SIGKILL", waitMs = DEFAULT_DRAIN_WAIT_MS) {
+    const boundedWaitMs = Number.isFinite(Number(waitMs)) ? Math.max(1, Math.min(30_000, Math.floor(Number(waitMs)))) : DEFAULT_DRAIN_WAIT_MS;
+    this.drainSignal = signal;
+    const deadline = createMonotonicDeadline(boundedWaitMs);
+    while (this.active.size) {
+      for (const child of [...this.active]) this.requestDrainTermination(child);
+      if (!this.active.size) break;
+      if (deadline.expired()) break;
+      await this.waitForChange(Math.max(1, deadline.remainingMs()));
+    }
+    if (this.active.size) {
+      for (const child of this.active) this.drainRequested.delete(child);
+      throw new BridgeError("unavailable", "process shutdown did not settle before the runtime teardown deadline", {
+        retryable: true,
+        details: { active_processes: this.active.size },
+      });
     }
   }
 
   snapshot() {
-    return { active_processes: this.active.size, calls_with_processes: this.byCall.size };
+    let activeCalls = 0;
+    let drainingCalls = 0;
+    let drainingProcesses = 0;
+    for (const [callId, children] of this.byCall) {
+      if (this.releasedCalls.has(callId)) {
+        drainingCalls += 1;
+        drainingProcesses += children.size;
+      } else activeCalls += 1;
+    }
+    return {
+      active_processes: this.active.size,
+      calls_with_processes: activeCalls,
+      draining_calls: drainingCalls,
+      draining_processes: drainingProcesses,
+      terminating_processes: this.terminating.size,
+      termination_escalations_pending: this.terminationTimers.size,
+    };
+  }
+
+  requestTermination(child, force) {
+    if (force) {
+      this.clearTermination(child);
+      this.terminate(child, "SIGKILL");
+      return;
+    }
+    if (this.terminationTimers.has(child)) return;
+    const timer = this.terminateWithEscalation(child, {
+      onTerminationSettled: () => { this.terminationTimers.delete(child); },
+    });
+    if (timer) this.terminationTimers.set(child, timer);
+  }
+
+  clearTermination(child) {
+    const timer = this.terminationTimers.get(child);
+    if (!timer) return;
+    this.clearScheduledTermination(timer);
+    this.terminationTimers.delete(child);
+  }
+
+  requestDrainTermination(child) {
+    if (!child || this.drainRequested.has(child)) return;
+    this.drainRequested.add(child);
+    this.terminating.add(child);
+    this.clearTermination(child);
+    try { this.terminate(child, this.drainSignal || "SIGKILL"); }
+    catch { /* Drain completion is proven by close/untrack, never by the kill request alone. */ }
+  }
+
+  waitForChange(waitMs) {
+    return new Promise((resolvePromise) => {
+      let timer;
+      const done = () => {
+        if (timer) clearTimeout(timer);
+        this.changeWaiters.delete(done);
+        resolvePromise();
+      };
+      this.changeWaiters.add(done);
+      timer = setTimeout(done, waitMs);
+    });
+  }
+
+  notifyChange() {
+    for (const waiter of [...this.changeWaiters]) waiter();
   }
 }

package/src/local/process-tree-ownership-types.d.ts

@@ -0,0 +1,37 @@
+export interface ChildProcessIdentity {
+  pid?: unknown;
+  exitCode?: unknown;
+  signalCode?: unknown;
+}
+
+export interface ProcessGroupEntry {
+  pid: number;
+  pgid: number;
+  startedAt: number;
+}
+
+export interface ProcessOwnershipMember {
+  pid: number;
+  startedAt: number | null;
+}
+
+export interface ProcessOwnershipSnapshot {
+  platform: string;
+  pid: number;
+  members: ProcessOwnershipMember[];
+}
+
+export interface ProcessSnapshotResult {
+  error?: unknown;
+  status?: number | null;
+  stdout?: string | Buffer;
+}
+
+export interface ProcessOwnershipOptions {
+  platform?: string;
+  listProcessGroups?: (options: ProcessOwnershipOptions, pid: number, timeoutMs: number) => ProcessGroupEntry[] | Promise<ProcessGroupEntry[]>;
+  execFileProcess?: (command: string, args: string[], options: Record<string, unknown>) => ProcessSnapshotResult | Promise<ProcessSnapshotResult>;
+  ownershipCheckBudgetMs?: unknown;
+  processSnapshotTimeoutMs?: unknown;
+  monotonicNow?: () => number;
+}