@yemi33/minions 0.1.2352 → 0.1.2354

package/engine/shared.js

@@ -7,6 +7,11 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
+// Process-management helpers (kill trees, PID liveness, process-table
+// enumeration, cwd-holder detection) live in process-utils.js
+// (P-mrb8yg9x001k1401-b). Re-exported below via `...processUtils` so no
+// caller of require('./shared') needs to change.
+const processUtils = require('./process-utils');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const DEFAULT_MINIONS_HOME = path.join(os.homedir(), '.minions');
@@ -1570,17 +1575,6 @@ function sleepMs(ms) {
 // rewrites) while the PID guard keeps crashed-holder recovery fast.
 const LOCK_STALE_MS = 300000; // 5 minutes — force-remove locks older than this
 
-// Shared.js-local PID liveness check. 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 the lock reaper already has the holder pid in-hand from the
-// lock contents).
-function isPidAlive(pid) {
-  if (!Number.isFinite(pid) || pid <= 0) return false;
-  try { process.kill(pid, 0); return true; }
-  catch { return false; }
-}
-
 // P-8a4d6f29 — single helper for detached-process stdio capture with
 // rotate-on-open. Used by bin/minions.js (engine + dashboard stdio logs) and
 // engine/managed-spawn.js openManagedLog. Centralising replaces the previous
@@ -1767,7 +1761,7 @@ function withFileLock(lockPath, fn, {
 
             let shouldReap;
             if (holderPid !== null) {
-              shouldReap = !isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5;
+              shouldReap = !processUtils.isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5;
             } else {
               // Legacy empty/non-JSON lockfile: trust mtime alone
               shouldReap = true;
@@ -3217,8 +3211,11 @@ const ENGINE_DEFAULTS = {
   // so dispatch proceeds without manual operator intervention. Per-project
   // `project.liveCheckoutAutoStash` overrides this (resolveLiveCheckoutAutoStash).
   // The engine never auto-pops the stash — the operator runs `git stash pop`.
-  // Default false so a fresh install behaves identically to before this knob.
-  liveCheckoutAutoStash: false,
+  // W-mrawiym8000c42c9 — default true fleet-wide: the stash is non-destructive
+  // (recoverable via `git stash pop`, never auto-popped by the engine) and is
+  // now the FIRST line of defense in the dirty-tree recovery flow, now that
+  // the destructive `liveCheckoutAutoReset` defaults OFF (W-mrawgw4q000a6bff).
+  liveCheckoutAutoStash: true,
   prNoOpFixPauseAttempts: 2, // pause one PR automation cause after repeated no-op fixes for unchanged evidence
   quarantineAutoRecoveryMax: 2, // #2996 follow-up: cap on auto-flipping WORKTREE_DIRTY/WORKTREE_DIVERGENT failures back to pending (the quarantine is self-healing so the next dispatch starts clean; the cap prevents infinite loops if quarantine itself keeps failing).
   // W-mq5n1zx5 — Layer 1a/2b: harden the quarantine rename path against
@@ -3592,12 +3589,21 @@ const ENGINE_DEFAULTS = {
   // When ON, a dirty/broken live-checkout tree is `git fetch origin` +
   // `git reset --hard origin/<branch>`'d before dispatch instead of failing
   // LIVE_CHECKOUT_DIRTY. Per-project `project.liveCheckoutAutoReset` overrides
-  // this. Default ON — discarding uncommitted dirt via reset-to-remote keeps
-  // live-checkout branches from diverging (the old `false` default accumulated
-  // `minions: auto-save agent WIP` commits on every dirty exit). Resolution
-  // precedence lives in `resolveLiveCheckoutAutoReset`. Fires ONLY on confirmed
-  // dirty-tree detection, never on mid-operation / blob-fetch / tooling failures.
-  liveCheckoutAutoReset: true,
+  // this. Default FLIPPED BACK to false under W-mrawgw4q000a6bff: the original
+  // divergence problem this was ON to solve (dirty live-checkout trees
+  // accumulating `minions: auto-save agent WIP` commits) is now primarily
+  // addressed by `liveCheckoutAutoStash` (non-destructive — `git stash push`,
+  // recoverable via `git stash pop` — see `resolveLiveCheckoutAutoStash` /
+  // `applyLiveCheckoutAutoStash` in engine/live-checkout.js), which the
+  // stash-before-reset ordering (W-mrawgw4q000a6bff) now always attempts FIRST
+  // when both flags are enabled for a dispatch. Auto-reset remains available as
+  // an explicit opt-in (per-project `project.liveCheckoutAutoReset: true` or
+  // fleet `engine.liveCheckoutAutoReset: true`) for cases that specifically
+  // need the branch fast-forwarded/discarded to `origin/<mainRef>`, not just
+  // cleaned. Resolution precedence lives in `resolveLiveCheckoutAutoReset`
+  // (UNCHANGED by this flip). Fires ONLY on confirmed dirty-tree detection,
+  // never on mid-operation / blob-fetch / tooling failures.
+  liveCheckoutAutoReset: false,
   orphanHolderScanTimeoutMs: 5000,          // 5s ceiling for the cross-platform holder scan (PowerShell / /proc walk / lsof)
   ccMaxTurns: 50, // max tool-use turns per CC/doc-chat call before CLI stops (per response, not per session)
   ccWorkerIdleTimeoutMs: 30 * 60 * 1000, // W-mr0qs0vw: idle-reaper window for the persistent `copilot --acp` worker pool (engine/cc-worker-pool.js). After this much inactivity with no in-flight turn the warm ACP process is killed; the next message cold-spawns a fresh session with NO memory of prior turns (CC shows a "context cleared after inactivity" notice). Tradeoff: shorter = less idle memory/process footprint, longer = more context durability across gaps between messages. Wired into the pool via ccWorkerPool.setIdleTimeoutMs() on every reloadConfig(); clamped to [60000, 28800000] (1min–8h) in the settings POST handler.
@@ -7900,536 +7906,10 @@ function autoEnrollPrFromWorkItem(item, project, minionsDir) {
 // Backward-compat alias — external callers that reference autoEnrollPrFromFixWorkItem keep working.
 const autoEnrollPrFromFixWorkItem = autoEnrollPrFromWorkItem;
 
-// ─── 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 [];
-  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 [];
-  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 = _dispatchTmpRoot();
-    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-platform process-management helpers (kill trees, PID liveness,
+// process-table enumeration, cwd-holder detection, descendant/reachability
+// BFS) were extracted to engine/process-utils.js (P-mrb8yg9x001k1401-b) and
+// are re-exported below via `...processUtils`.
 
 // W-mq6f2fe0000557fa — clear the per-path failure cooldown entry so the
 // post-holder-reap retry can attempt removeWorktree even though the path
@@ -8443,109 +7923,10 @@ function clearWorktreeFailureCache(wtPath) {
   } catch { return false; }
 }
 
-// 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;
-}
+// Cross-platform process-management helpers (kill trees, PID liveness,
+// process-table enumeration, cwd-holder detection, descendant/reachability
+// BFS) were extracted to engine/process-utils.js (P-mrb8yg9x001k1401-b) and
+// are re-exported below via `...processUtils`.
 
 // ─── Work Items & Pull Requests Mutation Helpers ────────────────────────────
 
@@ -9805,19 +9186,7 @@ module.exports = {
   isBuildFixIneffectivePaused,
   parseSkillFrontmatter,
   sleepMs,
-  killGracefully,
-  killImmediate,
-  tasklistOutputShowsPid,
-  getProcessCpuSeconds,
-  killByPidImmediate,
-  killByPidsImmediate,
-  isProcessCommandLineMatchingAgent,
-  listAllProcesses,
-  findProcessesWithCwdInside,
-  findProcessCwdHolders,
   clearWorktreeFailureCache,
-  listProcessDescendants,
-  listProcessReachable,
   removeWorktree,
   isWorktreePathLive,
   getWorktreeBlockingDispatchInfo,
@@ -9833,7 +9202,6 @@ module.exports = {
   _purgeReservedFiles, // exported for testing
   _WIN_RESERVED_NAMES, // exported for testing
   LOCK_STALE_MS,
-  isPidAlive,
   openAppendLogFd,
   flushLogs,
   redactSecrets,
@@ -9849,3 +9217,8 @@ module.exports = {
   createBackoffTracker,
   backfillPrPrdItems,
 };
+
+// Re-export process-management helpers extracted to engine/process-utils.js
+// (P-mrb8yg9x001k1401-b) so every existing require('./shared') call keeps
+// working unchanged.
+module.exports = { ...module.exports, ...processUtils };