@yemi33/minions 0.1.1950 → 0.1.1952

package/engine/shared.js

@@ -632,7 +632,23 @@ function sleepMs(ms) {
   }
 }
 
-const LOCK_STALE_MS = 60000; // 60 seconds — force-remove locks older than this
+// P-b7d4e8f2 — bumped from 60_000 to 300_000 once the reaper grew a PID-liveness
+// guard (below). Holders that record their pid are protected from reap up to
+// 5×LOCK_STALE_MS as long as `process.kill(pid, 0)` succeeds; the bump removes
+// false-positive kills of legitimate slow operations (worktree adds, large state
+// 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; }
+}
 
 function withFileLock(lockPath, fn, {
   timeoutMs = 5000,
@@ -655,20 +671,54 @@ function withFileLock(lockPath, fn, {
         const dir = path.dirname(lockPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
         fd = fs.openSync(lockPath, 'wx');
+        // P-b7d4e8f2 — record holder identity so the stale-lock reaper can
+        // distinguish a still-alive slow holder from a crashed one. Best-effort:
+        // the lock's existence (not its contents) provides mutual exclusion, so
+        // a write failure here must NOT abort acquisition.
+        try {
+          fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+        } catch { /* payload is advisory; lock semantics unaffected */ }
         break;
       } catch (err) {
         if (err.code !== 'EEXIST') throw err;
-        // Check for stale lock — if lock file is older than LOCK_STALE_MS, force-remove it
+        // P-b7d4e8f2 — Stale-lock check combines mtime age with PID liveness:
+        //   1. If mtime <= LOCK_STALE_MS  → never reap (recently active).
+        //   2. If JSON-parsable {pid, ts}:
+        //      - dead PID                 → reap.
+        //      - alive PID, mtime <= 5×   → don't reap (legitimate slow holder).
+        //      - alive PID, mtime > 5×    → reap (last-resort guard against
+        //                                    stuck holders that never released).
+        //   3. Legacy / empty / non-JSON lockfile → mtime-only path (reap).
         try {
           const stat = fs.statSync(lockPath);
-          if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+          const mtimeAge = Date.now() - stat.mtimeMs;
+          if (mtimeAge > LOCK_STALE_MS) {
+            let holderPid = null;
             try {
-              fs.unlinkSync(lockPath);
-            } catch (unlinkErr) {
-              // ENOENT: another process deleted the lock between stat and unlink — safe to retry
-              if (unlinkErr.code !== 'ENOENT') throw unlinkErr;
+              const raw = fs.readFileSync(lockPath, 'utf8');
+              const parsed = JSON.parse(raw);
+              if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) {
+                holderPid = parsed.pid;
+              }
+            } catch { /* legacy/empty/corrupt lock → fall through to mtime-only */ }
+
+            let shouldReap;
+            if (holderPid !== null) {
+              shouldReap = !isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5;
+            } else {
+              // Legacy empty/non-JSON lockfile: trust mtime alone
+              shouldReap = true;
+            }
+
+            if (shouldReap) {
+              try {
+                fs.unlinkSync(lockPath);
+              } catch (unlinkErr) {
+                // ENOENT: another process deleted the lock between stat and unlink — safe to retry
+                if (unlinkErr.code !== 'ENOENT') throw unlinkErr;
+              }
+              continue; // lock just removed — retry immediately
             }
-            continue; // lock just removed — retry immediately
           }
         } catch (staleErr) {
           // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed
@@ -683,10 +733,24 @@ function withFileLock(lockPath, fn, {
     }
 
     try {
-      return fn();
+      const result = fn();
+      // P-a3f9b2c1 — Defensive: detect a thenable return and throw synchronously.
+      // The `finally` below releases the lock immediately after `fn()` returns;
+      // an async callback would let the lock be released before its body
+      // completes, silently breaking mutual exclusion. Clean up our own fd /
+      // lock first, then throw so the caller cannot ignore the failure.
+      if (result && typeof result.then === 'function') {
+        try { fs.closeSync(fd); } catch { /* cleanup */ }
+        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
+        fd = null; // suppress double-cleanup in `finally`
+        throw new Error('withFileLock: fn must be synchronous; got Promise. Use synchronous operations only.');
+      }
+      return result;
     } finally {
-      try { fs.closeSync(fd); } catch { /* cleanup */ }
-      try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
+      if (fd !== null) {
+        try { fs.closeSync(fd); } catch { /* cleanup */ }
+        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
+      }
     }
   }
   throw lastErr;
@@ -867,7 +931,9 @@ function writeToInbox(agentId, slug, content, _inboxDir, metadata) {
 // ── Process Spawning ────────────────────────────────────────────────────────
 // All child process calls go through these to ensure windowsHide: true
 
-const { execSync: _execSync, spawnSync: _spawnSync, spawn: _spawn, exec: _cbExec } = require('child_process');
+const { execSync: _execSync, spawnSync: _spawnSync, spawn: _spawn, exec: _cbExec, execFile: _cbExecFile } = require('child_process');
+const { promisify: _promisify } = require('util');
+const _execFileAsync = _promisify(_cbExecFile);
 
 function exec(cmd, opts = {}) {
   return _execSync(cmd, { windowsHide: true, ...opts });
@@ -908,6 +974,149 @@ function execAsync(cmd, opts = {}) {
   });
 }
 
+// ── Argv-form (shell:false) helpers + ref/slug validators (P-a7c4d2e8) ──────
+// These eliminate shell-injection vectors in `gh`/`git` calls that previously
+// interpolated untrusted PR data (slugs from PR-link regex matches, branch
+// names from GitHub/ADO API responses, agent stdout, etc.) into a shell
+// string. Use these instead of execAsync wherever any argument is derived
+// from an untrusted source.
+//
+//   const out = await shared.shellSafeGh(['api', `repos/${shared.validateGhSlug(slug)}/pulls/${prNum}`]);
+//   await shared.shellSafeGit(['fetch', 'origin', shared.validateGitRef(branch)], { cwd });
+//
+// Validators throw on rejection; the wrapper helpers spawn via execFile
+// (shell:false) so shell metacharacters in argv elements are inert.
+
+// Tightened beyond the spec baseline regex to also block argument-injection
+// (leading dash) and unsafe ref-format quirks the shell can't help with —
+// `..` traversal, `@{`, `*`/`?` globs, leading/trailing/double slashes, and
+// path components ending in `.lock`. Mirrors a conservative subset of
+// `git check-ref-format`.
+function validateGitRef(ref) {
+  const fail = (why) => {
+    const e = new Error(`Invalid git ref (${why}): ${JSON.stringify(String(ref).slice(0, 64))}`);
+    throw e;
+  };
+  if (typeof ref !== 'string') fail('not a string');
+  if (ref.length === 0) fail('empty');
+  if (ref.length > 256) fail('too long');
+  if (!/^[A-Za-z0-9._\/-]+$/.test(ref)) fail('disallowed character');
+  if (ref.startsWith('-')) fail('leading dash');
+  if (ref.startsWith('/') || ref.endsWith('/')) fail('leading or trailing slash');
+  if (ref.includes('//')) fail('double slash');
+  if (ref.endsWith('.')) fail('trailing dot');
+  if (ref.includes('@{')) fail('ref expression @{');
+  // Per-component checks (split on `/`).
+  for (const part of ref.split('/')) {
+    if (part.length === 0) fail('empty path component');
+    if (part === '..' || part === '.') fail('dot path component');
+    if (part.includes('..')) fail('double-dot in component');
+    if (part.endsWith('.lock')) fail('component ends with .lock');
+    if (part.startsWith('.')) fail('component starts with dot');
+  }
+  return ref;
+}
+
+function validateGhSlug(slug) {
+  const fail = (why) => {
+    throw new Error(`Invalid GitHub slug (${why}): ${JSON.stringify(String(slug).slice(0, 64))}`);
+  };
+  if (typeof slug !== 'string') fail('not a string');
+  if (slug.length === 0) fail('empty');
+  if (slug.length > 256) fail('too long');
+  if (slug !== slug.trim()) fail('surrounding whitespace');
+  if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(slug)) fail('disallowed character or shape');
+  if (slug.startsWith('-') || slug.includes('/-')) fail('leading dash in component');
+  return slug;
+}
+
+// W-mp6k7ywi000fa33c — pure helper. Returns { ok: boolean, reason?: string }.
+// `ok: true` when `dirPath` exists AND contains either a `.git` directory OR
+// a `.git` worktree pointer file (a real file whose first line starts with
+// `gitdir:`). Anything else — missing dir, missing `.git`, `.git` as a
+// random non-pointer file — returns `ok: false` with a human-readable reason.
+//
+// No shelling out (no `git rev-parse`); just `fs.existsSync`/`fs.statSync`
+// and a tiny content sniff for the worktree pointer case. This catches the
+// failure mode where an agent ran in a partial copy of a repo (selective
+// `cp -r`) instead of `git worktree add`, which produced a directory that
+// looks file-by-file like a worktree but has no git linkage. See
+// W-mp6ha6q9000d58a5 for the real-world incident this prevents.
+function isValidGitWorktree(dirPath) {
+  if (typeof dirPath !== 'string' || dirPath.length === 0) {
+    return { ok: false, reason: 'cwd missing or not a string' };
+  }
+  let dirStat;
+  try { dirStat = fs.statSync(dirPath); }
+  catch (_e) { return { ok: false, reason: 'directory does not exist: ' + dirPath }; }
+  if (!dirStat.isDirectory()) {
+    return { ok: false, reason: 'path is not a directory: ' + dirPath };
+  }
+  const gitPath = path.join(dirPath, '.git');
+  let gitStat;
+  try { gitStat = fs.statSync(gitPath); }
+  catch (_e) { return { ok: false, reason: 'no .git directory or worktree pointer at ' + dirPath }; }
+  if (gitStat.isDirectory()) return { ok: true };
+  if (gitStat.isFile()) {
+    // Worktree pointer files contain "gitdir: <abs path>" on the first line.
+    // A `.git` file that doesn't match this shape is a normal file, not a
+    // valid worktree linkage — reject it.
+    let head = '';
+    try { head = fs.readFileSync(gitPath, { encoding: 'utf8', flag: 'r' }).slice(0, 256); }
+    catch (e) { return { ok: false, reason: '.git file unreadable: ' + e.message }; }
+    if (/^gitdir:\s*\S/.test(head)) return { ok: true };
+    return { ok: false, reason: '.git file present but not a worktree pointer (no "gitdir:" prefix): ' + dirPath };
+  }
+  return { ok: false, reason: '.git entry is neither a file nor a directory: ' + gitPath };
+}
+
+function shellSafeGh(args, opts = {}) {
+  if (!Array.isArray(args)) {
+    return Promise.reject(new TypeError('shellSafeGh: args must be an array'));
+  }
+  const { timeout, ...rest } = opts;
+  return _execFileAsync('gh', args, {
+    windowsHide: true,
+    encoding: 'utf8',
+    shell: false,
+    ...rest,
+    timeout: timeout || 30000,
+  }).then(({ stdout }) => stdout);
+}
+
+function shellSafeGit(args, opts = {}) {
+  if (!Array.isArray(args)) {
+    return Promise.reject(new TypeError('shellSafeGit: args must be an array'));
+  }
+  const { timeout, ...rest } = opts;
+  return _execFileAsync('git', args, {
+    windowsHide: true,
+    encoding: 'utf8',
+    shell: false,
+    ...rest,
+    timeout: timeout || 30000,
+  }).then(({ stdout }) => stdout);
+}
+
+// Sync argv-form helper for callers that aren't async (e.g. plan
+// materialization in materializePlansAsWorkItems). Uses execFileSync with
+// shell:false so argv elements are passed verbatim.
+function shellSafeGitSync(args, opts = {}) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('shellSafeGitSync: args must be an array');
+  }
+  const { timeout, ...rest } = opts;
+  const { execFileSync: _execFileSync } = require('child_process');
+  return _execFileSync('git', args, {
+    windowsHide: true,
+    encoding: 'utf8',
+    shell: false,
+    stdio: 'pipe',
+    ...rest,
+    timeout: timeout || 30000,
+  });
+}
+
 /**
  * Detect the default branch for a git repo. Tries in order:
  * 1. The configured mainBranch (if it exists as a local or remote ref)
@@ -1136,9 +1345,18 @@ const ENGINE_DEFAULTS = {
   prMergeMethod: 'squash', // merge method: squash, merge, rebase
   ignoredCommentAuthors: [], // comments from these authors are auto-closed and never trigger fixes
   botCommentLogins: [], // P-a3f9b2c1: opt-in shared-minions GH login list — comments from these logins are suppressed ONLY when body matches positive-signal markers (Verification SUCCESS / VERDICT:APPROVE / noop:true). Narrower than ignoredCommentAuthors which suppresses all comments by login.
+  // W-mp76pw7a001da7c1 — Per-slug GitHub PAT routing. Map of `<owner>` (or `<owner>/*`,
+  // or `*` for fleet default) to a `gh auth` account name. `engine/gh-token.js`
+  // resolves the right token via `gh auth token --user <account> --hostname github.com`
+  // and threads it as `GH_TOKEN` for that one shell-out, so the engine never depends
+  // on which gh account is globally active. Empty `{}` (default) preserves legacy
+  // behavior — every `gh` call uses the ambient identity. Example:
+  //   { "opg-microsoft": "yemishin_microsoft", "yemi33": "yemi33", "*": "yemi33" }
+  ghAccounts: {},
   agentBusyReassignMs: 600000, // 10min — reassign work item to another agent if preferred agent is busy beyond this threshold
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
   enablePreDispatchEval: true, // P-d2a9f6e5: cheap LLM gate before queueing — on by default. See engine/pre-dispatch-eval.js (Ripley §3 recommendation, 2026-05-11 architecture review). Validates from acceptance_criteria when present, falls back to description when criteria are absent but description is rich (≥80 chars). Fail-open on any validator error.
+  completionNonceRequired: false, // P-d2a8f6c1 (agent trust boundary F8): when true, a missing `nonce` field in the completion JSON hard-fails the dispatch with failure_class:'completion-nonce-mismatch'. Default false for one release so older agents/runtime caches that haven't picked up the prompt change degrade with a warning instead of breaking. Mismatched nonces hard-fail regardless of this flag. See docs/completion-reports.md → "Trust boundary".
 
   // ── Runtime fleet (P-3b8e5f1d) ──────────────────────────────────────────────
   // Single source of truth for which CLI runtime + model every spawn uses.
@@ -1181,6 +1399,38 @@ const ENGINE_DEFAULTS = {
   maxMeetingHumanNotesBytes: 2 * 1024, // cap human note bullet lists injected into meeting prompts
   maxPipelineMeetingContextBytes: 16 * 1024, // cap aggregated meeting/dependency context for pipeline plan generation
   notesArchiveMaxFiles: 2000, // keep notes/archive bounded during periodic cleanup
+  // ── Worktree pool (W-mp73ya3e000me6c5) ─────────────────────────────────────
+  // Per-project warm pool: completed worktrees are parked detached at
+  // origin/<main> instead of torn down, then re-borrowed by the next dispatch
+  // for the same project. Saves the cold install/build cost on heavy projects
+  // (constellation: bun install + Vite warmup; minions: npm install + test cache).
+  // Default off — opt-in fleet-wide via engine.worktreePoolSize or per-project
+  // via projects[].worktreePoolSize. See engine/worktree-pool.js + CLAUDE.md
+  // "Worktree pool" section for the lifecycle and edge cases.
+  worktreePoolSize: 0,                        // 0 = disabled (default); per-project override beats this
+  worktreePoolIdleTtlMs: 6 * 3600 * 1000,     // 6h — idle entries past TTL are evicted by cleanup
+  // ── keep_processes (W-mp68q6ke0010de68) ────────────────────────────────────
+  // Opt-in per-WI (`meta.keep_processes: true`) feature that lets an agent
+  // declare specific descendant PIDs the engine MUST NOT reap on close. The
+  // agent writes `agents/<id>/keep-pids.json` before exiting; spawn-agent's
+  // close handler subtracts those PIDs from the reap set and the MCP sweep
+  // adds them as anchors so the reachability walk doesn't classify their
+  // children as stray. Hard caps below bound abuse and audit-log churn.
+  keepProcesses: {
+    enabled: true,         // global kill switch; default ON since the feature is opt-in per-WI
+    maxPerAgent: 5,        // max PIDs honored per keep-pids.json file
+    maxTtlMinutes: 1440,   // 24h hard cap on expires_at
+    defaultTtlMinutes: 60, // default TTL when meta.keep_processes_ttl_minutes is unset
+    sweepEvery: 30,        // ticks between TTL/dead-PID sweeps
+    // W-mp6k7ywi000fa33c — when true (default), validateKeepPidsRecord rejects
+    // a keep-pids.json whose `cwd` does not look like a real git worktree
+    // (no `.git` dir or worktree-pointer file). Catches the failure mode where
+    // an agent runs in a partial copy of a repo (selective `cp -r`) instead
+    // of using `git worktree add`. Per-WI override: set
+    // `meta.keep_processes_skip_workdir_check: true` for legitimate non-git
+    // keep_processes use cases.
+    requireGitWorkdir: true,
+  },
   // Backward-compat: keep `engine.claude.*` field family deprecation tracker. Listed here so preflight
   // knows which subkeys to flag as deprecated. Do not consume `claude.*` in new code — use the runtime
   // adapter system (engine/runtimes/) and the resolveAgent*/resolveCc* helpers instead.
@@ -1586,6 +1836,27 @@ const WORK_TYPE = {
   MEETING: 'meeting', EXPLORE: 'explore', ASK: 'ask', TEST: 'test', DOCS: 'docs',
 };
 
+// Work types whose dispatch path requires a per-project git worktree. The
+// engine's spawnAgent uses the project's `localPath` as the worktree root —
+// without an owning project the rootDir falls back to MINIONS_DIR's parent,
+// which on Windows can collapse to a drive root and forever-fail
+// assertWorktreeOutsideProject. The dashboard ingress (POST /api/work-items
+// and /api/work-items/retry) refuses to create or re-spawn a project-less WI
+// of any type in this set when PROJECTS.length !== 1.
+//
+// Complement of engine.js READ_ONLY_ROOT_TASK_TYPES; `docs` is intentionally
+// also exempt because docs edits run at the Minions root, not in a project
+// worktree.
+const WORKTREE_REQUIRING_TYPES = new Set([
+  WORK_TYPE.FIX,
+  WORK_TYPE.IMPLEMENT,
+  WORK_TYPE.IMPLEMENT_LARGE,
+  WORK_TYPE.TEST,
+  WORK_TYPE.VERIFY,
+  WORK_TYPE.REVIEW,
+  WORK_TYPE.DECOMPOSE,
+]);
+
 const PLAN_STATUS = {
   ACTIVE: 'active', AWAITING_APPROVAL: 'awaiting-approval', APPROVED: 'approved',
   PAUSED: 'paused', REJECTED: 'rejected', COMPLETED: 'completed',
@@ -1806,6 +2077,9 @@ const FAILURE_CLASS = {
   NETWORK_ERROR: 'network-error',         // API rate limit, DNS, connectivity
   OUT_OF_CONTEXT: 'out-of-context',       // Context window exhausted (token limit, context length)
   MAX_TURNS: 'max-turns',                 // Claude CLI error_max_turns — work in progress, retryable
+  COMPLETION_NONCE_MISMATCH: 'completion-nonce-mismatch', // P-d2a8f6c1: completion JSON nonce did not match the per-spawn value injected via MINIONS_COMPLETION_NONCE — treat as forged/untrusted; ignore PR/noop/status fields from the report
+  WORKTREE_PREFLIGHT: 'worktree-preflight', // Pre-spawn worktree validation rejected (nested-in-project, drive-root collapse) — never retryable
+  INVALID_KEEP_PROCESSES_WORKDIR: 'invalid-keep-processes-workdir', // W-mp6k7ywi000fa33c: keep-pids.json declared a cwd that is not a real git worktree (likely a selective copy of the repo) — never retryable; agent must rerun in a real worktree
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 const ESCALATION_POLICY = {
@@ -1817,7 +2091,7 @@ const ESCALATION_POLICY = {
 };
 
 // Structured completion protocol — fields agents must produce in ```completion blocks
-const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'not_changed', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts'];
+const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'not_changed', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts', 'nonce'];
 
 const DEFAULT_AGENT_METRICS = {
   tasksCompleted: 0, tasksErrored: 0,
@@ -2532,6 +2806,110 @@ function assertWorktreeOutsideProject(worktreePath, projectRoot) {
   throw err;
 }
 
+/**
+ * Resolve the project root directory used as the parent for git worktree paths
+ * during dispatch. Centralizes the fallback that engine spawnAgent used to do
+ * inline (`project.localPath ? path.resolve(project.localPath) : path.resolve(MINIONS_DIR, '..')`).
+ *
+ * Why this helper exists: when a central work item (no `project` field) is
+ * dispatched and MINIONS_DIR sits one level below a drive/filesystem root
+ * (e.g. `D:\squad`), `path.resolve(MINIONS_DIR, '..')` collapses to the drive
+ * root (`D:\`). The downstream worktree path then evaluates to `D:\worktrees\…`
+ * which IS inside `D:\`, so `assertWorktreeOutsideProject` correctly rejects it
+ * — but the dispatch loops forever because the throw happens in spawnAgent
+ * without surfacing as a non-retryable failure (W-mp62taw2000ubcc3).
+ *
+ * Detect the collapse explicitly here and throw with a clear, actionable code
+ * (`WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT`). Callers should map this to a
+ * non-retryable WORKTREE_PREFLIGHT failure so the dispatch fails fast instead
+ * of silently re-dispatching every tick.
+ *
+ * @param {string|null|undefined} localPath  — `project.localPath`, if any
+ * @param {string} minionsDir                — the MINIONS_DIR fallback anchor
+ * @returns {string}                         — absolute path to use as rootDir
+ * @throws {Error}                           — code WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT on collapse
+ */
+function resolveProjectRootDir(localPath, minionsDir) {
+  if (localPath) return path.resolve(String(localPath));
+  if (!minionsDir) {
+    const err = new Error('Cannot resolve project rootDir: no project.localPath and no MINIONS_DIR provided.');
+    err.code = 'WORKTREE_ROOTDIR_MISSING_BASE';
+    throw err;
+  }
+  const fallback = path.resolve(String(minionsDir), '..');
+  // path.parse(p).root === p means we hit the drive root (Windows `D:\`,
+  // POSIX `/`, or UNC `\\server\share\`). A drive root is never a legitimate
+  // project root for worktree placement — every sibling like `D:\worktrees\…`
+  // is technically "inside" the drive root and would be rejected.
+  if (path.parse(fallback).root === fallback) {
+    const err = new Error(
+      `Cannot resolve project rootDir for dispatch — MINIONS_DIR="${minionsDir}" parent collapses ` +
+      `to filesystem/drive root "${fallback}", which cannot host worktrees. ` +
+      `Either attach the work item to a project (POST /api/work-items with "project") or ` +
+      `move MINIONS_DIR deeper than one directory below the drive root.`
+    );
+    err.code = 'WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT';
+    throw err;
+  }
+  return fallback;
+}
+
+// ── Spawn cwd vs worktree placement (W-mp73x32w000l143d) ──────────────────────
+// Work types that don't need a git worktree — they read repo state but don't
+// produce code changes. Centralized here so engine.js spawnAgent and any
+// future caller (e.g. pipeline preflight) can share one definition.
+//
+// `docs` is intentionally NOT in this set: docs edits run at the Minions root
+// without a project worktree but ARE write-capable (they push commits to the
+// minions repo itself). It's the complement of WORKTREE_REQUIRING_TYPES minus
+// that one odd case.
+const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to-prd', 'plan']);
+
+/**
+ * Resolve the agent's working directory and (when needed) the parent dir for
+ * git worktree placement. Decouples the two concerns that spawnAgent used to
+ * conflate (W-mp73x32w000l143d):
+ *
+ *   1. **cwd** — where the agent process actually runs. For read-only types
+ *      this is the project root (or MINIONS_DIR fallback for rootless WIs).
+ *      For code-mutating types this is the worktree placement parent until
+ *      `git worktree add` succeeds, after which spawnAgent reassigns it to
+ *      the worktree path.
+ *
+ *   2. **worktreeRootDir** — the parent directory `git worktree add` is run
+ *      from. Only meaningful when a worktree will actually be created. For
+ *      read-only types we deliberately return `null` so the caller can skip
+ *      the drive-root preflight that fires when MINIONS_DIR sits one level
+ *      below a filesystem root (resolveProjectRootDir's collapse case).
+ *
+ * NOTE: Pipeline branches (engine.js `isPipelineBranchName`) override this —
+ * they always need a worktree even for read-only types because the worktree
+ * IS the pipeline's isolated workspace. The caller must detect the pipeline
+ * branch case and recompute worktreeRootDir via `resolveProjectRootDir`.
+ *
+ * @param {{ localPath?: string|null }|null|undefined} project
+ * @param {string} type — work type (e.g. 'fix', 'explore', 'meeting')
+ * @param {string} minionsDir — MINIONS_DIR fallback anchor
+ * @returns {{ cwd: string|null, worktreeRootDir: string|null }}
+ *   - For read-only types: { cwd: <project dir or MINIONS_DIR>, worktreeRootDir: null }
+ *   - For code-mutating types: { cwd: null, worktreeRootDir: <project root> }
+ *     (caller defaults cwd to worktreeRootDir before worktree creation)
+ * @throws {Error} WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT (code-mutating only)
+ *                 or WORKTREE_ROOTDIR_MISSING_BASE if neither anchor present.
+ */
+function resolveSpawnPaths(project, type, minionsDir) {
+  const isReadOnly = READ_ONLY_ROOT_TASK_TYPES.has(type);
+  if (isReadOnly) {
+    if (project?.localPath) return { cwd: path.resolve(String(project.localPath)), worktreeRootDir: null };
+    if (minionsDir) return { cwd: path.resolve(String(minionsDir)), worktreeRootDir: null };
+    const err = new Error('Cannot resolve cwd for read-only spawn: no project.localPath and no MINIONS_DIR provided.');
+    err.code = 'WORKTREE_ROOTDIR_MISSING_BASE';
+    throw err;
+  }
+  const worktreeRootDir = resolveProjectRootDir(project?.localPath, minionsDir);
+  return { cwd: null, worktreeRootDir };
+}
+
 // ── HTTP Origin Allowlist & Security Headers ─────────────────────────────────
 // Pure helpers used by dashboard.js to gate mutating requests against an
 // explicit allowlist of local origins and to attach uniform security response
@@ -3329,6 +3707,49 @@ function listAllProcesses() {
   return process.platform === 'win32' ? _winListProcesses() : _unixListProcesses();
 }
 
+// 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) {
@@ -3755,6 +4176,12 @@ module.exports = {
   exec,
   execAsync,
   execSilent,
+  shellSafeGh,
+  shellSafeGit,
+  shellSafeGitSync,
+  validateGitRef,
+  validateGhSlug,
+  isValidGitWorktree,
   resolveMainBranch,
   run,
   runFile,
@@ -3770,7 +4197,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, WORKTREE_REQUIRING_TYPES, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
@@ -3830,6 +4257,9 @@ module.exports = {
   isPathInsideOrEqual,
   parseWorktreePorcelain,
   assertWorktreeOutsideProject,
+  resolveProjectRootDir,
+  resolveSpawnPaths,
+  READ_ONLY_ROOT_TASK_TYPES,
   isLiveCommandCenterPath,
   describeCcProtectedPaths,
   renderCcSystemPrompt,
@@ -3855,6 +4285,7 @@ module.exports = {
   killImmediate,
   killByPidImmediate,
   killByPidsImmediate,
+  isProcessCommandLineMatchingAgent,
   listAllProcesses,
   listProcessDescendants,
   listProcessReachable,
@@ -3862,6 +4293,7 @@ module.exports = {
   _purgeReservedFiles, // exported for testing
   _WIN_RESERVED_NAMES, // exported for testing
   LOCK_STALE_MS,
+  isPidAlive,
   flushLogs,
   redactSecrets,
   slugify,

package/engine/spawn-agent.js

@@ -38,6 +38,7 @@ const path = require('path');
 const { runFile, cleanChildEnv, killGracefully, killImmediate, killByPidsImmediate, listProcessDescendants, ts, resolveEngineCacheDir } = require('./shared');
 const { resolveRuntime } = require('./runtimes');
 const { acquireAdoTokenSync, isLikelyAdoToken } = require('./ado-token');
+const keepProcessSweep = require('./keep-process-sweep');
 
 // ─── Pure helpers (exported for tests) ──────────────────────────────────────
 
@@ -534,8 +535,49 @@ function main() {
     if (trackedDescendants.size || gotFirstOutput) {
       snapshotDescendants();
       if (trackedDescendants.size) {
-        const reaped = killByPidsImmediate([...trackedDescendants]);
-        try { fs.appendFileSync(debugPath, `DESCENDANTS reaped=${reaped}/${trackedDescendants.size}\n`); } catch {}
+        // W-mp68q6ke0010de68 — opt-in keep_processes flag: agents whose work
+        // item carried `meta.keep_processes: true` may have written
+        // `agents/<id>/keep-pids.json` declaring specific descendant PIDs the
+        // engine MUST NOT reap. Resolve agentId from MINIONS_LIVE_OUTPUT_PATH
+        // (engine.js:1451 sets it to agents/<agentId>/live-output.log) and
+        // subtract validated, alive PIDs from the kill set. Missing or
+        // invalid file → fall through to today's behavior (reap everything).
+        let toKillPids = [...trackedDescendants];
+        let kept = [];
+        let keepRecord = null;
+        let keepReason = null;
+        try {
+          const liveOut = process.env.MINIONS_LIVE_OUTPUT_PATH;
+          const agentId = liveOut ? path.basename(path.dirname(liveOut)) : '';
+          if (agentId) {
+            // W-mp6k7ywi000fa33c — per-WI override (set by engine when
+            // meta.keep_processes_skip_workdir_check is true) bypasses the
+            // requireGitWorkdir check so legitimate non-git keep_processes
+            // use cases (e.g., a daemon under /tmp) still anchor.
+            const reapOpts = process.env.MINIONS_KEEP_PROCESSES_SKIP_WORKDIR_CHECK === '1'
+              ? { requireGitWorkdir: false }
+              : {};
+            const plan = keepProcessSweep.computeReapPlan(toKillPids, agentId, reapOpts);
+            toKillPids = plan.toKill;
+            kept = plan.kept;
+            keepRecord = plan.record;
+            keepReason = plan.reason;
+          }
+        } catch (e) {
+          try { fs.appendFileSync(debugPath, `KEEP-PIDS error: ${e.message}\n`); } catch {}
+        }
+        if (kept.length) {
+          try {
+            fs.appendFileSync(
+              debugPath,
+              `KEPT pids=[${kept.join(',')}] purpose="${(keepRecord?.purpose || '').slice(0, 200)}" wi=${keepRecord?.wi_id || ''}\n`,
+            );
+          } catch {}
+        } else if (keepReason) {
+          try { fs.appendFileSync(debugPath, `KEEP-PIDS skipped: ${keepReason}\n`); } catch {}
+        }
+        const reaped = toKillPids.length ? killByPidsImmediate(toKillPids) : 0;
+        try { fs.appendFileSync(debugPath, `DESCENDANTS reaped=${reaped}/${toKillPids.length} kept=${kept.length}\n`); } catch {}
       }
     }
     // Prefer the 'exit' event's code/signal when present — see note above.