@oar-sh/oar 0.9.0

package/server/services/session-worker-process-service.mjs

@@ -0,0 +1,319 @@
+'use strict';
+
+import { execFileSync } from 'child_process';
+
+function normalizeSessionId(value) {
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+function escapeRegExp(value) {
+  return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function parseSessionIdFromCommandLine(commandLine) {
+  const text = String(commandLine || '');
+  if (!text) return null;
+  const match = text.match(/["']?--(?:session-id|resume)["']?(?:=|\s+)(?:"([^"]+)"|'([^']+)'|([^\s"'=]+))/i);
+  const value = match?.[1] || match?.[2] || match?.[3] || '';
+  return normalizeSessionId(value);
+}
+
+function buildSessionArgPattern(targetSessionId, { includeResume = true } = {}) {
+  const target = normalizeSessionId(targetSessionId);
+  if (!target) return null;
+  const argName = includeResume ? 'session-id|resume' : 'session-id';
+  return new RegExp(
+    `["']?--(?:${argName})["']?(?:=|\\s+)(?:"${escapeRegExp(target)}"|'${escapeRegExp(target)}'|${escapeRegExp(target)})(?:\\s|$)`,
+    'i',
+  );
+}
+
+function scoreWindowsWorkerCandidate(proc) {
+  const name = String(proc?.name || '').trim().toLowerCase();
+  const cmd = String(proc?.commandLine || '').trim().toLowerCase();
+  if (name === 'copilot.exe') return 400;
+  if (name === 'gh.exe' && cmd.includes('copilot')) return 300;
+  if (cmd.includes('gh copilot')) return 250;
+  if (cmd.includes('copilot.cmd') || cmd.includes('copilot-win32')) return 225;
+  if (name === 'cmd.exe' || name === 'powershell.exe' || name === 'conhost.exe') return 50;
+  return 100;
+}
+
+function isWindowsWrapperProcess(proc) {
+  const name = String(proc?.name || '').trim().toLowerCase();
+  return name === 'cmd.exe' || name === 'powershell.exe' || name === 'conhost.exe';
+}
+
+function normalizeWindowsProcess(proc) {
+  return {
+    processId: Number.isInteger(Number(proc?.processId)) ? Number(proc.processId) : null,
+    parentProcessId: Number.isInteger(Number(proc?.parentProcessId)) ? Number(proc.parentProcessId) : null,
+    name: String(proc?.name || ''),
+    commandLine: String(proc?.commandLine || ''),
+  };
+}
+
+function looksLikeCopilotWorkerProcess(proc) {
+  const name = String(proc?.name || '').trim().toLowerCase();
+  const cmd = String(proc?.commandLine || '').trim().toLowerCase();
+  if (!name && !cmd) return false;
+  if (cmd.includes('\\server\\server.js') || cmd.includes('/server/server.js')) return false;
+  // A tmux process is never a worker. The shared tmux server keeps the argv of
+  // whichever `tmux new-session -d -s <session-id> ...` first started it, so a
+  // session-id scan would otherwise match the server itself — and killing it
+  // tears down every tmux-hosted worker on the socket, not just the target
+  // session. (The server's comm is "tmux: server", which the ps parser splits
+  // into name "tmux:" with the command line shifted to start with "server".)
+  if (name === 'tmux' || name.startsWith('tmux:')) return false;
+  if (/^(?:server\s+)?tmux(?:\s|$)/.test(cmd)) return false;
+  if (name === 'copilot.exe') return true;
+  if (name === 'gh.exe' && cmd.includes('gh') && cmd.includes('copilot')) return true;
+  if (cmd.includes('gh copilot')) return true;
+  // Every node worker's entry script is named `<kind>-session-worker.mjs` and
+  // is invoked as `node <script> --session-id <id>` — none of the CLI markers
+  // below (no `--allow-all`, no `@github/copilot` path) appear on their command
+  // lines, so a worker missing from this check is invisible to discovery: the
+  // kill route no-ops and process reuse spawns a duplicate every turn. That is
+  // exactly what happened to `grok-session-worker`, which the per-worker list
+  // this replaces never named.
+  //
+  // Matching the naming convention instead of four literals means a new node
+  // worker is discoverable the moment it exists. The tmux exclusions above
+  // still run first, so the shared tmux server cannot be adopted through this
+  // arm by carrying a worker's argv.
+  if (cmd.includes('-session-worker')) return true;
+  return cmd.includes('copilot.cmd')
+    || cmd.includes('copilot-win32')
+    || cmd.includes('@github\\copilot')
+    || cmd.includes('@aykahshi/copilot-mcp-server')
+    || cmd.includes('--allow-all')
+    || cmd.includes('--resume');
+}
+
+export function createSessionWorkerProcessInspector({
+  platform = process.platform,
+  execFileSyncImpl = execFileSync,
+} = {}) {
+  function getPosixProcessSnapshot() {
+    if (platform === 'win32') return [];
+    const output = execFileSyncImpl('ps', ['-eo', 'pid=,ppid=,comm=,args=', '-ww'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const text = String(output || '').trim();
+    if (!text) return [];
+    return text
+      .split(/\r?\n/)
+      .map((line) => {
+        const match = String(line || '').match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
+        if (!match) return null;
+        return {
+          processId: Number.parseInt(match[1], 10),
+          parentProcessId: Number.parseInt(match[2], 10),
+          name: String(match[3] || ''),
+          commandLine: String(match[4] || ''),
+        };
+      })
+      .filter(Boolean);
+  }
+
+  function getWindowsProcessSnapshot() {
+    if (platform !== 'win32') return [];
+    const script = [
+      '$list = Get-CimInstance Win32_Process | ForEach-Object {',
+      '  [pscustomobject]@{',
+      '    processId = [int]$_.ProcessId;',
+      '    parentProcessId = [int]$_.ParentProcessId;',
+      '    name = [string]$_.Name;',
+      '    commandLine = [string]$_.CommandLine;',
+      '  }',
+      '};',
+      '$list | ConvertTo-Json -Depth 3 -Compress',
+    ].join(' ');
+    const output = execFileSyncImpl('powershell.exe', ['-NoProfile', '-Command', script], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const text = String(output || '').trim();
+    if (!text) return [];
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : [parsed];
+  }
+
+  function isWindowsSessionMatch(proc, target, targetPattern) {
+    if (!proc?.processId) return false;
+    if (!looksLikeCopilotWorkerProcess(proc)) return false;
+    const parsedSessionId = parseSessionIdFromCommandLine(proc.commandLine);
+    if (parsedSessionId) return parsedSessionId === target;
+    return Boolean(targetPattern?.test(proc.commandLine));
+  }
+
+  function findWindowsProcessesForSession(targetSessionId) {
+    const target = normalizeSessionId(targetSessionId);
+    if (platform !== 'win32' || !target) return [];
+    const targetPattern = buildSessionArgPattern(target, { includeResume: false });
+    return getWindowsProcessSnapshot()
+      .map(normalizeWindowsProcess)
+      .filter((proc) => proc.processId)
+      .filter((proc) => isWindowsSessionMatch(proc, target, targetPattern))
+      .sort((left, right) => {
+        const scoreDelta = scoreWindowsWorkerCandidate(right) - scoreWindowsWorkerCandidate(left);
+        if (scoreDelta !== 0) return scoreDelta;
+        return Number(right.processId || 0) - Number(left.processId || 0);
+      });
+  }
+
+  function findWindowsProcessForSession(targetSessionId) {
+    const candidates = findWindowsProcessesForSession(targetSessionId);
+    return candidates.find((proc) => !isWindowsWrapperProcess(proc)) || null;
+  }
+
+  function findWindowsProcessTreeForSession(targetSessionId) {
+    const target = normalizeSessionId(targetSessionId);
+    if (platform !== 'win32' || !target) return [];
+    const targetPattern = buildSessionArgPattern(target, { includeResume: false });
+    const snapshot = getWindowsProcessSnapshot()
+      .map(normalizeWindowsProcess)
+      .filter((proc) => proc.processId);
+    const byPid = new Map(snapshot.map((proc) => [proc.processId, proc]));
+    const childrenByParent = new Map();
+    for (const proc of snapshot) {
+      if (!proc.parentProcessId) continue;
+      const children = childrenByParent.get(proc.parentProcessId) || [];
+      children.push(proc);
+      childrenByParent.set(proc.parentProcessId, children);
+    }
+
+    const related = new Map();
+    const addProcess = (proc) => {
+      if (proc?.processId) related.set(proc.processId, proc);
+    };
+    const addDescendants = (pid) => {
+      for (const child of childrenByParent.get(pid) || []) {
+        if (related.has(child.processId)) continue;
+        addProcess(child);
+        addDescendants(child.processId);
+      }
+    };
+    const addWrapperAncestors = (proc) => {
+      let current = proc;
+      const seen = new Set();
+      while (current?.parentProcessId && !seen.has(current.parentProcessId)) {
+        seen.add(current.parentProcessId);
+        const parent = byPid.get(current.parentProcessId);
+        if (!parent || !isWindowsWrapperProcess(parent)) return;
+        addProcess(parent);
+        current = parent;
+      }
+    };
+
+    for (const proc of snapshot.filter((candidate) => isWindowsSessionMatch(candidate, target, targetPattern))) {
+      addProcess(proc);
+      addDescendants(proc.processId);
+      addWrapperAncestors(proc);
+    }
+
+    return Array.from(related.values()).sort((left, right) => {
+      const scoreDelta = scoreWindowsWorkerCandidate(right) - scoreWindowsWorkerCandidate(left);
+      if (scoreDelta !== 0) return scoreDelta;
+      return Number(right.processId || 0) - Number(left.processId || 0);
+    });
+  }
+
+  function findPosixProcessesForSession(targetSessionId) {
+    const target = normalizeSessionId(targetSessionId);
+    if (platform === 'win32' || !target) return [];
+    const targetPattern = buildSessionArgPattern(target, { includeResume: true });
+    return getPosixProcessSnapshot()
+      .map((proc) => ({
+        processId: Number.isInteger(Number(proc?.processId)) ? Number(proc.processId) : null,
+        parentProcessId: Number.isInteger(Number(proc?.parentProcessId)) ? Number(proc.parentProcessId) : null,
+        name: String(proc?.name || ''),
+        commandLine: String(proc?.commandLine || ''),
+      }))
+      .filter((proc) => proc.processId)
+      .filter((proc) => looksLikeCopilotWorkerProcess(proc))
+      .filter((proc) => {
+        const parsedSessionId = parseSessionIdFromCommandLine(proc.commandLine);
+        if (parsedSessionId) return parsedSessionId === target;
+        return targetPattern?.test(proc.commandLine);
+      });
+  }
+
+  function findPosixProcessForSession(targetSessionId) {
+    return findPosixProcessesForSession(targetSessionId)[0] || null;
+  }
+
+  function parsePositiveInt(value) {
+    const num = Number.parseInt(String(value || ''), 10);
+    return Number.isInteger(num) && num > 0 ? num : null;
+  }
+
+  function stopWindowsPids(pids) {
+    const ids = Array.from(new Set(
+      (Array.isArray(pids) ? pids : [pids])
+        .map((value) => parsePositiveInt(value))
+        .filter(Boolean),
+    ));
+    if (!ids.length) return [];
+    const script = [
+      '$ErrorActionPreference = "Continue"',
+      '$ids = @(' + ids.join(',') + ')',
+      'try {',
+      '  $snapshot = @(Get-CimInstance Win32_Process -ErrorAction Stop | ForEach-Object { [pscustomobject]@{ processId = [int]$_.ProcessId; parentProcessId = [int]$_.ParentProcessId } })',
+      '} catch {',
+      '  Write-Error $_',
+      '  exit 2',
+      '}',
+      '$targets = [System.Collections.Generic.HashSet[int]]::new()',
+      'foreach ($id in $ids) { [void]$targets.Add([int]$id) }',
+      '$changed = $true',
+      'while ($changed) {',
+      '  $changed = $false',
+      '  foreach ($proc in $snapshot) {',
+      '    if ($targets.Contains([int]$proc.parentProcessId) -and -not $targets.Contains([int]$proc.processId)) {',
+      '      [void]$targets.Add([int]$proc.processId)',
+      '      $changed = $true',
+      '    }',
+      '  }',
+      '}',
+      '$ordered = @($snapshot | Where-Object { $targets.Contains([int]$_.processId) } | Sort-Object parentProcessId -Descending | ForEach-Object { [int]$_.processId })',
+      '$seen = [System.Collections.Generic.HashSet[int]]::new()',
+      '$ids = @($ordered + $ids | Where-Object { $seen.Add([int]$_) })',
+      'foreach ($id in $ids) {',
+      '  try { Stop-Process -Id $id -Force -ErrorAction SilentlyContinue } catch {}',
+      '}',
+      'exit 0',
+    ].join('; ');
+    execFileSyncImpl('powershell.exe', ['-NoProfile', '-Command', script], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return ids;
+  }
+
+  function findProcessesForSession(targetSessionId) {
+    return platform === 'win32'
+      ? findWindowsProcessesForSession(targetSessionId)
+      : findPosixProcessesForSession(targetSessionId);
+  }
+
+  function findProcessForSession(targetSessionId) {
+    return platform === 'win32'
+      ? findWindowsProcessForSession(targetSessionId)
+      : findPosixProcessForSession(targetSessionId);
+  }
+
+  return {
+    normalizeSessionId,
+    parseSessionIdFromCommandLine,
+    findProcessForSession,
+    findProcessesForSession,
+    findPosixProcessForSession,
+    findPosixProcessesForSession,
+    getPosixProcessSnapshot,
+    findWindowsProcessesForSession,
+    findWindowsProcessForSession,
+    findWindowsProcessTreeForSession,
+    getWindowsProcessSnapshot,
+    stopWindowsPids,
+  };
+}

package/server/services/session-worker-registry-service.mjs

@@ -0,0 +1,194 @@
+'use strict';
+
+function normalizeSessionId(value) {
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+function normalizeWorkerId(value) {
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+function normalizeConversationId(value) {
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+function normalizeRuntimeSessionId(value) {
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+function toNonNegativeInt(value, fallback = 0) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(0, Math.trunc(n));
+}
+
+function toPositivePid(value) {
+  if (value === null || value === undefined || value === '') return null;
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value) || value <= 0) return null;
+    return value;
+  }
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) return null;
+  const parsed = Number(text);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function normalizeTimestamp(value, fallbackIso) {
+  const text = String(value || '').trim();
+  if (!text) return fallbackIso;
+  const parsed = new Date(text);
+  if (Number.isNaN(parsed.getTime())) return fallbackIso;
+  return parsed.toISOString();
+}
+
+const STATUS_ALIASES = Object.freeze({
+  idle: 'ready',
+  queued: 'processing',
+  failed: 'error',
+});
+
+const ALLOWED_STATUSES = new Set(['new', 'starting', 'ready', 'processing', 'error', 'stopped']);
+
+function normalizeStatus(value) {
+  const normalized = String(value || 'new').trim().toLowerCase();
+  const mapped = STATUS_ALIASES[normalized] || normalized || 'new';
+  return ALLOWED_STATUSES.has(mapped) ? mapped : 'new';
+}
+
+function sanitizeState(raw = null) {
+  const nowIso = new Date().toISOString();
+  const base = raw && typeof raw === 'object' ? raw : {};
+  const createdAt = normalizeTimestamp(base.createdAt, nowIso);
+  return {
+    workerId: normalizeWorkerId(base.workerId),
+    conversationId: normalizeConversationId(base.conversationId),
+    runtimeSessionId: normalizeRuntimeSessionId(base.runtimeSessionId),
+    sdkSessionId: normalizeSessionId(base.sdkSessionId),
+    status: normalizeStatus(base.status),
+    pid: toPositivePid(base.pid),
+    queueDepth: toNonNegativeInt(base.queueDepth, 0),
+    retryCount: toNonNegativeInt(base.retryCount, 0),
+    lastError: String(base.lastError || '').trim() || null,
+    updatedAt: normalizeTimestamp(base.updatedAt, nowIso),
+    createdAt,
+  };
+}
+
+function toSnapshot(entry) {
+  return Object.freeze({ ...entry });
+}
+
+export function createSessionWorkerRegistry() {
+  const bySession = new Map();
+  const sessionByWorkerId = new Map();
+  const sessionByConversationId = new Map();
+  const sessionByRuntimeSessionId = new Map();
+
+  function clearIndexesForSession(entry) {
+    if (!entry) return;
+    if (entry.workerId) sessionByWorkerId.delete(entry.workerId);
+    if (entry.conversationId) sessionByConversationId.delete(entry.conversationId);
+    if (entry.runtimeSessionId) sessionByRuntimeSessionId.delete(entry.runtimeSessionId);
+  }
+
+  function updateIndexesForSession(entry) {
+    if (!entry) return;
+    if (entry.workerId) sessionByWorkerId.set(entry.workerId, entry.sdkSessionId);
+    if (entry.conversationId) sessionByConversationId.set(entry.conversationId, entry.sdkSessionId);
+    if (entry.runtimeSessionId) sessionByRuntimeSessionId.set(entry.runtimeSessionId, entry.sdkSessionId);
+  }
+
+  function getWorker(sdkSessionId) {
+    const sessionId = normalizeSessionId(sdkSessionId);
+    if (!sessionId) return null;
+    const entry = bySession.get(sessionId);
+    return entry ? toSnapshot(entry) : null;
+  }
+
+  function getWorkerByWorkerId(workerId) {
+    const normalized = normalizeWorkerId(workerId);
+    if (!normalized) return null;
+    const sessionId = sessionByWorkerId.get(normalized);
+    if (!sessionId) return null;
+    return getWorker(sessionId);
+  }
+
+  function getWorkerByConversationId(conversationId) {
+    const normalized = normalizeConversationId(conversationId);
+    if (!normalized) return null;
+    const sessionId = sessionByConversationId.get(normalized);
+    if (!sessionId) return null;
+    return getWorker(sessionId);
+  }
+
+  function getWorkerByRuntimeSessionId(runtimeSessionId) {
+    const normalized = normalizeRuntimeSessionId(runtimeSessionId);
+    if (!normalized) return null;
+    const sessionId = sessionByRuntimeSessionId.get(normalized);
+    if (!sessionId) return null;
+    return getWorker(sessionId);
+  }
+
+  function listWorkers() {
+    return Object.freeze(Array.from(bySession.values()).map((entry) => toSnapshot(entry)));
+  }
+
+  function upsertWorker(rawState = {}) {
+    if (!rawState || typeof rawState !== 'object' || Array.isArray(rawState)) {
+      throw new TypeError('upsertWorker requires a state object');
+    }
+    const state = sanitizeState(rawState);
+    if (!state.sdkSessionId) {
+      throw new Error('upsertWorker requires sdkSessionId');
+    }
+    const existing = bySession.get(state.sdkSessionId);
+    const next = sanitizeState({
+      ...(existing || {}),
+      ...state,
+      sdkSessionId: state.sdkSessionId,
+      createdAt: existing?.createdAt || state.createdAt,
+      updatedAt: new Date().toISOString(),
+    });
+    clearIndexesForSession(existing);
+    bySession.set(state.sdkSessionId, next);
+    updateIndexesForSession(next);
+    return toSnapshot(next);
+  }
+
+  function removeWorker(sdkSessionId) {
+    const sessionId = normalizeSessionId(sdkSessionId);
+    if (!sessionId) return false;
+    const existing = bySession.get(sessionId);
+    if (!existing) return false;
+    clearIndexesForSession(existing);
+    return bySession.delete(sessionId);
+  }
+
+  function clearAll() {
+    bySession.clear();
+    sessionByWorkerId.clear();
+    sessionByConversationId.clear();
+    sessionByRuntimeSessionId.clear();
+  }
+
+  return {
+    normalizeSessionId,
+    normalizeWorkerId,
+    normalizeConversationId,
+    normalizeRuntimeSessionId,
+    getWorker,
+    getWorkerByWorkerId,
+    getWorkerByConversationId,
+    getWorkerByRuntimeSessionId,
+    listWorkers,
+    upsertWorker,
+    removeWorker,
+    clearAll,
+  };
+}
+

package/server/services/session-worker-stop-service.mjs

@@ -0,0 +1,141 @@
+// ---------------------------------------------------------------------------
+// Deterministic session-worker stop
+//
+// Kills every process belonging to a session and then *verifies* it is gone,
+// escalating once if the graceful pass did not take. Callers must be able to
+// distinguish "the old CLI is definitely dead" from "we asked it to die" —
+// relaunching into a still-live process is how a session ends up with two CLIs,
+// or with one CLI silently still in the old working directory.
+//
+// Never throws: the caller decides what a timeout means.
+// ---------------------------------------------------------------------------
+
+const DEFAULT_GRACEFUL_TIMEOUT_MS = 3_000;
+const DEFAULT_ESCALATION_TIMEOUT_MS = 2_000;
+const DEFAULT_POLL_INTERVAL_MS = 50;
+
+function toPidList(rows, extraPid) {
+  const fromRows = (Array.isArray(rows) ? rows : []).map((row) => Number(row?.processId));
+  return [...new Set([...fromRows, Number(extraPid)])]
+    .filter((pid) => Number.isInteger(pid) && pid > 0);
+}
+
+function enumeratePids({ sdkSessionId, worker, processInspector, platform }) {
+  const rows = platform === 'win32'
+    ? (
+      processInspector?.findWindowsProcessTreeForSession?.(sdkSessionId)
+      || processInspector?.findWindowsProcessesForSession?.(sdkSessionId)
+      || processInspector?.findProcessesForSession?.(sdkSessionId)
+      || []
+    )
+    : (processInspector?.findProcessesForSession?.(sdkSessionId) || []);
+  return toPidList(rows, worker?.pid);
+}
+
+export async function stopSessionWorkerProcesses({
+  sdkSessionId,
+  worker = null,
+  processInspector = null,
+  platform = process.platform,
+  killImpl = (pid, signal) => process.kill(pid, signal),
+  isPidAliveImpl = () => false,
+  killTmuxSessionImpl = null,
+  sleepImpl = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  nowMs = Date.now,
+  gracefulTimeoutMs = DEFAULT_GRACEFUL_TIMEOUT_MS,
+  escalationTimeoutMs = DEFAULT_ESCALATION_TIMEOUT_MS,
+  pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+} = {}) {
+  const sid = String(sdkSessionId || '').trim();
+  const startedAt = nowMs();
+  const done = (extra) => ({
+    ok: true,
+    pids: [],
+    remainingPids: [],
+    escalated: false,
+    timedOut: false,
+    durationMs: nowMs() - startedAt,
+    error: null,
+    ...extra,
+  });
+
+  if (!sid) return done({ ok: false, error: 'Missing session id' });
+
+  const pids = enumeratePids({ sdkSessionId: sid, worker, processInspector, platform });
+  if (!pids.length) return done({ pids: [] });
+
+  const survivors = (list) => list.filter((pid) => isPidAliveImpl(pid));
+
+  const waitFor = async (list, timeoutMs) => {
+    const deadline = nowMs() + Math.max(0, Number(timeoutMs) || 0);
+    let remaining = survivors(list);
+    while (remaining.length && nowMs() < deadline) {
+      await sleepImpl(pollIntervalMs);
+      remaining = survivors(list);
+    }
+    return remaining;
+  };
+
+  try {
+    if (platform === 'win32') {
+      // stopWindowsPids already walks the descendant tree leaf-first and uses
+      // Stop-Process -Force, so there is no gentler first pass to attempt.
+      processInspector?.stopWindowsPids?.(pids);
+    } else {
+      for (const pid of pids) {
+        try {
+          killImpl(pid, 'SIGTERM');
+        } catch (error) {
+          if (String(error?.code || '') !== 'ESRCH') throw error;
+        }
+      }
+      // The tmux session can outlive its child after SIGTERM.
+      killTmuxSessionImpl?.(sid);
+    }
+  } catch (error) {
+    return done({ ok: false, pids, remainingPids: survivors(pids), error: error?.message || 'Failed to stop the CLI' });
+  }
+
+  let remainingPids = await waitFor(pids, gracefulTimeoutMs);
+  if (!remainingPids.length) return done({ pids });
+
+  // Escalate once.
+  let escalationTargets = remainingPids;
+  try {
+    if (platform === 'win32') {
+      // Re-enumerate: children spawned after the first snapshot are invisible to it.
+      const rediscovered = enumeratePids({ sdkSessionId: sid, worker, processInspector, platform });
+      escalationTargets = [...new Set([...remainingPids, ...rediscovered.filter((pid) => isPidAliveImpl(pid))])];
+      processInspector?.stopWindowsPids?.(escalationTargets);
+    } else {
+      for (const pid of escalationTargets) {
+        try {
+          killImpl(pid, 'SIGKILL');
+        } catch (error) {
+          if (String(error?.code || '') !== 'ESRCH') throw error;
+        }
+      }
+    }
+  } catch (error) {
+    return done({
+      ok: false,
+      pids,
+      remainingPids: survivors(escalationTargets),
+      escalated: true,
+      error: error?.message || 'Failed to force-stop the CLI',
+    });
+  }
+
+  remainingPids = await waitFor(escalationTargets, escalationTimeoutMs);
+  if (remainingPids.length) {
+    return done({
+      ok: false,
+      pids,
+      remainingPids,
+      escalated: true,
+      timedOut: true,
+      error: `worker-stop-timeout:${remainingPids.join(',')}`,
+    });
+  }
+  return done({ pids, escalated: true });
+}