@yemi33/minions 0.1.2352 → 0.1.2354

package/engine/process-utils.js

@@ -0,0 +1,700 @@
+/**
+ * engine/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
+ * 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
+ * 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 } = require('child_process');
+
+// 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
+// (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; }
+}
+
+// ─── Cross-Platform Process Kill Helpers ─────────────────────────────────────
+
+function normalizeKillPid(proc) {
+  const pid = Number(proc?.pid);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function unixChildPids(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return [];
+  try {
+    return _execSync(`pgrep -P ${pid}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 })
+      .split(/\r?\n/)
+      .map(line => Number(line.trim()))
+      .filter(childPid => Number.isInteger(childPid) && childPid > 0 && childPid !== pid);
+  } catch {
+    return [];
+  }
+}
+
+function killUnixProcessTree(pid, signal, seen = new Set()) {
+  if (!Number.isInteger(pid) || pid <= 0 || seen.has(pid)) return;
+  seen.add(pid);
+  for (const childPid of unixChildPids(pid)) {
+    killUnixProcessTree(childPid, signal, seen);
+  }
+  try { process.kill(pid, signal); } catch { /* process may be dead */ }
+}
+
+function unrefTimer(timer) {
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  return timer;
+}
+
+function killGracefully(proc, graceMs = 5000) {
+  const pid = normalizeKillPid(proc);
+  if (!pid) return;
+  if (process.platform === 'win32') {
+    try { _execSync(`taskkill /PID ${pid} /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
+    unrefTimer(setTimeout(() => {
+      try { _execSync(`taskkill /PID ${pid} /F /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
+    }, graceMs));
+  } else {
+    killUnixProcessTree(pid, 'SIGTERM');
+    unrefTimer(setTimeout(() => {
+      killUnixProcessTree(pid, 'SIGKILL');
+    }, graceMs));
+  }
+}
+
+function killImmediate(proc) {
+  const pid = normalizeKillPid(proc);
+  if (!pid) return;
+  if (process.platform === 'win32') {
+    try { _execSync(`taskkill /PID ${pid} /F /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
+  } else {
+    killUnixProcessTree(pid, 'SIGKILL');
+  }
+}
+
+// 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.
+// Pure (no shell-out) so callers can pass captured output and unit tests can
+// feed crafted samples.
+function tasklistOutputShowsPid(out, pid, { imageName } = {}) {
+  if (!out) return false;
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  if (!new RegExp(`\\b${n}\\b`).test(out)) return false;
+  if (imageName && !out.toLowerCase().includes(String(imageName).toLowerCase())) return false;
+  return true;
+}
+
+// W-mq0e2dae000a003d — cross-platform CPU-seconds sampler used by the
+// spawn-phase watchdog to decide whether a process is genuinely wedged
+// vs busy. Returns the cumulative user+system CPU time in seconds, or
+// null when we can't determine it (process dead, sampler unavailable,
+// shell errored). Fail-open: a null result MUST NOT cause the watchdog
+// to fire — silence-from-the-OS is not the same as silence-from-the-process.
+function getProcessCpuSeconds(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return null;
+  try {
+    if (process.platform === 'win32') {
+      // PowerShell. CPU = total processor time in seconds (sum of user + kernel).
+      // 2.5s timeout keeps the tick budget bounded if PS is sluggish.
+      const out = _execSync(
+        `powershell -NoProfile -NonInteractive -Command "(Get-Process -Id ${n} -ErrorAction Stop).CPU"`,
+        { stdio: ['ignore', 'pipe', 'pipe'], timeout: 2500, windowsHide: true, encoding: 'utf8' }
+      );
+      const v = parseFloat(String(out).trim());
+      return Number.isFinite(v) ? v : null;
+    }
+    if (process.platform === 'linux') {
+      // /proc/<pid>/stat fields 14 (utime) + 15 (stime) in clock ticks.
+      // _SC_CLK_TCK is 100 on virtually every Linux distro; sysconf isn't
+      // exposed from Node so we use the conventional value. If a host
+      // ever ships USER_HZ != 100 this would under/over-report by a
+      // constant factor; safe within an order of magnitude for our gate.
+      const raw = fs.readFileSync(`/proc/${n}/stat`, 'utf8');
+      // The comm field can contain spaces and parens — slice past the last ')'
+      const close = raw.lastIndexOf(')');
+      if (close < 0) return null;
+      const fields = raw.slice(close + 2).split(/\s+/);
+      // After comm: state(0) ppid(1) pgrp(2) ... utime is index 11, stime 12
+      const utime = Number(fields[11]);
+      const stime = Number(fields[12]);
+      if (!Number.isFinite(utime) || !Number.isFinite(stime)) return null;
+      return (utime + stime) / 100;
+    }
+    if (process.platform === 'darwin') {
+      // `ps -p N -o cputime=` → "MM:SS.ss" or "HH:MM:SS"
+      const out = _execSync(`ps -p ${n} -o cputime=`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 2500, windowsHide: true, encoding: 'utf8' });
+      const t = String(out).trim();
+      if (!t) return null;
+      const parts = t.split(':').map(s => parseFloat(s));
+      if (!parts.every(p => Number.isFinite(p))) return null;
+      let secs = 0;
+      while (parts.length) secs = secs * 60 + parts.shift();
+      return secs;
+    }
+  } catch { /* fail-open */ }
+  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) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0 || n === process.pid) return false;
+  if (process.platform === 'win32') {
+    try { _execSync(`taskkill /PID ${n} /F`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); return true; }
+    catch { return false; }
+  }
+  try { process.kill(n, 'SIGKILL'); return true; } catch { return false; }
+}
+
+// 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) {
+  const valid = (Array.isArray(pids) ? pids : [])
+    .map(Number)
+    .filter(n => Number.isInteger(n) && n > 0 && n !== process.pid);
+  if (!valid.length) return 0;
+  if (process.platform === 'win32') {
+    const flags = valid.map(p => `/PID ${p}`).join(' ');
+    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++; }
+      return killed;
+    }
+  }
+  let killed = 0;
+  for (const p of valid) {
+    try { process.kill(p, 'SIGKILL'); killed++; } catch { /* dead */ }
+  }
+  return killed;
+}
+
+// ─── 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
+// be empty on macOS without ps -ww.
+
+function _parseWmicCsv(text) {
+  const lines = String(text || '').split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+  if (lines.length < 2) return [];
+  const header = lines[0].split(',');
+  const idx = (col) => header.findIndex(h => h.toLowerCase() === col.toLowerCase());
+  const nameIdx = idx('Name');
+  const ppidIdx = idx('ParentProcessId');
+  const pidIdx = idx('ProcessId');
+  const cmdIdx = idx('CommandLine');
+  if (nameIdx < 0 || ppidIdx < 0 || pidIdx < 0) return [];
+  const out = [];
+  for (let i = 1; i < lines.length; i++) {
+    // CommandLine can contain commas — naive split is fine because Name + PIDs
+    // sit at fixed positions and CommandLine, when present, is the LAST column.
+    const cols = lines[i].split(',');
+    if (cols.length < 4) continue;
+    const pid = parseInt(cols[pidIdx], 10);
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    const ppid = parseInt(cols[ppidIdx], 10);
+    const name = cols[nameIdx] || '';
+    const cmd = cmdIdx >= 0 ? cols.slice(cmdIdx).join(',') : '';
+    out.push({ pid, ppid: Number.isInteger(ppid) ? ppid : 0, name, cmd });
+  }
+  return out;
+}
+
+// PowerShell Get-CimInstance is the modern path (wmic is removed on Win11
+// 24H2+). We try it first and fall back to wmic for older Windows hosts.
+function _psListProcesses() {
+  const script = "Get-CimInstance Win32_Process | Select-Object Name,ParentProcessId,ProcessId,CommandLine | ConvertTo-Json -Compress -Depth 2";
+  try {
+    const out = _execSync(
+      `powershell -NoProfile -NonInteractive -Command "${script}"`,
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 4000, windowsHide: true, maxBuffer: 4 * 1024 * 1024 }
+    );
+    const parsed = JSON.parse(out);
+    const arr = Array.isArray(parsed) ? parsed : [parsed];
+    return arr.map(p => ({
+      pid: Number(p.ProcessId),
+      ppid: Number(p.ParentProcessId) || 0,
+      name: p.Name || '',
+      cmd: p.CommandLine || '',
+    })).filter(p => Number.isInteger(p.pid) && p.pid > 0);
+  } catch { return null; }
+}
+
+function _winListProcesses() {
+  const ps = _psListProcesses();
+  if (ps && ps.length) return ps;
+  try {
+    const out = _execSync(
+      'wmic process get Name,ParentProcessId,ProcessId,CommandLine /format:csv',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 4000, windowsHide: true, maxBuffer: 4 * 1024 * 1024 }
+    );
+    return _parseWmicCsv(out);
+  } catch { return []; }
+}
+
+function _unixListProcesses() {
+  try {
+    const out = _execSync(
+      'ps -A -o pid=,ppid=,comm=',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }
+    );
+    return out.split(/\r?\n/).map(line => {
+      const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+      if (!m) return null;
+      return { pid: parseInt(m[1], 10), ppid: parseInt(m[2], 10), name: m[3], cmd: '' };
+    }).filter(Boolean);
+  } catch { return []; }
+}
+
+function listAllProcesses() {
+  return process.platform === 'win32' ? _winListProcesses() : _unixListProcesses();
+}
+
+// W-mq6f2fe0000557fa — orphan-worktree GC: identify OS processes whose cwd
+// is at or inside `dir`. Cross-platform with a fail-open contract: on any
+// error or timeout we return [] (the caller continues with its existing
+// escalation path and an unenriched note).
+//
+// Return shape: [{ pid, cmdline, startedAt, ageMs }, ...]
+//   - pid: numeric OS pid
+//   - cmdline: full command line as a single string (best-effort; possibly truncated)
+//   - startedAt: ms-since-epoch process start time (0 when unknown)
+//   - ageMs: Date.now() - startedAt (0 when startedAt is 0)
+//
+// Platform notes:
+//   - Windows: PowerShell `Get-CimInstance Win32_Process` filtered by the
+//     worktree basename appearing in CommandLine. (Win32_Process does not
+//     expose the working directory; the basename match is the most-reliable
+//     heuristic — every spawn-agent invocation embeds the dispatch id, which
+//     is the worktree basename, in its argv.)
+//   - Linux: walk `/proc/*/cwd` and keep PIDs whose readlinkSync resolves
+//     under `dir`. Cmdline read from `/proc/<pid>/cmdline` (NUL-separated).
+//     Start time derived from stat() mtime of the cwd entry as a proxy.
+//   - macOS: `lsof -F p -d cwd` filtered by directory, then `ps -p <pid>` for
+//     cmdline + start time.
+function findProcessesWithCwdInside(dir, opts = {}) {
+  if (!dir || typeof dir !== 'string') return [];
+  let resolved;
+  try { resolved = path.resolve(dir); } catch { return []; }
+  if (!resolved) return [];
+  // 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
+  // to its full, cached exports object.
+  const { ENGINE_DEFAULTS } = require('./shared');
+  const timeoutMs = Number(opts.timeoutMs) > 0
+    ? Number(opts.timeoutMs)
+    : (ENGINE_DEFAULTS.orphanHolderScanTimeoutMs || 5000);
+  const now = Date.now();
+
+  try {
+    if (process.platform === 'win32') {
+      return _findWindowsProcessesWithCwdInside(resolved, timeoutMs, now);
+    }
+    if (process.platform === 'linux') {
+      return _findLinuxProcessesWithCwdInside(resolved, timeoutMs, now);
+    }
+    return _findMacProcessesWithCwdInside(resolved, timeoutMs, now);
+  } catch { return []; }
+}
+
+function _findWindowsProcessesWithCwdInside(resolved, timeoutMs, now) {
+  // Win32_Process exposes CommandLine but not the cwd. Match by basename of
+  // the worktree dir (the dispatch id like W-mq1k8z6o003acd89) appearing in
+  // the cmdline — every spawn-agent prompt-file path embeds it.
+  const basename = path.basename(resolved);
+  if (!basename || basename.length < 3) return [];
+  // PowerShell-quote: outer escape ' as ''
+  const psBasename = basename.replace(/'/g, "''");
+  const psResolved = resolved.replace(/'/g, "''");
+  // Use -like with wildcards on BOTH basename and full path so a process
+  // whose cmdline carries the worktree dir (but a different basename
+  // anywhere in argv) also matches.
+  const script = `Get-CimInstance Win32_Process | Where-Object { ($_.CommandLine -like '*${psBasename}*') -or ($_.CommandLine -like '*${psResolved}*') } | ForEach-Object { [PSCustomObject]@{ pid = $_.ProcessId; cmdline = $_.CommandLine; startedAt = if ($_.CreationDate) { [int64](([datetimeoffset]$_.CreationDate).ToUnixTimeMilliseconds()) } else { 0 } } } | ConvertTo-Json -Compress -Depth 2`;
+  let raw;
+  try {
+    raw = _execSync(
+      `powershell -NoProfile -NonInteractive -Command "${script}"`,
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024 }
+    );
+  } catch { return []; }
+  if (!raw || !String(raw).trim()) return [];
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch { return []; }
+  const arr = Array.isArray(parsed) ? parsed : [parsed];
+  const out = [];
+  for (const r of arr) {
+    if (!r) continue;
+    const pid = Number(r.pid);
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    const startedAt = Number(r.startedAt) || 0;
+    out.push({
+      pid,
+      cmdline: r.cmdline ? String(r.cmdline) : '',
+      startedAt,
+      ageMs: startedAt > 0 ? Math.max(0, now - startedAt) : 0,
+    });
+  }
+  return out;
+}
+
+function _findLinuxProcessesWithCwdInside(resolved, _timeoutMs, now) {
+  // /proc walk: scan numeric entries, readlink cwd, keep matches.
+  let entries;
+  try { entries = fs.readdirSync('/proc'); }
+  catch { return []; }
+  const prefix = resolved + path.sep;
+  const out = [];
+  for (const e of entries) {
+    if (!/^\d+$/.test(e)) continue;
+    const pid = Number(e);
+    let cwd;
+    try { cwd = fs.readlinkSync(`/proc/${pid}/cwd`); }
+    catch { continue; }
+    if (!cwd) continue;
+    if (cwd !== resolved && !cwd.startsWith(prefix)) continue;
+    let cmdline = '';
+    try {
+      const buf = fs.readFileSync(`/proc/${pid}/cmdline`);
+      cmdline = buf.toString('utf8').replace(/\0/g, ' ').trim();
+    } catch { /* cmdline read can fail on race */ }
+    let startedAt = 0;
+    try {
+      const st = fs.statSync(`/proc/${pid}`);
+      startedAt = st && st.ctimeMs ? Math.floor(st.ctimeMs) : 0;
+    } catch { /* stat can fail on race */ }
+    out.push({
+      pid,
+      cmdline,
+      startedAt,
+      ageMs: startedAt > 0 ? Math.max(0, now - startedAt) : 0,
+    });
+  }
+  return out;
+}
+
+function _findMacProcessesWithCwdInside(resolved, timeoutMs, now) {
+  // `lsof -a -d cwd -F pn` emits PID then cwd path. Filter for dir matches,
+  // then run a single `ps` pass to enrich cmdline + start time.
+  let raw;
+  try {
+    raw = _execSync('lsof -a -d cwd -F pn 2>/dev/null', {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024,
+    });
+  } catch { return []; }
+  if (!raw) return [];
+  const prefix = resolved + path.sep;
+  const pids = new Set();
+  let currentPid = null;
+  for (const line of String(raw).split(/\r?\n/)) {
+    if (!line) continue;
+    const tag = line[0];
+    const val = line.slice(1);
+    if (tag === 'p') {
+      const n = Number(val);
+      currentPid = Number.isInteger(n) && n > 0 ? n : null;
+    } else if (tag === 'n' && currentPid != null) {
+      if (val === resolved || val.startsWith(prefix)) pids.add(currentPid);
+    }
+  }
+  if (pids.size === 0) return [];
+  const out = [];
+  for (const pid of pids) {
+    let line;
+    try {
+      line = String(_execSync(`ps -p ${pid} -o lstart=,command=`, {
+        stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, encoding: 'utf8',
+      }) || '').trim();
+    } catch { line = ''; }
+    let startedAt = 0;
+    let cmdline = '';
+    if (line) {
+      // ps lstart= emits "Mon Jun  9 07:04:33 2026" (24 chars), then cmdline.
+      const lstart = line.slice(0, 24).trim();
+      cmdline = line.slice(24).trim();
+      const parsed = Date.parse(lstart);
+      if (!Number.isNaN(parsed)) startedAt = parsed;
+    }
+    out.push({
+      pid,
+      cmdline,
+      startedAt,
+      ageMs: startedAt > 0 ? Math.max(0, now - startedAt) : 0,
+    });
+  }
+  return out;
+}
+
+// W-mqila0t5 — Windows-only PEB-based CWD probe used by the worktree-holder
+// reaper. Unlike findProcessesWithCwdInside (whose Windows path is a
+// CommandLine-basename heuristic — Win32_Process does NOT expose the working
+// directory), this reads each process's REAL current directory out of its PEB
+// (NtQueryInformationProcess → PebBaseAddress, then ReadProcessMemory of
+// RTL_USER_PROCESS_PARAMETERS.CurrentDirectory.DosPath). That's the only way
+// to find a process that pins a directory via its CWD — e.g. an orphaned
+// copilot.exe / cmd.exe / node.exe agent child whose cwd is the worktree root
+// but whose argv never mentions the path (so the cmdline heuristic
+// false-negatives, and the Restart Manager / file-handle detectors report ZERO
+// lockers because the lock is a DIRECTORY handle, not a file handle).
+//
+// Returns [{ pid, name, cwd }] for processes whose CWD is at-or-under
+// `worktreePath`. POSIX returns [] (the EBUSY race is Windows-specific; POSIX
+// reaping stays a no-op). Fail-open: any error / timeout / spawn failure →
+// [] (reap nothing). x64 offsets only (PebBaseAddress@8, PEB+0x20 →
+// ProcessParameters, RTL_USER_PROCESS_PARAMETERS+0x38 → CurrentDirectory).
+function _windowsCwdProbeScript(psTarget) {
+  return [
+    "$ErrorActionPreference='SilentlyContinue'",
+    `$target = '${psTarget}'.TrimEnd('\\').ToLower()`,
+    'Add-Type -Namespace MinionsPeb -Name Native -MemberDefinition @"',
+    '[DllImport("ntdll.dll")] public static extern int NtQueryInformationProcess(IntPtr h, int cls, byte[] info, int len, ref int ret);',
+    '[DllImport("kernel32.dll")] public static extern IntPtr OpenProcess(int access, bool inherit, int pid);',
+    '[DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr h);',
+    '[DllImport("kernel32.dll")] public static extern bool ReadProcessMemory(IntPtr h, IntPtr baseAddr, byte[] buf, int size, ref int read);',
+    '"@',
+    'function Get-ProcCwd($procId) {',
+    '  $h = [MinionsPeb.Native]::OpenProcess(0x410, $false, $procId)',
+    '  if ($h -eq [IntPtr]::Zero) { return $null }',
+    '  try {',
+    '    $pbi = New-Object byte[] 48; $ret = 0',
+    '    if ([MinionsPeb.Native]::NtQueryInformationProcess($h, 0, $pbi, 48, [ref]$ret) -ne 0) { return $null }',
+    '    $pebBase = [System.BitConverter]::ToInt64($pbi, 8)',
+    '    if ($pebBase -eq 0) { return $null }',
+    '    $p8 = New-Object byte[] 8; $r = 0',
+    '    if (-not [MinionsPeb.Native]::ReadProcessMemory($h, [IntPtr]($pebBase + 0x20), $p8, 8, [ref]$r)) { return $null }',
+    '    $params = [System.BitConverter]::ToInt64($p8, 0)',
+    '    if ($params -eq 0) { return $null }',
+    '    $us = New-Object byte[] 16',
+    '    if (-not [MinionsPeb.Native]::ReadProcessMemory($h, [IntPtr]($params + 0x38), $us, 16, [ref]$r)) { return $null }',
+    '    $len = [System.BitConverter]::ToUInt16($us, 0)',
+    '    $bufPtr = [System.BitConverter]::ToInt64($us, 8)',
+    '    if ($len -le 0 -or $bufPtr -eq 0) { return $null }',
+    '    $sb = New-Object byte[] $len',
+    '    if (-not [MinionsPeb.Native]::ReadProcessMemory($h, [IntPtr]$bufPtr, $sb, $len, [ref]$r)) { return $null }',
+    '    return [System.Text.Encoding]::Unicode.GetString($sb, 0, $len)',
+    '  } finally { [void][MinionsPeb.Native]::CloseHandle($h) }',
+    '}',
+    'foreach ($p in Get-Process) {',
+    '  $cwd = Get-ProcCwd $p.Id',
+    '  if (-not $cwd) { continue }',
+    "  $c = $cwd.TrimEnd('\\').ToLower()",
+    "  if ($c -eq $target -or $c.StartsWith($target + '\\')) {",
+    '    Write-Output ("{0}|{1}|{2}" -f $p.Id, $p.ProcessName, $cwd)',
+    '  }',
+    '}',
+  ].join('\n');
+}
+
+function _parseCwdHolderLines(raw, resolved) {
+  if (!raw || !String(raw).trim()) return [];
+  const prefix = (resolved.replace(/[\\/]+$/g, '') + path.sep).toLowerCase();
+  const target = resolved.replace(/[\\/]+$/g, '').toLowerCase();
+  const out = [];
+  for (const line of String(raw).split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    const parts = t.split('|');
+    if (parts.length < 3) continue;
+    const pid = Number(parts[0]);
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    const name = parts[1] || '';
+    const cwd = parts.slice(2).join('|');
+    // Defense-in-depth: re-confirm the cwd is at/under THIS worktree so a
+    // sibling worktree's live agent is never reaped (the script filters too).
+    const cwdLower = cwd.replace(/[\\/]+$/g, '').toLowerCase();
+    if (cwdLower !== target && !cwdLower.startsWith(prefix)) continue;
+    out.push({ pid, name, cwd });
+  }
+  return out;
+}
+
+function findProcessCwdHolders(worktreePath, opts = {}) {
+  if (process.platform !== 'win32') return [];
+  if (!worktreePath || typeof worktreePath !== 'string') return [];
+  let resolved;
+  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 timeoutMs = Number(opts.timeoutMs) > 0
+    ? Number(opts.timeoutMs)
+    : (ENGINE_DEFAULTS.statusProbeKillTimeoutMs || 12000);
+  const psTarget = resolved.replace(/'/g, "''");
+  const script = _windowsCwdProbeScript(psTarget);
+  // Run from a temp .ps1 file to avoid fragile inline-quote escaping of the
+  // embedded C#. Fail-open at every step.
+  let scriptPath = null;
+  let raw;
+  try {
+    const dir = path.join(MINIONS_DIR, 'engine', 'tmp');
+    try { fs.mkdirSync(dir, { recursive: true }); } catch { /* exists */ }
+    scriptPath = path.join(dir, `cwd-probe-${process.pid}-${Date.now()}.ps1`);
+    fs.writeFileSync(scriptPath, script, 'utf8');
+    raw = _execSync(
+      `powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "${scriptPath}"`,
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024 }
+    );
+  } catch { raw = ''; /* ETIMEDOUT / spawn fail / write fail → reap nothing */ }
+  finally {
+    if (scriptPath) { try { fs.unlinkSync(scriptPath); } catch { /* best-effort */ } }
+  }
+  return _parseCwdHolderLines(raw, resolved);
+}
+
+// Cross-check a single PID's command line for a Minions agent invocation
+// (`claude` or `copilot`, including the `node spawn-agent.js --runtime <name>`
+// wrapper and `gh copilot` fallback). 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
+//     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.
+// Linux:   /proc/<pid>/cmdline (NUL-separated).
+// macOS / when /proc isn't available: fallback `ps -p <pid> -o command=`.
+//
+// Returns false when the PID is invalid, the process doesn't exist, the
+// command line can't be read, or the cmdline contains neither `claude` nor
+// `copilot`. False is the safe default for both call sites: cleanup falls
+// through to "skip kill" and timeout falls through to "treat PID as dead".
+function isProcessCommandLineMatchingAgent(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  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;
+  const lower = cmdline.toLowerCase();
+  return lower.includes('claude') || lower.includes('copilot');
+}
+
+function _buildChildMap(processes) {
+  const childMap = new Map();
+  for (const p of processes) {
+    if (!childMap.has(p.ppid)) childMap.set(p.ppid, []);
+    childMap.get(p.ppid).push(p.pid);
+  }
+  return childMap;
+}
+
+// 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.
+function listProcessDescendants(rootPid, allProcesses = null) {
+  const root = Number(rootPid);
+  if (!Number.isInteger(root) || root <= 0) return [];
+  const procs = Array.isArray(allProcesses) ? allProcesses : listAllProcesses();
+  const childMap = _buildChildMap(procs);
+  const result = [];
+  const seen = new Set([root]);
+  const queue = [root];
+  while (queue.length) {
+    const cur = queue.shift();
+    const children = childMap.get(cur) || [];
+    for (const c of children) {
+      if (seen.has(c)) continue;
+      seen.add(c);
+      result.push(c);
+      queue.push(c);
+    }
+  }
+  return result;
+}
+
+// Same BFS, but starts from any number of root PIDs and returns the full reach
+// set (including the roots themselves). Used by the orphan-MCP sweep to compute
+// "everything anchored to Minions" so non-anchored MCP node processes can be
+// identified.
+function listProcessReachable(rootPids, allProcesses = null) {
+  const roots = (Array.isArray(rootPids) ? rootPids : [rootPids])
+    .map(Number)
+    .filter(n => Number.isInteger(n) && n > 0);
+  if (!roots.length) return new Set();
+  const procs = Array.isArray(allProcesses) ? allProcesses : listAllProcesses();
+  const childMap = _buildChildMap(procs);
+  const seen = new Set();
+  const queue = [];
+  for (const r of roots) {
+    if (!seen.has(r)) { seen.add(r); queue.push(r); }
+  }
+  while (queue.length) {
+    const cur = queue.shift();
+    const children = childMap.get(cur) || [];
+    for (const c of children) {
+      if (seen.has(c)) continue;
+      seen.add(c);
+      queue.push(c);
+    }
+  }
+  return seen;
+}
+
+module.exports = {
+  normalizeKillPid,
+  unixChildPids,
+  killUnixProcessTree,
+  killGracefully,
+  killImmediate,
+  killByPidImmediate,
+  killByPidsImmediate,
+  tasklistOutputShowsPid,
+  getProcessCpuSeconds,
+  _parseWmicCsv,
+  _psListProcesses,
+  _winListProcesses,
+  _unixListProcesses,
+  listAllProcesses,
+  findProcessesWithCwdInside,
+  _findWindowsProcessesWithCwdInside,
+  _findLinuxProcessesWithCwdInside,
+  _findMacProcessesWithCwdInside,
+  _windowsCwdProbeScript,
+  _parseCwdHolderLines,
+  findProcessCwdHolders,
+  isProcessCommandLineMatchingAgent,
+  _buildChildMap,
+  listProcessDescendants,
+  listProcessReachable,
+  isPidAlive,
+};