@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{process-utils.js → processes/process-utils.js}

@@ -1,30 +1,66 @@
 /**
- * engine/process-utils.js — Cross-platform process-management helpers
+ * engine/processes/process-utils.js — Cross-platform process-management helpers
  * (kill trees, PID liveness, CPU sampling, process-table enumeration, cwd
  * holder detection, descendant/reachability BFS).
  *
- * Extracted from engine/shared.js (P-mrb8yg9x001k1401-b) — a self-contained
+ * Extracted from engine/core/shared.js (P-mrb8yg9x001k1401-b) — a self-contained
  * slice with no dependency on the rest of shared.js's state/JSON machinery.
  * shared.js re-exports these names so no caller needs to change its
- * `require('./shared')` call. Where a function needs MINIONS_DIR /
- * ENGINE_DEFAULTS from shared.js, it lazily `require('./shared')`s inside
+ * `require('../core/shared')` call. Where a function needs MINIONS_DIR /
+ * ENGINE_DEFAULTS from shared.js, it lazily `require('../core/shared')`s inside
  * the function body (not at module top-level) to avoid a load-time
  * circular-require deadlock with shared.js requiring this module back.
  */
 
 const fs = require('fs');
 const path = require('path');
-const { execSync: _execSync, execFile: _execFile } = require('child_process');
+const { execSync: _execSync, execFile: _execFile, spawnSync: _spawnSync } = require('child_process');
+
+// W-ms6dmv99005o26f4 — tri-state PID liveness.
+//
+// `process.kill(pid, 0)` has THREE outcomes, not two:
+//   - no throw  → the signal was deliverable; the process exists.
+//   - ESRCH     → the kernel found no such process; genuine, conclusive absence.
+//   - EPERM     → the kernel FOUND the process and refused the signal. This is
+//                 positive evidence of existence, and every helper here used to
+//                 report it as death.
+//   - anything else (EINVAL, EACCES on exotic platforms, a thrown validate error
+//                 from a caller-supplied probe) → we learned nothing.
+//
+// Collapsing all four into `false` is the third link of the 2026-07-29T17:44Z
+// false-orphan storm: in engine/cli.js a `false` here zeroes `agentPid`, which is
+// exactly the `hadPid && !agentPid` condition that flags a dispatch confirmed-dead
+// at restart — bypassing both minAliveBeforeOrphanMs and the engine-restart grace
+// window, so the dispatch is orphaned on the next tick after a few seconds of
+// silence with failure_class `engine-restart`.
+//
+// `conclusive` lets destructive callers require proof before acting; the boolean
+// facades below keep their historical "false == not known to be alive" contract
+// for non-destructive callers.
+function inspectPidLiveness(pid, opts = {}) {
+  const value = Number(pid);
+  if (!Number.isInteger(value) || value <= 0) {
+    return { alive: false, conclusive: true, reason: 'invalid-pid' };
+  }
+  const kill = typeof opts.kill === 'function' ? opts.kill : process.kill.bind(process);
+  try {
+    kill(value, 0);
+    return { alive: true, conclusive: true, reason: 'signalled' };
+  } catch (err) {
+    const code = String(err && err.code || '');
+    if (code === 'ESRCH') return { alive: false, conclusive: true, reason: 'esrch' };
+    if (code === 'EPERM') return { alive: true, conclusive: true, reason: 'eperm' };
+    return { alive: false, conclusive: false, reason: code ? code.toLowerCase() : 'probe-failed' };
+  }
+}
 
 // Shared.js-local PID liveness check, moved here unchanged. Avoids a circular
-// require on engine/cli.js (which has its own isPidAlive) and engine/timeout.js
+// require on engine/operations/cli.js (which has its own isPidAlive) and engine/orchestration/timeout.js
 // (which has isOsPidAliveForDispatch — but that one looks up pid from a
 // side-channel pid-file, whereas callers that already have the pid in-hand
 // use this simple check).
-function isPidAlive(pid) {
-  if (!Number.isFinite(pid) || pid <= 0) return false;
-  try { process.kill(pid, 0); return true; }
-  catch { return false; }
+function isPidAlive(pid, opts = {}) {
+  return inspectPidLiveness(pid, opts).alive;
 }
 
 // ─── Cross-Platform Process Kill Helpers ─────────────────────────────────────
@@ -61,9 +97,9 @@ function unrefTimer(timer) {
   return timer;
 }
 
-function killGracefully(proc, graceMs = 5000) {
+function _killGracefully(proc, graceMs = 5000) {
   const pid = normalizeKillPid(proc);
-  if (!pid) return;
+  if (!pid) return false;
   if (process.platform === 'win32') {
     try { _execSync(`taskkill /PID ${pid} /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
     unrefTimer(setTimeout(() => {
@@ -75,9 +111,10 @@ function killGracefully(proc, graceMs = 5000) {
       killUnixProcessTree(pid, 'SIGKILL');
     }, graceMs));
   }
+  return true;
 }
 
-function killImmediate(proc) {
+function _killImmediate(proc) {
   const pid = normalizeKillPid(proc);
   if (!pid) return false;
   if (process.platform === 'win32') {
@@ -91,12 +128,183 @@ function killImmediate(proc) {
   return killUnixProcessTree(pid, 'SIGKILL');
 }
 
+// Kill one process without walking its descendants. Daemon replacement uses
+// this because detached agents and managed services intentionally outlive the
+// engine/dashboard process that launched them.
+function _killProcessOnly(proc) {
+  const pid = normalizeKillPid(proc);
+  if (!pid) return false;
+  if (process.platform === 'win32') {
+    try {
+      _execSync(`taskkill /PID ${pid} /F`, { stdio: 'pipe', timeout: 3000, windowsHide: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  try {
+    process.kill(pid, 'SIGKILL');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function _normalizeProcessScriptPath(value, platform = process.platform) {
+  const normalized = String(value || '').replace(/\\/g, '/');
+  return platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+// `path.basename` binds to the HOST platform, but the helpers below are told
+// which platform's process table they are parsing. Parsing a Windows path with
+// POSIX semantics keeps the backslashes (breaking Windows enumeration from a
+// Linux/macOS engine), and parsing a POSIX path with Windows semantics splits on
+// a backslash that is a legal POSIX filename character. Always pick the flavour
+// that matches the platform being enumerated. Call sites that have already run
+// the raw value through `_normalizeProcessScriptPath` are separator-agnostic
+// today, but they route through here too so the rule holds if that normalization
+// ever stops collapsing backslashes.
+function _processPathFlavor(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+function _tokenizeProcessCommandLine(commandLine) {
+  const tokens = [];
+  let current = '';
+  let quoted = false;
+  for (const char of String(commandLine || '')) {
+    if (char === '"') {
+      quoted = !quoted;
+    } else if (!quoted && /\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+    } else {
+      current += char;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function commandLineRunsScript(commandLine, scriptPath, platform = process.platform) {
+  const target = _normalizeProcessScriptPath(scriptPath, platform);
+  if (!target) return false;
+  const tokens = _tokenizeProcessCommandLine(commandLine);
+  const executable = _processPathFlavor(platform)
+    .basename(_normalizeProcessScriptPath(tokens[0], platform))
+    .toLowerCase();
+  if (executable !== 'node' && executable !== 'node.exe' && executable !== 'nodejs') return false;
+  const windows = platform === 'win32';
+  const isEngine = target === 'engine.js' || target.endsWith('/engine.js');
+  for (let i = 1; i < tokens.length; i++) {
+    const token = _normalizeProcessScriptPath(tokens[i], platform);
+    if (!token.endsWith('.js')) continue;
+    if (token !== target) {
+      if (windows) return false;
+      break;
+    }
+    if (!isEngine) return true;
+    return _normalizeProcessScriptPath(tokens[i + 1], platform) === 'start';
+  }
+  // `ps` flattens argv, so an unquoted POSIX path containing spaces cannot be
+  // reconstructed by tokenization. Match the exact path in the raw command
+  // only when no earlier JavaScript entrypoint exists.
+  if (!windows) {
+    const command = String(commandLine || '').replace(/\\/g, '/');
+    let offset = 0;
+    while (offset < command.length) {
+      const index = command.indexOf(target, offset);
+      if (index < 0) break;
+      const end = index + target.length;
+      const leftBoundary = index === 0 || /\s|["']/.test(command[index - 1]);
+      const rightBoundary = end === command.length || /\s|["']/.test(command[end]);
+      if (leftBoundary && rightBoundary) {
+        const prefix = command.slice(0, index);
+        if (!/\.js(?:\s|["']|$)/.test(prefix)) {
+          const suffix = command.slice(end).replace(/^["']/, '').trimStart();
+          return isEngine ? /^start(?:\s|$)/.test(suffix) : true;
+        }
+      }
+      offset = index + 1;
+    }
+  }
+  return false;
+}
+
+// Return Node PIDs whose executable script token exactly matches any requested
+// path. Enumeration failures fail open: leaking a daemon is safer than killing
+// an unrelated process from another checkout.
+function listNodePidsMatchingScripts(scriptPaths, {
+  platform = process.platform,
+  spawnSync = _spawnSync,
+  execSync = _execSync,
+} = {}) {
+  const targets = [...new Set((scriptPaths || []).map(value => String(value || '')).filter(Boolean))];
+  if (targets.length === 0) return [];
+  const flavor = _processPathFlavor(platform);
+  const basenames = [...new Set(targets.map(target => flavor.basename(target)))];
+  if (basenames.some(base => !/^[A-Za-z0-9._-]+$/.test(base))) return [];
+  let output = '';
+  try {
+    if (platform === 'win32') {
+      const commandLineFilter = basenames
+        .map(base => `CommandLine LIKE '%${base.replace(/'/g, "''")}%'`)
+        .join(' OR ');
+      const ps = `Get-CimInstance Win32_Process -Filter "name='node.exe' AND (${commandLineFilter})" | `
+        + 'ForEach-Object { "$($_.ProcessId)|$($_.CommandLine)" }';
+      const result = spawnSync('powershell', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-EncodedCommand',
+        Buffer.from(ps, 'utf16le').toString('base64'),
+      ], {
+        encoding: 'utf8',
+        timeout: 8000,
+        windowsHide: true,
+        maxBuffer: 8 * 1024 * 1024,
+      });
+      if (result.error || result.status !== 0) return [];
+      output = String(result.stdout || '');
+    } else {
+      for (const base of basenames) {
+        try {
+          output += String(execSync(`ps -eo pid=,args= | grep -F -- '${base}'`, {
+            encoding: 'utf8',
+            timeout: 8000,
+            windowsHide: true,
+            maxBuffer: 8 * 1024 * 1024,
+          }) || '');
+        } catch { /* grep exit 1 means no candidate rows */ }
+      }
+    }
+  } catch {
+    return [];
+  }
+
+  const pids = new Set();
+  for (const line of output.split(/\r?\n/)) {
+    const match = platform === 'win32'
+      ? line.trim().match(/^(\d+)\|(.*)$/)
+      : line.trim().match(/^(\d+)\s+(.*)$/);
+    if (!match || !targets.some(target => commandLineRunsScript(match[2], target, platform))) continue;
+    const pid = Number(match[1]);
+    if (Number.isInteger(pid) && pid > 0) pids.add(pid);
+  }
+  return [...pids];
+}
+
+function listNodePidsMatchingScript(scriptPath, opts) {
+  return listNodePidsMatchingScripts([scriptPath], opts);
+}
+
 // Decide whether a Windows `tasklist /FI "PID eq <pid>" /NH` output proves the
 // pid is alive. A bare `out.includes(String(pid))` can read a DEAD pid as alive
 // on a digit-substring collision — the pid appears inside another column (a
 // larger PID, a memory-KB figure, a session id). Require a word-boundary match
 // (`\b<pid>\b`) and, when an `imageName` is supplied, that the expected process
-// image is present too. Mirrors the hardened check in engine/restart-health.js.
+// image is present too. Mirrors the hardened check in engine/recovery/restart-health.js.
 // Pure (no shell-out) so callers can pass captured output and unit tests can
 // feed crafted samples.
 function tasklistOutputShowsPid(out, pid, { imageName } = {}) {
@@ -160,10 +368,8 @@ function getProcessCpuSeconds(pid) {
   return null;
 }
 
-// Single-PID kill (no /T tree walk) — used by the orphan-MCP sweep where we
-// already enumerated descendants ourselves and the parent is dead, so /T would
-// be a no-op anyway.
-function killByPidImmediate(pid) {
+// Single-PID kill (no tree walk) for identity-verified declarations.
+function _killByPidImmediate(pid) {
   const n = Number(pid);
   if (!Number.isInteger(n) || n <= 0 || n === process.pid) return false;
   if (process.platform === 'win32') {
@@ -176,7 +382,7 @@ function killByPidImmediate(pid) {
 // Batched kill — one OS process for N PIDs. `taskkill` accepts repeated /PID
 // flags natively; on Unix we still loop process.kill, which is in-process and
 // cheap. Returns the count of successful kills.
-function killByPidsImmediate(pids) {
+function _killByPidsImmediate(pids) {
   const valid = (Array.isArray(pids) ? pids : [])
     .map(Number)
     .filter(n => Number.isInteger(n) && n > 0 && n !== process.pid);
@@ -186,7 +392,7 @@ function killByPidsImmediate(pids) {
     try { _execSync(`taskkill /F ${flags}`, { stdio: 'pipe', timeout: 5000, windowsHide: true }); return valid.length; }
     catch {
       let killed = 0;
-      for (const p of valid) { if (killByPidImmediate(p)) killed++; }
+      for (const p of valid) { if (_killByPidImmediate(p)) killed++; }
       return killed;
     }
   }
@@ -203,7 +409,7 @@ function killByPidsImmediate(pids) {
 // an attached child (e.g. managed-spawn's Node launcher shim, P-8a4d6f29): a
 // non-tree kill would reap the shim and orphan/leak the child. Returns the
 // count of pids for which the kill call was issued without throwing.
-function killByPidTreesImmediate(pids) {
+function _killByPidTreesImmediate(pids) {
   const valid = (Array.isArray(pids) ? pids : [])
     .map(Number)
     .filter(n => Number.isInteger(n) && n > 0 && n !== process.pid);
@@ -229,6 +435,184 @@ function killByPidTreesImmediate(pids) {
   return killed;
 }
 
+const PROCESS_TERMINATION_SITES = Object.freeze({
+  'bin.daemon-stop-process': { mode: 'process-only', ownership: 'exact-scripts', description: 'Stop an exact-script Minions daemon without its detached children.' },
+  'bin.daemon-stop-tree': { mode: 'tree-immediate', ownership: 'exact-scripts', description: 'Stop an exact-script daemon and its owned descendants during full shutdown.' },
+  'dashboard.engine-restart': { mode: 'process-only', ownership: 'exact-script', description: 'Restart the engine while preserving detached agents.' },
+  'dashboard.keep-process-manual': { mode: 'pid-immediate', ownership: 'exact-identity', description: 'Operator removes one identity-verified keep-process PID.' },
+  'dashboard.tools-inventory-shutdown': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Dashboard shutdown reaps its tools-inventory child.' },
+  'dashboard.tools-inventory-watchdog': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Tools-inventory child exceeded its watchdog.' },
+  'engine.acp-worker-close': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Close an owned ACP worker and descendants.' },
+  'engine.acp-worker-root-close': { mode: 'process-only', ownership: 'child-handle', description: 'Close only an ACP worker root while preserving declared descendants.' },
+  'engine.cleanup.stale-agent-pid': { mode: 'tree-immediate', ownership: 'recorded-agent', description: 'Reap an identity-verified stale agent PID file.' },
+  'engine.cli.kill-command': { mode: 'tree-immediate', ownership: 'recorded-agent', description: 'Explicit CLI kill of an identity-verified agent PID.' },
+  'engine.cli.shutdown-pooled': { mode: 'facade-cancel', ownership: 'facade', description: 'Graceful engine shutdown cancels an active pooled turn.' },
+  'engine.cli.unsafe-reattach': { mode: 'tree-immediate', ownership: 'recorded-agent', description: 'Reject an identity-verified agent running from an unsafe execution path.' },
+  'engine.dispatch.cancel': { mode: 'tree-graceful', ownership: 'recorded-agent', description: 'Explicitly cancel an identity-verified cold dispatch.' },
+  'engine.git-status-probe-cleanup': { mode: 'pids-immediate', ownership: 'exact-identities', description: 'Reap git probes proven to target one owned worktree.' },
+  'engine.keep-process.ttl': { mode: 'pid-immediate', ownership: 'declared-process', description: 'Expire a keep-process PID whose identity predates its declaration.' },
+  'engine.lifecycle.hook-buffer-limit': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Post-completion hook exceeded its output bound.' },
+  'engine.lifecycle.hook-timeout-force': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Post-completion hook ignored graceful timeout.' },
+  'engine.lifecycle.hook-timeout-graceful': { mode: 'tree-graceful', ownership: 'child-handle', description: 'Post-completion hook exceeded its timeout.' },
+  'engine.llm.abort': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Abort an owned direct LLM child.' },
+  'engine.llm.timeout': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Owned direct LLM child exceeded its timeout.' },
+  'engine.managed-launcher.self-signal': { mode: 'self-signal', ownership: 'self', description: 'Managed launcher forwards a termination signal to itself.' },
+  'engine.managed-spawn.reap-failed': { mode: 'tree-immediate', ownership: 'exact-identity', description: 'A newly spawned managed runtime failed acceptance.' },
+  'engine.managed-spawn.remove': { mode: 'tree-immediate', ownership: 'exact-identity', description: 'Remove an identity-verified managed process tree.' },
+  'engine.pooled-agent.descendants': { mode: 'pids-immediate', ownership: 'exact-identities', description: 'Reap descendants proven to belong to one pooled session.' },
+  'engine.query.git-probe-timeout': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Git probe child exceeded its watchdog.' },
+  'engine.spawn-agent.descendants': { mode: 'pids-immediate', ownership: 'exact-identities', description: 'Spawn wrapper reaps its snapshotted runtime descendants.' },
+  'engine.spawn-agent.stdin-failure': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Runtime child could not receive its startup prompt.' },
+  'engine.spawn-partial-failure': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Agent setup failed after creating a cold child.' },
+  'engine.spawn-partial-pooled': { mode: 'facade-cancel', ownership: 'facade', description: 'Agent setup failed after acquiring a pooled turn.' },
+  'engine.spawn-phase.stall': { mode: 'tree-immediate', ownership: 'tracked-process', description: 'Tracked cold runtime remained wedged in startup.' },
+  'engine.spawn-phase.stall-pooled': { mode: 'facade-cancel', ownership: 'facade', description: 'Tracked pooled turn remained wedged in startup.' },
+  'engine.supervisor.daemon-replace': { mode: 'process-only', ownership: 'exact-script', description: 'Supervisor replaces an exact-script daemon without descendants.' },
+  'engine.timeout.tracked-cold': { mode: 'tree-immediate', ownership: 'tracked-process', description: 'Timeout, steering, or removed-dispatch cleanup stops a tracked cold runtime.' },
+  'engine.timeout.tracked-cold-escalation': { mode: 'tree-immediate', ownership: 'tracked-process', description: 'Steering escalation force-stops a tracked cold runtime.' },
+  'engine.timeout.tracked-cold-graceful': { mode: 'tree-graceful', ownership: 'tracked-process', description: 'Tracked cold runtime receives graceful timeout termination.' },
+  'engine.timeout.tracked-pooled': { mode: 'facade-cancel', ownership: 'facade', description: 'Timeout or steering cancels a pooled turn without killing its worker.' },
+  'engine.worktree-gc.orphan-holder': { mode: 'tree-immediate', ownership: 'exact-identity', description: 'Reap an aged process proven to hold an owned orphan worktree.' },
+  'test.helper-child-watchdog': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Shared test helper reaps a child that exceeded its watchdog.' },
+  'test.process-descendants': { mode: 'pids-immediate', ownership: 'exact-identities', description: 'Test harness reaps descendants of its own worker process.' },
+  'test.unit-worker-timeout': { mode: 'tree-immediate', ownership: 'child-handle', description: 'Parallel unit runner reaps a timed-out worker tree.' },
+  'compat.tree-graceful': { mode: 'tree-graceful', ownership: 'compatibility', description: 'Legacy public helper; production call sites are forbidden.' },
+  'compat.tree-immediate': { mode: 'tree-immediate', ownership: 'compatibility', description: 'Legacy public helper; production call sites are forbidden.' },
+  'compat.process-only': { mode: 'process-only', ownership: 'compatibility', description: 'Legacy public helper; production call sites are forbidden.' },
+  'compat.pid-immediate': { mode: 'pid-immediate', ownership: 'compatibility', description: 'Legacy public helper; production call sites are forbidden.' },
+  'compat.pids-immediate': { mode: 'pids-immediate', ownership: 'compatibility', description: 'Legacy public helper; production call sites are forbidden.' },
+  'compat.trees-immediate': { mode: 'trees-immediate', ownership: 'compatibility', description: 'Legacy public helper; production call sites are forbidden.' },
+});
+
+function _terminationOwnershipAllowed(policy, target, opts) {
+  if (policy.ownership === 'compatibility') return true;
+  if (policy.ownership === 'child-handle') {
+    return !!target
+      && typeof target === 'object'
+      && normalizeKillPid(target) !== null
+      && target.killed !== true
+      && (!Object.prototype.hasOwnProperty.call(target, 'exitCode') || target.exitCode === null);
+  }
+  if (policy.ownership === 'facade') return !!target && typeof target.kill === 'function';
+  if (policy.ownership === 'self') return Number(target?.pid) === process.pid;
+  if (policy.ownership === 'exact-script') {
+    const pid = normalizeKillPid(target);
+    return !!pid
+      && typeof opts.scriptPath === 'string'
+      && listNodePidsMatchingScript(opts.scriptPath).includes(pid);
+  }
+  if (policy.ownership === 'exact-scripts') {
+    const pid = normalizeKillPid(target);
+    return !!pid
+      && Array.isArray(opts.scriptPaths)
+      && listNodePidsMatchingScripts(opts.scriptPaths).includes(pid);
+  }
+  if (policy.ownership === 'exact-identity') {
+    const pid = normalizeKillPid(target);
+    const expected = opts.expectedIdentity;
+    if (!pid || !expected || Number(expected.pid) !== pid) return false;
+    const processes = Array.isArray(opts.processes) ? opts.processes : listAllProcesses();
+    return isSameProcessIdentity(expected, getProcessIdentity(pid, { processes }));
+  }
+  if (policy.ownership === 'declared-process') {
+    const pid = normalizeKillPid(target);
+    const processes = Array.isArray(opts.processes) ? opts.processes : listAllProcesses();
+    return !!pid
+      && Number(opts.recordedAtMs) > 0
+      && isProcessIdentityCompatible(
+        getProcessIdentity(pid, { processes }),
+        Number(opts.recordedAtMs),
+        opts.skewMs,
+      );
+  }
+  if (policy.ownership === 'tracked-process' || policy.ownership === 'recorded-agent') {
+    const processes = Array.isArray(opts.processes) ? opts.processes : listAllProcesses();
+    return (policy.ownership !== 'tracked-process' || opts.tracked === true)
+      && Number(opts.recordedAtMs) > 0
+      && isRecordedAgentProcess(normalizeKillPid(target), Number(opts.recordedAtMs), {
+        ...opts,
+        processes,
+      });
+  }
+  return false;
+}
+
+function _filterExactIdentityTargets(target, opts) {
+  const pids = (Array.isArray(target) ? target : [])
+    .map(Number)
+    .filter(pid => Number.isInteger(pid) && pid > 0);
+  const expected = opts.expectedIdentities instanceof Map
+    ? opts.expectedIdentities
+    : new Map();
+  if (pids.length === 0 || expected.size === 0) return [];
+  const processes = Array.isArray(opts.processes) ? opts.processes : listAllProcesses();
+  const currentByPid = new Map(processes.map(entry => [Number(entry.pid), entry]));
+  return pids.filter(pid => {
+    const startedAt = Number(expected.get(pid));
+    const current = currentByPid.get(pid);
+    return startedAt > 0
+      && Number(current?.startedAt) > 0
+      && Number(current.startedAt) === startedAt;
+  });
+}
+
+function terminateProcess(site, target, opts = {}) {
+  const policy = PROCESS_TERMINATION_SITES[site];
+  if (!policy) throw new Error(`Unknown process termination site: ${site}`);
+  let ownedTarget = target;
+  if (policy.ownership === 'exact-identities') {
+    ownedTarget = _filterExactIdentityTargets(target, opts);
+    if (ownedTarget.length === 0) return 0;
+  } else if (!_terminationOwnershipAllowed(policy, target, opts)) {
+    return false;
+  }
+  switch (policy.mode) {
+    case 'tree-graceful':
+      return _killGracefully(ownedTarget, opts.graceMs);
+    case 'tree-immediate':
+      return _killImmediate(ownedTarget);
+    case 'process-only':
+      return _killProcessOnly(ownedTarget);
+    case 'pid-immediate':
+      return _killByPidImmediate(ownedTarget?.pid ?? ownedTarget);
+    case 'pids-immediate':
+      return _killByPidsImmediate(ownedTarget);
+    case 'trees-immediate':
+      return _killByPidTreesImmediate(ownedTarget);
+    case 'facade-cancel':
+      return ownedTarget.kill() !== false;
+    case 'self-signal':
+      try { process.kill(process.pid, opts.signal); return true; }
+      catch { return false; }
+    default:
+      throw new Error(`Unsupported process termination mode: ${policy.mode}`);
+  }
+}
+
+function killGracefully(proc, graceMs = 5000) {
+  return terminateProcess('compat.tree-graceful', proc, { graceMs });
+}
+
+function killImmediate(proc) {
+  return terminateProcess('compat.tree-immediate', proc);
+}
+
+function killProcessOnly(proc) {
+  return terminateProcess('compat.process-only', proc);
+}
+
+function killByPidImmediate(pid) {
+  return terminateProcess('compat.pid-immediate', pid);
+}
+
+function killByPidsImmediate(pids) {
+  return terminateProcess('compat.pids-immediate', pids);
+}
+
+function killByPidTreesImmediate(pids) {
+  return terminateProcess('compat.trees-immediate', pids);
+}
+
 // ─── Process Table Enumeration ───────────────────────────────────────────────
 // Cross-platform listing of every live process as { pid, ppid, name, cmd? }.
 // `cmd` is best-effort — included on Windows (via wmic) and Linux (/proc); may
@@ -315,6 +699,56 @@ function listAllProcesses() {
   return process.platform === 'win32' ? _winListProcesses() : _unixListProcesses();
 }
 
+// W-ms6dmv99005o26f4 — "the enumerator failed" must not read as "those processes
+// are gone".
+//
+// listAllProcesses() collapses EVERY failure — a PowerShell/wmic/ps timeout under
+// fleet load, a maxBuffer overflow, a spawn EAGAIN — into `[]`. Callers that hand
+// that `[]` to the helpers below then get a confident "no such process" for every
+// PID they ask about. engine/cli.js takes exactly one snapshot for the whole fleet
+// at engine start, so a single transient enumeration failure disproved every live
+// agent at once, flagged them all confirmed-dead, and produced the fleet-wide
+// false-orphan storm of 2026-07-29T17:44Z (a dozen dispatches reaped within ~10s,
+// retries consumed and worktrees GC'd — while the agent processes were still
+// running, since nothing had actually killed them).
+//
+// The snapshot is self-validating: a live OS always contains at least the process
+// doing the observing, so a snapshot that is empty, or that omits `selfPid`
+// (truncated read, partially parsed CSV), is known-incomplete and carries no
+// evidence of absence at all.
+const PROCESS_SNAPSHOT_UNAVAILABLE = 'process-snapshot-unavailable';
+
+function captureProcessSnapshot(opts = {}) {
+  const list = typeof opts.list === 'function' ? opts.list : listAllProcesses;
+  const selfPid = Number.isInteger(opts.selfPid) ? opts.selfPid : process.pid;
+  let processes = [];
+  let error = null;
+  try { processes = list(); } catch (err) { error = err; }
+  if (!Array.isArray(processes)) processes = [];
+  const usable = processes.length > 0 && processes.some(entry => Number(entry && entry.pid) === selfPid);
+  if (usable) return { ok: true, processes };
+  return {
+    ok: false,
+    processes: [],
+    reason: error ? `${PROCESS_SNAPSHOT_UNAVAILABLE}: ${error.message}` : PROCESS_SNAPSHOT_UNAVAILABLE,
+  };
+}
+
+// Normalize an `opts.processes` value into a TRUSTED process array, or null when
+// the caller supplied no usable snapshot. Returning null rather than [] is the
+// whole point: [] asserts "these processes do not exist", null admits "unknown".
+//
+// A raw array keeps its historical trusted-input meaning so existing callers
+// (engine/cleanup.js, engine/timeout.js, tests passing synthetic fleets) are
+// unaffected; only a `captureProcessSnapshot()` result can report itself unusable.
+function _resolveSnapshotProcesses(value) {
+  if (Array.isArray(value)) return value;
+  if (value && typeof value === 'object' && Array.isArray(value.processes)) {
+    return value.ok === false ? null : value.processes;
+  }
+  return null;
+}
+
 function _parsePowerShellProcesses(out) {
   const parsed = JSON.parse(out);
   const arr = Array.isArray(parsed) ? parsed : [parsed];
@@ -350,13 +784,41 @@ function _parseUnixProcessesWithStart(out) {
   }).filter(Boolean);
 }
 
-function getProcessIdentity(pid, opts = {}) {
+// W-ms6dmv99005o26f4 — tri-state identity observation.
+//
+// getProcessIdentity() returns null for three very different situations: the PID
+// is invalid, the process is genuinely absent, and "we could not observe it".
+// Only the first two are evidence. Callers that act destructively on a null —
+// engine/cli.js refuses reattach and marks the dispatch confirmed-dead, which
+// bypasses both minAliveBeforeOrphanMs and the engine-restart grace window in
+// engine/timeout.js — need the distinction.
+function inspectProcessIdentity(pid, opts = {}) {
   const value = Number(pid);
-  if (!Number.isInteger(value) || value <= 0) return null;
-  const processes = Array.isArray(opts.processes) ? opts.processes : listAllProcesses();
+  if (!Number.isInteger(value) || value <= 0) {
+    return { identity: null, conclusive: true, reason: 'invalid-pid' };
+  }
+  let processes = _resolveSnapshotProcesses(opts.processes);
+  if (!processes) {
+    // No usable caller snapshot — re-observe live rather than concluding absence.
+    const live = captureProcessSnapshot(
+      typeof opts._list === 'function' ? { list: opts._list, selfPid: opts.selfPid } : {},
+    );
+    if (!live.ok) return { identity: null, conclusive: false, reason: live.reason };
+    processes = live.processes;
+  }
   const match = processes.find(entry => Number(entry && entry.pid) === value);
-  const startedAt = Number(match && match.startedAt);
-  return startedAt > 0 ? { pid: value, startedAt } : null;
+  if (!match) return { identity: null, conclusive: true, reason: 'absent-from-snapshot' };
+  const startedAt = Number(match.startedAt);
+  if (!(startedAt > 0)) {
+    // The process exists but the platform did not report a creation time (e.g. a
+    // `ps` variant without lstart). Absence of a timestamp is not a mismatch.
+    return { identity: null, conclusive: false, reason: 'start-time-unavailable' };
+  }
+  return { identity: { pid: value, startedAt }, conclusive: true, reason: 'snapshot' };
+}
+
+function getProcessIdentity(pid, opts = {}) {
+  return inspectProcessIdentity(pid, opts).identity;
 }
 
 function isProcessIdentityCompatible(identity, recordedAtMs, skewMs = 1000) {
@@ -365,6 +827,27 @@ function isProcessIdentityCompatible(identity, recordedAtMs, skewMs = 1000) {
     && identity.startedAt <= recordedAtMs + skewMs;
 }
 
+// The fail-closed inverse of isProcessIdentityCompatible is NOT proof of a
+// foreign process: that gate also answers false when the identity could not be
+// resolved or the record carries no usable start time (absence of evidence).
+// This helper answers the narrower question — did we resolve a real creation
+// time that is provably LATER than the child we recorded, i.e. is this PID
+// demonstrably somebody else's? Only that is safe to act on destructively
+// (W-ms8d10y3003t0588).
+function isProcessIdentityConclusiveMismatch(identity, recordedAtMs, skewMs = 1000) {
+  const observedAt = Number(identity && identity.startedAt);
+  return Number.isFinite(observedAt)
+    && observedAt > 0
+    && Number.isFinite(recordedAtMs)
+    // A non-positive recorded time is not a real start time — callers coerce a
+    // missing `started_at` through Number(), and Number(null) / Number('') are
+    // both 0. Epoch 0 would make EVERY live process look provably later than
+    // ours, which is the exact absence-of-evidence collapse this helper exists
+    // to prevent.
+    && recordedAtMs > 0
+    && observedAt > recordedAtMs + skewMs;
+}
+
 function isSameProcessIdentity(left, right) {
   return !!left
     && !!right
@@ -465,9 +948,9 @@ function findProcessesWithCwdInside(dir, opts = {}) {
   // Lazy require avoids a load-time circular-require deadlock: shared.js
   // requires this module at top-level, so shared's own module.exports isn't
   // populated yet at that point — but by the time this function actually
-  // RUNS, shared.js has finished loading and require('./shared') resolves
+  // RUNS, shared.js has finished loading and require('../core/shared') resolves
   // to its full, cached exports object.
-  const { ENGINE_DEFAULTS } = require('./shared');
+  const { ENGINE_DEFAULTS } = require('../core/shared');
   const timeoutMs = Number(opts.timeoutMs) > 0
     ? Number(opts.timeoutMs)
     : (ENGINE_DEFAULTS.orphanHolderScanTimeoutMs || 5000);
@@ -747,7 +1230,7 @@ function findProcessCwdHolders(worktreePath, opts = {}) {
   try { resolved = path.resolve(worktreePath); } catch { return []; }
   if (!resolved) return [];
   // Lazy require — see comment in findProcessesWithCwdInside above.
-  const { ENGINE_DEFAULTS, MINIONS_DIR } = require('./shared');
+  const { ENGINE_DEFAULTS, MINIONS_DIR } = require('../core/shared');
   const timeoutMs = Number(opts.timeoutMs) > 0
     ? Number(opts.timeoutMs)
     : (ENGINE_DEFAULTS.statusProbeKillTimeoutMs || 12000);
@@ -779,8 +1262,8 @@ function findProcessCwdHolders(worktreePath, opts = {}) {
 // Cross-check a single PID's command line for a Minions agent invocation,
 // including the shared spawn wrapper and every bundled runtime CLI. Used by
 // orphan/recycled-PID safety:
-//   - engine/cleanup.js: gate before killing a PID found in engine/tmp/pid-*.pid
-//   - engine/timeout.js: gate before parking a dispatch as still-alive when
+//   - engine/orchestration/cleanup.js: gate before killing a PID found in engine/tmp/pid-*.pid
+//   - engine/orchestration/timeout.js: gate before parking a dispatch as still-alive when
 //     the OS PID is alive but may belong to an unrelated recycled-PID process
 //
 // Windows: PowerShell Get-CimInstance for the full CommandLine of one PID.
@@ -802,31 +1285,69 @@ function _commandLineMatchesAgent(cmdline) {
   return AGENT_COMMAND_PATTERNS.some(pattern => pattern.test(value));
 }
 
-function isProcessCommandLineMatchingAgent(pid) {
+// W-ms6dmv99005o26f4 — tri-state command-line observation.
+//
+// `conclusive` answers "did we actually observe anything?", separately from
+// `match`. The old boolean form short-circuited on `Array.isArray(opts.processes)`
+// and returned false whenever the PID was missing from the array — including when
+// that array was the `[]` produced by a FAILED enumeration, so the per-PID
+// fallback probe below never ran and a live agent was reported as not-an-agent.
+function inspectProcessCommandLineForAgent(pid, opts = {}) {
   const n = Number(pid);
-  if (!Number.isInteger(n) || n <= 0) return false;
+  if (!Number.isInteger(n) || n <= 0) return { match: false, conclusive: true, reason: 'invalid-pid' };
+  const snapshot = _resolveSnapshotProcesses(opts.processes);
+  if (snapshot) {
+    const match = snapshot.find(entry => Number(entry?.pid) === n);
+    if (!match) return { match: false, conclusive: true, reason: 'absent-from-snapshot' };
+    if (match.cmd) {
+      return { match: _commandLineMatchesAgent(match.cmd), conclusive: true, reason: 'snapshot-cmdline' };
+    }
+    // Snapshot has the process but no command line (wmic/ps enumerations omit it)
+    // — fall through to the per-PID probe.
+  }
   let cmdline = '';
   try {
-    if (process.platform === 'win32') {
-      const out = _execSync(
-        `powershell -NoProfile -NonInteractive -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId=${n}').CommandLine"`,
-        { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, windowsHide: true, encoding: 'utf8' }
-      );
-      cmdline = String(out || '').trim();
-    } else {
-      try {
-        const buf = fs.readFileSync(`/proc/${n}/cmdline`);
-        cmdline = buf.toString('utf8').replace(/\0/g, ' ').trim();
-      } catch {
-        try {
-          cmdline = String(_execSync(`ps -p ${n} -o command=`,
-            { stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, encoding: 'utf8' }) || '').trim();
-        } catch { return false; }
-      }
-    }
-  } catch { return false; }
-  if (!cmdline) return false;
-  return _commandLineMatchesAgent(cmdline);
+    cmdline = typeof opts._probe === 'function'
+      ? String(opts._probe(n) || '').trim()
+      : _readProcessCommandLine(n);
+  } catch { return { match: false, conclusive: false, reason: 'probe-failed' }; }
+  if (!cmdline) return { match: false, conclusive: false, reason: 'probe-empty' };
+  return { match: _commandLineMatchesAgent(cmdline), conclusive: true, reason: 'live-cmdline' };
+}
+
+// Read one PID's full command line, or throw when it cannot be observed.
+// Windows: PowerShell Get-CimInstance. Linux: /proc/<pid>/cmdline (NUL-separated).
+// macOS / when /proc isn't available: fallback `ps -p <pid> -o command=`.
+function _readProcessCommandLine(n) {
+  if (process.platform === 'win32') {
+    const out = _execSync(
+      `powershell -NoProfile -NonInteractive -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId=${n}').CommandLine"`,
+      { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, windowsHide: true, encoding: 'utf8' }
+    );
+    return String(out || '').trim();
+  }
+  try {
+    const buf = fs.readFileSync(`/proc/${n}/cmdline`);
+    return buf.toString('utf8').replace(/\0/g, ' ').trim();
+  } catch {
+    return String(_execSync(`ps -p ${n} -o command=`,
+      { stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, encoding: 'utf8' }) || '').trim();
+  }
+}
+
+// Boolean facade over inspectProcessCommandLineForAgent. Returns false when the
+// PID is invalid, the process doesn't exist, the command line can't be read, or
+// the cmdline contains no recognized agent marker. False stays the safe default
+// for both historical call sites: cleanup falls through to "skip kill" and
+// timeout falls through to "treat PID as dead".
+function isProcessCommandLineMatchingAgent(pid, opts = {}) {
+  return inspectProcessCommandLineForAgent(pid, opts).match;
+}
+
+function isRecordedAgentProcess(pid, recordedAtMs, opts = {}) {
+  const identity = getProcessIdentity(pid, opts);
+  return isProcessIdentityCompatible(identity, recordedAtMs, opts.skewMs)
+    && isProcessCommandLineMatchingAgent(pid, opts);
 }
 
 function _buildChildMap(processes) {
@@ -838,6 +1359,14 @@ function _buildChildMap(processes) {
   return childMap;
 }
 
+function _isChronologicalChild(parentPid, childPid, byPid) {
+  const parentStartedAt = Number(byPid.get(parentPid)?.startedAt) || 0;
+  const childStartedAt = Number(byPid.get(childPid)?.startedAt) || 0;
+  // Detached children retain their original PPID after the parent exits. If
+  // that PID is later reused, the older process is not a child of the new one.
+  return parentStartedAt <= 0 || childStartedAt <= 0 || childStartedAt >= parentStartedAt;
+}
+
 // BFS descendants of rootPid given a process snapshot. `allProcesses` is
 // injectable for tests and for amortizing one snapshot across multiple
 // `listProcessDescendants` calls in the same tick.
@@ -846,6 +1375,7 @@ function listProcessDescendants(rootPid, allProcesses = null) {
   if (!Number.isInteger(root) || root <= 0) return [];
   const procs = Array.isArray(allProcesses) ? allProcesses : listAllProcesses();
   const childMap = _buildChildMap(procs);
+  const byPid = new Map(procs.map(entry => [Number(entry.pid), entry]));
   const result = [];
   const seen = new Set([root]);
   const queue = [root];
@@ -853,7 +1383,7 @@ function listProcessDescendants(rootPid, allProcesses = null) {
     const cur = queue.shift();
     const children = childMap.get(cur) || [];
     for (const c of children) {
-      if (seen.has(c)) continue;
+      if (seen.has(c) || !_isChronologicalChild(cur, c, byPid)) continue;
       seen.add(c);
       result.push(c);
       queue.push(c);
@@ -873,6 +1403,7 @@ function listProcessReachable(rootPids, allProcesses = null) {
   if (!roots.length) return new Set();
   const procs = Array.isArray(allProcesses) ? allProcesses : listAllProcesses();
   const childMap = _buildChildMap(procs);
+  const byPid = new Map(procs.map(entry => [Number(entry.pid), entry]));
   const seen = new Set();
   const queue = [];
   for (const r of roots) {
@@ -882,7 +1413,7 @@ function listProcessReachable(rootPids, allProcesses = null) {
     const cur = queue.shift();
     const children = childMap.get(cur) || [];
     for (const c of children) {
-      if (seen.has(c)) continue;
+      if (seen.has(c) || !_isChronologicalChild(cur, c, byPid)) continue;
       seen.add(c);
       queue.push(c);
     }
@@ -891,11 +1422,17 @@ function listProcessReachable(rootPids, allProcesses = null) {
 }
 
 module.exports = {
+  PROCESS_TERMINATION_SITES,
+  terminateProcess,
   normalizeKillPid,
   unixChildPids,
   killUnixProcessTree,
   killGracefully,
   killImmediate,
+  killProcessOnly,
+  commandLineRunsScript,
+  listNodePidsMatchingScript,
+  listNodePidsMatchingScripts,
   killByPidImmediate,
   killByPidsImmediate,
   killByPidTreesImmediate,
@@ -907,10 +1444,15 @@ module.exports = {
   _unixListProcesses,
   _parseUnixProcessesWithStart, // exported for testing
   listAllProcesses,
+  captureProcessSnapshot,
+  PROCESS_SNAPSHOT_UNAVAILABLE,
   listAllProcessesAsync,
   getProcessIdentity,
+  inspectProcessIdentity,
   isProcessIdentityCompatible,
+  isProcessIdentityConclusiveMismatch,
   isSameProcessIdentity,
+  isRecordedAgentProcess,
   findProcessesWithCwdInside,
   findProcessesWithCwdInsideAsync,
   _findWindowsProcessesWithCwdInside,
@@ -920,9 +1462,11 @@ module.exports = {
   _parseCwdHolderLines,
   findProcessCwdHolders,
   isProcessCommandLineMatchingAgent,
+  inspectProcessCommandLineForAgent,
   _commandLineMatchesAgent, // exported for testing
   _buildChildMap,
   listProcessDescendants,
   listProcessReachable,
   isPidAlive,
+  inspectPidLiveness,
 };