@yemi33/minions 0.1.1949 → 0.1.1951

package/engine.js

@@ -23,6 +23,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const shared = require('./engine/shared');
 const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS,
   WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, DISPATCH_RESULT, AGENT_STATUS,
@@ -103,7 +104,9 @@ const mutatePullRequests = shared.mutatePullRequests;
 const withFileLock = shared.withFileLock;
 
 const CHECKPOINT_CAP_FAIL_REASON = 'Exceeded 3 checkpoint-resumes; manual intervention required';
-const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to-prd', 'plan']);
+// W-mp73x32w000l143d: shared.READ_ONLY_ROOT_TASK_TYPES is the canonical set;
+// re-aliased here for the existing call sites in this file.
+const READ_ONLY_ROOT_TASK_TYPES = shared.READ_ONLY_ROOT_TASK_TYPES;
 
 function isPipelineBranchName(branchName) {
   return typeof branchName === 'string' && branchName.startsWith('pipeline/');
@@ -123,6 +126,10 @@ const steering = require('./engine/steering');
 
 const { runCleanup } = require('./engine/cleanup');
 
+// ─── Worktree pool (W-mp73ya3e000me6c5 — opt-in cross-branch warm reuse) ────
+
+const worktreePool = require('./engine/worktree-pool');
+
 // ─── State Readers (delegated to engine/queries.js) ─────────────────────────
 
 const { getConfig, getControl, getDispatch, getNotes,
@@ -201,7 +208,7 @@ async function pruneAncestorDeps(deps, gitOpts, cwd) {
     for (let j = 0; j < deps.length; j++) {
       if (i === j || ancestorIndices.has(j)) continue;
       try {
-        await execAsync(`git merge-base --is-ancestor "origin/${deps[i].branch}" "origin/${deps[j].branch}"`, { ...gitOpts, cwd });
+        await shared.shellSafeGit(['merge-base', '--is-ancestor', `origin/${deps[i].branch}`, `origin/${deps[j].branch}`], { ...gitOpts, cwd });
         // deps[i] is an ancestor of deps[j] — prune deps[i]
         ancestorIndices.add(i);
         break;
@@ -221,14 +228,14 @@ async function preflightMergeSimulation(deps, mainRef, gitOpts, cwd) {
   for (let i = 0; i < deps.length; i++) {
     const depBranch = deps[i].branch;
     try {
-      const result = await execAsync(`git merge-tree --write-tree "${currentRef}" "origin/${depBranch}"`, { ...gitOpts, cwd });
+      const result = await shared.shellSafeGit(['merge-tree', '--write-tree', currentRef, `origin/${depBranch}`], { ...gitOpts, cwd });
       const treeSha = (typeof result === 'string' ? result : (result.stdout?.toString?.() || '')).trim().split('\n')[0];
       if (!treeSha) return { ok: true }; // can't parse tree SHA, skip pre-flight
       // Create temp commit to chain for next dep (skip for last dep — no chaining needed)
       if (i < deps.length - 1) {
         try {
-          const commitResult = await execAsync(
-            `git commit-tree "${treeSha}" -p "${currentRef}" -p "origin/${depBranch}" -m "preflight-merge"`,
+          const commitResult = await shared.shellSafeGit(
+            ['commit-tree', treeSha, '-p', currentRef, '-p', `origin/${depBranch}`, '-m', 'preflight-merge'],
             { ...gitOpts, cwd }
           );
           const commitSha = (typeof commitResult === 'string' ? commitResult : (commitResult.stdout?.toString?.() || '')).trim();
@@ -501,8 +508,8 @@ async function syncReusedWorktree(rootDir, worktreePath, branchName, gitOpts = {
   // even on slow links.
   let onOrigin = true;
   try {
-    await execAsync(
-      `git ls-remote --exit-code --heads origin "${branchName}"`,
+    await shared.shellSafeGit(
+      ['ls-remote', '--exit-code', '--heads', 'origin', branchName],
       { ...gitOpts, cwd: rootDir, timeout: 5000 },
     );
   } catch (e) {
@@ -515,15 +522,15 @@ async function syncReusedWorktree(rootDir, worktreePath, branchName, gitOpts = {
     log('info', `Branch ${branchName} not on origin yet — first push pending; skipping fetch/pull`);
     return { skipped: true, reason: 'no-upstream' };
   }
-  try { await execAsync(`git fetch origin "${branchName}"`, { ...gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
-  try { await execAsync(`git pull origin "${branchName}"`, { ...gitOpts, cwd: worktreePath }); } catch (e) { log('warn', 'git: ' + e.message); }
+  try { await shared.shellSafeGit(['fetch', 'origin', branchName], { ...gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
+  try { await shared.shellSafeGit(['pull', 'origin', branchName], { ...gitOpts, cwd: worktreePath }); } catch (e) { log('warn', 'git: ' + e.message); }
   return { skipped: false };
 }
 
 // Find an existing worktree already checked out on a given branch
 async function findExistingWorktree(repoDir, branchName) {
   try {
-    const out = await execAsync(`git worktree list --porcelain`, { cwd: repoDir, timeout: 10000 });
+    const out = await shared.shellSafeGit(['worktree', 'list', '--porcelain'], { cwd: repoDir, timeout: 10000 });
     const found = shared.parseWorktreePorcelain(out).find(w => w.branch === branchName);
     if (found && fs.existsSync(found.path)) return found.path;
   } catch (e) { log('warn', 'git: ' + e.message); }
@@ -553,17 +560,24 @@ function removeStaleIndexLock(rootDir) {
   } catch (e) { log('warn', 'git: ' + e.message); }
 }
 
-async function runWorktreeAdd(rootDir, worktreePath, args, gitOpts, worktreeCreateRetries) {
+async function runWorktreeAdd(rootDir, worktreePath, addArgs, gitOpts, worktreeCreateRetries) {
+  // P-a7c4d2e8 (F3): argv-form `git worktree add` — `addArgs` is an array of
+  // additional arguments (typically a branch name, optionally preceded by
+  // `-b <newBranch>`). The worktreePath is passed via `--` to disambiguate
+  // from refs and prevent option-style argument injection.
+  if (!Array.isArray(addArgs)) {
+    throw new TypeError('runWorktreeAdd: addArgs must be an array');
+  }
   let lastErr = null;
   const retries = Math.max(0, Number(worktreeCreateRetries) || 0);
   for (let attempt = 0; attempt <= retries; attempt++) {
     try {
       if (attempt > 0) {
-        try { await execAsync('git worktree prune', { ...gitOpts, cwd: rootDir, timeout: 15000 }); } catch (e) { log('warn', 'git: ' + e.message); }
+        try { await shared.shellSafeGit(['worktree', 'prune'], { ...gitOpts, cwd: rootDir, timeout: 15000 }); } catch (e) { log('warn', 'git: ' + e.message); }
         removeStaleIndexLock(rootDir);
         log('warn', `Retrying git worktree add (attempt ${attempt + 1}/${retries + 1}) for ${path.basename(worktreePath)}`);
       }
-      await execAsync(`git worktree add "${worktreePath}" ${args}`, { ...gitOpts, cwd: rootDir });
+      await shared.shellSafeGit(['worktree', 'add', worktreePath, ...addArgs], { ...gitOpts, cwd: rootDir });
       return;
     } catch (err) {
       lastErr = err;
@@ -584,7 +598,7 @@ async function pruneStaleWorktreeForBranch(rootDir, branchName, gitOpts) {
   if (!branchName) return 0;
   let trees = [];
   try {
-    const out = await execAsync(`git worktree list --porcelain`, { ...gitOpts, cwd: rootDir, timeout: 10000 });
+    const out = await shared.shellSafeGit(['worktree', 'list', '--porcelain'], { ...gitOpts, cwd: rootDir, timeout: 10000 });
     trees = shared.parseWorktreePorcelain(out);
   } catch (e) {
     log('warn', `pruneStaleWorktreeForBranch list: ${e.message?.split('\n')[0]}`);
@@ -595,14 +609,14 @@ async function pruneStaleWorktreeForBranch(rootDir, branchName, gitOpts) {
   let removed = 0;
   for (const w of stale) {
     try {
-      await execAsync(`git worktree remove -f -f "${w.path}"`, { ...gitOpts, cwd: rootDir, timeout: 15000 });
+      await shared.shellSafeGit(['worktree', 'remove', '-f', '-f', w.path], { ...gitOpts, cwd: rootDir, timeout: 15000 });
       removed++;
       log('warn', `Removed stale worktree entry for ${branchName} at missing path ${w.path}${w.locked ? ' (was locked)' : ''}`);
     } catch (e) {
       log('warn', `git worktree remove -f -f failed for stale ${w.path}: ${e.message?.split('\n')[0]}`);
     }
   }
-  try { await execAsync(`git worktree prune`, { ...gitOpts, cwd: rootDir, timeout: 10000 }); } catch { /* best-effort */ }
+  try { await shared.shellSafeGit(['worktree', 'prune'], { ...gitOpts, cwd: rootDir, timeout: 10000 }); } catch { /* best-effort */ }
   return removed;
 }
 
@@ -717,8 +731,8 @@ async function recoverPartialWorktree(rootDir, worktreePath, branchName, gitOpts
   if (existingWt && fs.existsSync(existingWt)) return true;
   if (!fs.existsSync(worktreePath)) return false;
   try {
-    await execAsync(`git -C "${worktreePath}" rev-parse --is-inside-work-tree`, { ...gitOpts, timeout: 10000 });
-    await execAsync(`git -C "${worktreePath}" rev-parse --abbrev-ref HEAD`, { ...gitOpts, timeout: 10000 });
+    await shared.shellSafeGit(['-C', worktreePath, 'rev-parse', '--is-inside-work-tree'], { ...gitOpts, timeout: 10000 });
+    await shared.shellSafeGit(['-C', worktreePath, 'rev-parse', '--abbrev-ref', 'HEAD'], { ...gitOpts, timeout: 10000 });
     log('warn', `Recovered partially-created worktree for ${branchName} at ${worktreePath}`);
     return true;
   } catch {
@@ -755,12 +769,73 @@ async function spawnAgent(dispatchItem, config) {
   }
   const metaProjectFields = metaProject && typeof metaProject === 'object' ? metaProject : {};
   const project = projectResolution.project ? { ...projectResolution.project, ...metaProjectFields } : {};
-  const rootDir = project.localPath ? path.resolve(project.localPath) : path.resolve(MINIONS_DIR, '..');
-
-  // Determine working directory
-  let cwd = rootDir;
+  // W-mp73x32w000l143d: decouple agent cwd from worktree placement.
+  // resolveSpawnPaths returns:
+  //   - read-only types: { cwd: <project dir or MINIONS_DIR>, worktreeRootDir: null }
+  //     (no drive-root preflight — these tasks don't need a worktree)
+  //   - code-mutating types: { cwd: null, worktreeRootDir: <project root> }
+  //     (caller defaults cwd to worktreeRootDir; drive-root collapse throws
+  //     WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT — same fail-fast behavior as
+  //     the legacy resolveProjectRootDir call this replaced).
+  // Pipeline branches force a worktree even for read-only types — handled
+  // immediately after the resolver call below.
+  const _preBranchName = meta?.branch ? sanitizeBranch(meta.branch) : null;
+  let cwd, worktreeRootDir;
+  try {
+    ({ cwd, worktreeRootDir } = shared.resolveSpawnPaths(project, type, MINIONS_DIR));
+  } catch (rootErr) {
+    if (rootErr?.code === 'WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT' || rootErr?.code === 'WORKTREE_ROOTDIR_MISSING_BASE') {
+      log('error', `spawnAgent: project rootDir resolution failed for ${id}: ${rootErr.message}`);
+      // Prompt files haven't been written yet at this point — no cleanup needed.
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        rootErr.message.slice(0, 800),
+        'Pre-spawn worktree preflight rejected — see failure_class for the specific cause.',
+        { failureClass: FAILURE_CLASS.WORKTREE_PREFLIGHT, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
+    throw rootErr;
+  }
+  // Pipeline branches need a worktree even for read-only types (the worktree
+  // IS the pipeline's isolated workspace). When we detect a pipeline branch
+  // on a read-only type, recompute worktreeRootDir so the worktree creation
+  // block has a placement parent — and so the drive-root preflight still fires.
+  if (worktreeRootDir === null && isPipelineBranchName(_preBranchName)) {
+    try {
+      worktreeRootDir = shared.resolveProjectRootDir(project.localPath, MINIONS_DIR);
+    } catch (rootErr) {
+      if (rootErr?.code === 'WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT' || rootErr?.code === 'WORKTREE_ROOTDIR_MISSING_BASE') {
+        log('error', `spawnAgent: pipeline-branch rootDir resolution failed for ${id}: ${rootErr.message}`);
+        completeDispatch(
+          id,
+          DISPATCH_RESULT.ERROR,
+          rootErr.message.slice(0, 800),
+          'Pre-spawn worktree preflight rejected — see failure_class for the specific cause.',
+          { failureClass: FAILURE_CLASS.WORKTREE_PREFLIGHT, agentRetryable: false },
+        );
+        cleanupTempAgent(agentId);
+        return null;
+      }
+      throw rootErr;
+    }
+  }
+  // Legacy local alias: downstream git ops (worktree add, prune, fetch) and
+  // the `cwd === rootDir` safety warn at line ~1387 reference `rootDir`. For
+  // read-only rootless tasks (no worktree, no branch) this is null — the
+  // rootDir-referencing code paths only run inside `if (branchName)` /
+  // `if (worktreePath)` guards, so a null rootDir is safe there.
+  const rootDir = worktreeRootDir;
+
+  // Determine working directory. For code-mutating types the resolver
+  // returned cwd: null and we default to the worktree placement parent
+  // (matches legacy behavior — reassigned to the worktreePath after
+  // `git worktree add` succeeds at line ~1078).
+  if (cwd == null) cwd = rootDir;
   let worktreePath = null;
-  let branchName = meta?.branch ? sanitizeBranch(meta.branch) : null;
+  let branchName = _preBranchName;
   const worktreeCreateTimeout = Math.max(60000, Number(engineConfig.worktreeCreateTimeout) || ENGINE_DEFAULTS.worktreeCreateTimeout);
   const worktreeCreateRetries = Math.max(0, Math.min(3, Number(engineConfig.worktreeCreateRetries) || ENGINE_DEFAULTS.worktreeCreateRetries));
   const _gitOpts = { stdio: 'pipe', timeout: 30000, windowsHide: true, env: shared.gitEnv() };
@@ -778,14 +853,24 @@ async function spawnAgent(dispatchItem, config) {
       safeUnlink(completionReportPath);
     } catch (e) { log('warn', `completion report setup: ${e.message}`); }
   }
+  // P-d2a8f6c1 (agent trust boundary F8): per-spawn cryptographic nonce. The
+  // engine injects this into the agent env as MINIONS_COMPLETION_NONCE and
+  // requires the agent to echo it back in the completion JSON. On parse, the
+  // engine compares report.nonce against the in-memory value below; on
+  // mismatch the report is treated as forged (e.g. a prompt-injected agent
+  // writing into a sibling agent's completion path) and discarded. See
+  // engine/lifecycle.js:runPostCompletionHooks and docs/completion-reports.md.
+  const completionNonce = crypto.randomBytes(16).toString('hex');
   const completionReportInstruction = completionReportPath ? [
     '## Completion Report',
     '',
     `Before exiting, write a JSON completion report to: \`${completionReportPath}\``,
     '',
-    'Use this shape: {"status":"success|partial|failed","summary":"...","verdict":"approved|changes-requested|null","pr":"PR URL or id if relevant","failure_class":"...","retryable":true|false,"needs_rerun":true|false,"artifacts":[{"type":"note|plan|prd|pr|file","path":"relative/path/or/url","title":"short label"}]}.',
+    'Use this shape: {"status":"success|partial|failed","summary":"...","verdict":"approved|changes-requested|null","pr":"PR URL or id if relevant","failure_class":"...","retryable":true|false,"needs_rerun":true|false,"nonce":"<value of MINIONS_COMPLETION_NONCE env var>","artifacts":[{"type":"note|plan|prd|pr|file","path":"relative/path/or/url","title":"short label"}]}.',
     'This report is the primary completion signal; fenced completion blocks are only a fallback.',
     '',
+    `**Trust nonce (REQUIRED):** copy the exact value of the \`MINIONS_COMPLETION_NONCE\` environment variable into the report's \`nonce\` field. The engine validates this on read; mismatched or missing nonces are treated as untrusted and the dispatch is failed with \`failure_class: 'completion-nonce-mismatch'\`. Do not invent, regenerate, or share this value across reports.`,
+    '',
   ].join('\n') : '';
   const buildFullTaskPrompt = (promptBody) => {
     const taskPromptWithSteering = pendingSteering.prompt
@@ -807,6 +892,22 @@ async function spawnAgent(dispatchItem, config) {
   const sysPromptPath = path.join(tmpDir, `sysprompt-${safeId}.md`);
   safeWrite(sysPromptPath, systemPrompt);
   const _cleanupPromptFiles = () => { safeUnlink(promptPath); safeUnlink(sysPromptPath); };
+  // Convert a WORKTREE_NESTED_IN_PROJECT throw into a fail-fast non-retryable
+  // dispatch failure (W-mp62taw2000ubcc3). The error's `.code` is set by
+  // shared.assertWorktreeOutsideProject so we don't have to parse the message.
+  // Returns truthy when the caller should `return null` from spawnAgent.
+  const _failWorktreePreflight = (assertErr) => {
+    log('error', `spawnAgent: worktree preflight rejected for ${id}: ${assertErr.message}`);
+    _cleanupPromptFiles();
+    completeDispatch(
+      id,
+      DISPATCH_RESULT.ERROR,
+      assertErr.message.slice(0, 800),
+      'Pre-spawn worktree preflight rejected — see failure_class for the specific cause. Recompute will produce the same rejection until the underlying configuration changes.',
+      { failureClass: FAILURE_CLASS.WORKTREE_PREFLIGHT, agentRetryable: false },
+    );
+    cleanupTempAgent(agentId);
+  };
   _phaseT.afterPrompt = Date.now();
 
   if (branchName) {
@@ -819,8 +920,13 @@ async function spawnAgent(dispatchItem, config) {
     worktreePath = path.resolve(rootDir, engineConfig.worktreeRoot || '../worktrees', wtDirName);
     // Refuse to spawn into a worktree path that's inside the project root —
     // nested worktrees cause glob/grep to match both copies (mirror writes).
-    // Throws on violation; caught by the outer try/catch which fails dispatch.
-    shared.assertWorktreeOutsideProject(worktreePath, rootDir);
+    // WORKTREE_NESTED_IN_PROJECT is non-retryable: the recompute on the next
+    // tick will produce the same path. Fail fast (W-mp62taw2000ubcc3).
+    try { shared.assertWorktreeOutsideProject(worktreePath, rootDir); }
+    catch (assertErr) {
+      if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
+      throw assertErr;
+    }
 
     // If branch is already checked out in an existing worktree, reuse it
     _phaseT.findExistingStart = Date.now();
@@ -830,7 +936,11 @@ async function spawnAgent(dispatchItem, config) {
       // Same guard for reuse — a previously-created bad worktree must not
       // be silently reused either; the cleanup sweep flags these so the
       // operator can remove them.
-      shared.assertWorktreeOutsideProject(existingWt, rootDir);
+      try { shared.assertWorktreeOutsideProject(existingWt, rootDir); }
+      catch (assertErr) {
+        if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
+        throw assertErr;
+      }
       worktreePath = existingWt;
       log('info', `Reusing existing worktree for ${branchName}: ${existingWt}`);
       // Probe origin first — locally-created branches that were never pushed
@@ -840,30 +950,84 @@ async function spawnAgent(dispatchItem, config) {
       await syncReusedWorktree(rootDir, existingWt, branchName, _gitOpts);
       _phaseT.reuseSyncEnd = Date.now();
     } else if (READ_ONLY_ROOT_TASK_TYPES.has(type) && !isPipelineBranchName(branchName)) {
-      // Read-only tasks — no worktree needed, run in rootDir
-      log('info', `${type}: read-only task, no worktree needed — running in rootDir`);
+      // Read-only tasks — no worktree needed, run in cwd from resolveSpawnPaths
+      // (project.localPath or MINIONS_DIR). W-mp73x32w000l143d.
+      log('info', `${type}: read-only task, no worktree needed — running in cwd ${cwd}`);
       branchName = null;
       worktreePath = null;
     } else {
       _phaseT.createWorktreeStart = Date.now();
+
+      // ── Pool borrow (W-mp73ya3e000me6c5) ────────────────────────────────
+      // Try to borrow a warm worktree from the per-project pool BEFORE the
+      // existing fresh-create path. Default-off (`worktreePoolSize: 0`); when
+      // enabled, this saves the cold install/build cost on heavy projects.
+      // Borrow only fires when the branch is brand-new (no upstream yet) so
+      // we don't disrupt fix-tasks targeting existing PR branches. Any git
+      // failure during the checkout evicts the entry and falls through to
+      // the unchanged fresh-create logic.
+      let borrowedFromPool = false;
+      const _isSharedForPool = meta?.branchStrategy === 'shared-branch' || meta?.useExistingBranch;
+      const _poolProject = project.name || 'default';
+      const _poolSize = worktreePool.getProjectPoolSize(_poolProject, config);
+      if (_poolSize > 0 && !_isSharedForPool && branchName) {
+        let _branchOnRemote = true;
+        try {
+          await shared.shellSafeGit(
+            ['ls-remote', '--exit-code', '--heads', 'origin', branchName],
+            { ..._gitOpts, cwd: rootDir, timeout: 5000 },
+          );
+        } catch (e) { if (e && e.code === 2) _branchOnRemote = false; }
+        if (!_branchOnRemote) {
+          const borrowed = worktreePool.tryBorrow(_poolProject, id);
+          if (borrowed && borrowed.path && fs.existsSync(borrowed.path)) {
+            try { shared.assertWorktreeOutsideProject(borrowed.path, rootDir); }
+            catch (assertErr) {
+              if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') {
+                worktreePool.evictEntry(borrowed.path, 'nested-in-project');
+                _failWorktreePreflight(assertErr); return null;
+              }
+              throw assertErr;
+            }
+            try {
+              const _mainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
+              await shared.shellSafeGit(['fetch', 'origin', _mainRef], { ..._gitOpts, cwd: rootDir, timeout: 30000 });
+              // -B force-creates/resets the branch so a stale local ref from a
+              // prior occupant does not block the checkout.
+              await shared.shellSafeGit(['checkout', '-B', branchName, `origin/${_mainRef}`], { ..._gitOpts, cwd: borrowed.path, timeout: 30000 });
+              worktreePath = borrowed.path;
+              borrowedFromPool = true;
+              log('info', `worktree-pool: borrowed warm worktree for ${_poolProject}/${branchName}: ${borrowed.path}`);
+            } catch (borrowErr) {
+              log('warn', `worktree-pool: borrow checkout failed for ${branchName} at ${borrowed.path}: ${borrowErr.message} — evicting and falling through to fresh create`);
+              worktreePool.evictEntry(borrowed.path, 'borrow-checkout-failed');
+            }
+          }
+        }
+      }
+
       try {
         if (!fs.existsSync(worktreePath)) {
           const isSharedBranch = meta?.branchStrategy === 'shared-branch' || meta?.useExistingBranch;
           // Prune stale worktree entries before creating (handles leftover entries from crashed runs)
-          try { await execAsync(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
+          try { await shared.shellSafeGit(['worktree', 'prune'], { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
           // Remove stale index.lock before creating worktree (Windows crashes can leave this behind)
           removeStaleIndexLock(rootDir);
 
           if (isSharedBranch) {
             log('info', `Creating worktree for shared branch: ${worktreePath} on ${branchName}`);
-            try { await execAsync(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
+            try { await shared.shellSafeGit(['fetch', 'origin', branchName], { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
             try {
-              await runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
+              await runWorktreeAdd(rootDir, worktreePath, [branchName], _worktreeGitOpts, worktreeCreateRetries);
             } catch (eShared) {
               if (eShared.message?.includes('already used by worktree') || eShared.message?.includes('already checked out')) {
                 const existingWtPath = await findExistingWorktree(rootDir, branchName);
                 if (existingWtPath && fs.existsSync(existingWtPath)) {
-                  shared.assertWorktreeOutsideProject(existingWtPath, rootDir);
+                  try { shared.assertWorktreeOutsideProject(existingWtPath, rootDir); }
+                  catch (assertErr) {
+                    if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
+                    throw assertErr;
+                  }
                   log('info', `Shared branch ${branchName} already checked out at ${existingWtPath} — reusing`);
                   worktreePath = existingWtPath;
                 } else {
@@ -873,42 +1037,42 @@ async function spawnAgent(dispatchItem, config) {
                   const pruned = await pruneStaleWorktreeForBranch(rootDir, branchName, _gitOpts);
                   if (pruned > 0) {
                     log('info', `Pruned ${pruned} stale worktree entry(ies) for shared branch ${branchName}; retrying worktree add`);
-                    await runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, 0);
+                    await runWorktreeAdd(rootDir, worktreePath, [branchName], _worktreeGitOpts, 0);
                   } else { throw eShared; }
                 }
               } else if (eShared.message?.includes('invalid reference') || eShared.message?.includes('not a valid ref')) {
                 // Branch doesn't exist yet (first item in plan) — create it from main
                 const mainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
                 log('info', `Shared branch ${branchName} not found — creating from ${mainRef}`);
-                await runWorktreeAdd(rootDir, worktreePath, `-b "${branchName}" ${mainRef}`, _worktreeGitOpts, worktreeCreateRetries);
+                await runWorktreeAdd(rootDir, worktreePath, ['-b', branchName, mainRef], _worktreeGitOpts, worktreeCreateRetries);
               } else { throw eShared; }
             }
           } else {
             log('info', `Creating worktree: ${worktreePath} on branch ${branchName}`);
             const mainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
             try {
-              await runWorktreeAdd(rootDir, worktreePath, `-b "${branchName}" ${mainRef}`, _worktreeGitOpts, worktreeCreateRetries);
+              await runWorktreeAdd(rootDir, worktreePath, ['-b', branchName, mainRef], _worktreeGitOpts, worktreeCreateRetries);
             } catch (e1) {
               const branchExists = e1.message?.includes('already exists');
               log('warn', `Worktree -b failed for ${branchName}: ${e1.message?.split('\n')[0]}`);
               if (!branchExists) {
                 // Transient error (lock, timeout) — prune, clean, and retry -b once more
                 log('info', `Retrying -b create after prune for ${branchName}`);
-                try { await execAsync(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 15000 }); } catch { /* optional */ }
+                try { await shared.shellSafeGit(['worktree', 'prune'], { ..._gitOpts, cwd: rootDir, timeout: 15000 }); } catch { /* optional */ }
                 removeStaleIndexLock(rootDir);
                 // Clean up partial worktree directory from failed attempt
                 try { if (fs.existsSync(worktreePath)) fs.rmSync(worktreePath, { recursive: true, force: true }); } catch { /* optional */ }
                 try {
-                  await runWorktreeAdd(rootDir, worktreePath, `-b "${branchName}" ${mainRef}`, _worktreeGitOpts, 0);
+                  await runWorktreeAdd(rootDir, worktreePath, ['-b', branchName, mainRef], _worktreeGitOpts, 0);
                 } catch (e1b) {
                   log('error', `Worktree -b retry also failed for ${branchName}: ${e1b.message?.split('\n')[0]}`);
                   throw e1b;
                 }
               } else {
                 // Branch already exists — try checkout without -b
-                try { await execAsync(`git fetch origin "${branchName}"`, { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
+                try { await shared.shellSafeGit(['fetch', 'origin', branchName], { ..._gitOpts, cwd: rootDir }); } catch (e) { log('warn', 'git: ' + e.message); }
                 try {
-                  await runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
+                  await runWorktreeAdd(rootDir, worktreePath, [branchName], _worktreeGitOpts, worktreeCreateRetries);
                   log('info', `Reusing existing branch: ${branchName}`);
                 } catch (e2) {
                   // "already checked out" or "already used by worktree" — find and reuse or recover
@@ -930,17 +1094,21 @@ async function spawnAgent(dispatchItem, config) {
                         log('warn', `Branch ${branchName} actively used by another agent at ${existingWtPath} — cannot create worktree`);
                         throw e2;
                       }
-                      shared.assertWorktreeOutsideProject(existingWtPath, rootDir);
+                      try { shared.assertWorktreeOutsideProject(existingWtPath, rootDir); }
+                      catch (assertErr) {
+                        if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
+                        throw assertErr;
+                      }
                       log('info', `Branch ${branchName} already checked out at ${existingWtPath} — reusing`);
                       worktreePath = existingWtPath;
                     } else if (existingWtPath && !fs.existsSync(existingWtPath)) {
                       log('warn', `Branch ${branchName} tracked in missing dir ${existingWtPath} — pruning and recreating`);
-                      try { await execAsync(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
-                      await runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
+                      try { await shared.shellSafeGit(['worktree', 'prune'], { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
+                      await runWorktreeAdd(rootDir, worktreePath, [branchName], _worktreeGitOpts, worktreeCreateRetries);
                       log('info', `Recovered worktree for ${branchName} after stale entry prune`);
                     } else {
-                      try { await execAsync(`git worktree prune`, { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
-                      await runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, worktreeCreateRetries);
+                      try { await shared.shellSafeGit(['worktree', 'prune'], { ..._gitOpts, cwd: rootDir, timeout: 10000 }); } catch (e) { log('warn', 'git: ' + e.message); }
+                      await runWorktreeAdd(rootDir, worktreePath, [branchName], _worktreeGitOpts, worktreeCreateRetries);
                     }
                   } else {
                     throw e2;
@@ -951,7 +1119,7 @@ async function spawnAgent(dispatchItem, config) {
           }
         } else if (meta?.branchStrategy === 'shared-branch') {
           log('info', `Pulling latest on shared branch ${branchName}`);
-          try { await execAsync(`git pull origin "${branchName}"`, { ..._gitOpts, cwd: worktreePath }); } catch (e) { log('warn', 'git: ' + e.message); }
+          try { await shared.shellSafeGit(['pull', 'origin', branchName], { ..._gitOpts, cwd: worktreePath }); } catch (e) { log('warn', 'git: ' + e.message); }
         }
       } catch (err) {
         if (await recoverPartialWorktree(rootDir, worktreePath, branchName, _gitOpts)) {
@@ -1027,7 +1195,7 @@ async function spawnAgent(dispatchItem, config) {
           }
           const fetchResults = await Promise.allSettled(
             fetchable.map(({ branch: depBranch }) =>
-              execAsync(`git fetch origin "${depBranch}"`, { ..._gitOpts, cwd: rootDir }).then(() => depBranch)
+              shared.shellSafeGit(['fetch', 'origin', depBranch], { ..._gitOpts, cwd: rootDir }).then(() => depBranch)
             )
           );
           const hasFetchFailures = fetchResults.some(r => r.status === 'rejected');
@@ -1047,10 +1215,10 @@ async function spawnAgent(dispatchItem, config) {
               // If remote ref missing, check if branch exists locally and push it (#782)
               if (errMsg.includes('couldn\'t find remote ref') || errMsg.includes('not found in upstream')) {
                 try {
-                  await execAsync(`git rev-parse --verify "refs/heads/${failedBranch}"`, { ..._gitOpts, cwd: rootDir });
+                  await shared.shellSafeGit(['rev-parse', '--verify', `refs/heads/${failedBranch}`], { ..._gitOpts, cwd: rootDir });
                   // Branch exists locally — push it to origin
                   log('info', `Dependency ${failedBranch} exists locally but not on remote — pushing to origin`);
-                  await execAsync(`git push origin "${failedBranch}"`, { ..._gitOpts, cwd: rootDir, timeout: 60000 });
+                  await shared.shellSafeGit(['push', 'origin', failedBranch], { ..._gitOpts, cwd: rootDir, timeout: 60000 });
                   log('info', `Successfully pushed local-only dependency branch ${failedBranch} to origin`);
                   recoveredBranches.add(failedBranch);
                   continue;
@@ -1089,7 +1257,7 @@ async function spawnAgent(dispatchItem, config) {
             const ancestorChecks = await Promise.all(
               prunedDeps.map(async ({ branch: depBranch }) => {
                 try {
-                  await execAsync(`git merge-base --is-ancestor "origin/${depBranch}" HEAD`, { ..._gitOpts, cwd: worktreePath });
+                  await shared.shellSafeGit(['merge-base', '--is-ancestor', `origin/${depBranch}`, 'HEAD'], { ..._gitOpts, cwd: worktreePath });
                   return true;
                 } catch (_) { return false; }
               })
@@ -1122,9 +1290,9 @@ async function spawnAgent(dispatchItem, config) {
           let stashed = false;
           if (!depMergeFailed && !skipDepMerge && prunedDeps.length > 0) {
             try {
-              const statusOut = (await execAsync('git status --porcelain', { ..._gitOpts, cwd: worktreePath })).stdout.toString().trim();
+              const statusOut = (await shared.shellSafeGit(['status', '--porcelain'], { ..._gitOpts, cwd: worktreePath })).stdout.toString().trim();
               if (statusOut) {
-                await execAsync('git stash push --include-untracked -m "engine: stash before dep re-merge"', { ..._gitOpts, cwd: worktreePath });
+                await shared.shellSafeGit(['stash', 'push', '--include-untracked', '-m', 'engine: stash before dep re-merge'], { ..._gitOpts, cwd: worktreePath });
                 stashed = true;
                 log('info', `Stashed uncommitted changes in ${branchName} before dep merge`);
               }
@@ -1135,27 +1303,27 @@ async function spawnAgent(dispatchItem, config) {
           if (!depMergeFailed && !skipDepMerge) {
             for (const { branch: depBranch, prId } of prunedDeps) {
               try {
-                await execAsync(`git merge "origin/${depBranch}" --no-edit`, { ..._gitOpts, cwd: worktreePath });
+                await shared.shellSafeGit(['merge', `origin/${depBranch}`, '--no-edit'], { ..._gitOpts, cwd: worktreePath });
                 log('info', `Merged dependency branch ${depBranch} (${prId}) into worktree ${branchName}`);
               } catch (mergeErr) {
                 // Merge failed — possibly due to diverged history from a force-pushed (rebased) dep branch.
                 // Abort partial merge, reset worktree to clean main base, and re-merge all deps from scratch.
                 log('warn', `Merge of ${depBranch} into ${branchName} failed: ${mergeErr.message} — attempting reset and re-merge of all deps`);
-                try { await execAsync(`git merge --abort`, { ..._gitOpts, cwd: worktreePath }); } catch (_) { /* no merge in progress */ }
+                try { await shared.shellSafeGit(['merge', '--abort'], { ..._gitOpts, cwd: worktreePath }); } catch (_) { /* no merge in progress */ }
                 const mainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
                 try {
-                  await execAsync(`git reset --hard "origin/${mainRef}"`, { ..._gitOpts, cwd: worktreePath });
+                  await shared.shellSafeGit(['reset', '--hard', `origin/${mainRef}`], { ..._gitOpts, cwd: worktreePath });
                   log('info', `Reset worktree ${branchName} to origin/${mainRef} for clean dep re-merge`);
                   // Re-merge ALL pruned dep branches from scratch on clean base
                   for (const { branch: reBranch, prId: rePrId } of prunedDeps) {
-                    await execAsync(`git merge "origin/${reBranch}" --no-edit`, { ..._gitOpts, cwd: worktreePath });
+                    await shared.shellSafeGit(['merge', `origin/${reBranch}`, '--no-edit'], { ..._gitOpts, cwd: worktreePath });
                     log('info', `Re-merged dependency branch ${reBranch} (${rePrId}) into worktree ${branchName}`);
                   }
                   log('info', `Successfully re-merged all ${prunedDeps.length} dep branches after reset for ${branchName}`);
                 } catch (resetErr) {
                   const errOutput = (resetErr.message || '') + '\n' + (resetErr.stdout?.toString?.() || '') + '\n' + (resetErr.stderr?.toString?.() || '');
                   log('warn', `Failed to reset and re-merge deps for ${branchName}: ${resetErr.message}`);
-                  try { await execAsync(`git merge --abort`, { ..._gitOpts, cwd: worktreePath }); } catch (_) { /* no merge in progress */ }
+                  try { await shared.shellSafeGit(['merge', '--abort'], { ..._gitOpts, cwd: worktreePath }); } catch (_) { /* no merge in progress */ }
                   // Post-mortem: incremental simulation to identify which dep caused the conflict (#958)
                   // Uses same chained merge-tree approach as pre-flight to catch inter-dep conflicts
                   const pmMainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
@@ -1172,8 +1340,8 @@ async function spawnAgent(dispatchItem, config) {
                     for (const { branch: reBranch2 } of prunedDeps) {
                       try {
                         const mainRef2 = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
-                        const mergeBase = (await execAsync(`git merge-base "origin/${mainRef2}" "origin/${reBranch2}"`, { ..._gitOpts, cwd: rootDir })).stdout.toString().trim();
-                        const treeResult = await execAsync(`git merge-tree "${mergeBase}" "origin/${mainRef2}" "origin/${reBranch2}"`, { ..._gitOpts, cwd: rootDir });
+                        const mergeBase = (await shared.shellSafeGit(['merge-base', `origin/${mainRef2}`, `origin/${reBranch2}`], { ..._gitOpts, cwd: rootDir })).stdout.toString().trim();
+                        const treeResult = await shared.shellSafeGit(['merge-tree', mergeBase, `origin/${mainRef2}`, `origin/${reBranch2}`], { ..._gitOpts, cwd: rootDir });
                         const treeOutput = treeResult.stdout?.toString?.() || '';
                         if (treeOutput.includes('<<<<<<<') || treeOutput.includes('changed in both')) {
                           depConflictBranch = reBranch2;
@@ -1196,7 +1364,7 @@ async function spawnAgent(dispatchItem, config) {
           // Restore stashed changes after dep merge (#973)
           if (stashed) {
             try {
-              await execAsync('git stash pop', { ..._gitOpts, cwd: worktreePath });
+              await shared.shellSafeGit(['stash', 'pop'], { ..._gitOpts, cwd: worktreePath });
               log('info', `Restored stashed changes in ${branchName} after dep merge`);
             } catch (popErr) {
               log('warn', `git stash pop failed in ${branchName}: ${popErr.message} — stash preserved for agent`);
@@ -1407,7 +1575,16 @@ async function spawnAgent(dispatchItem, config) {
   // Spawn the claude process
   const childEnv = shared.cleanChildEnv();
   if (completionReportPath) childEnv.MINIONS_COMPLETION_REPORT = completionReportPath;
+  if (completionNonce) childEnv.MINIONS_COMPLETION_NONCE = completionNonce;
   childEnv.MINIONS_REPO_HOST = getRepoHost(project);
+  // W-mp6k7ywi000fa33c — per-WI override that bypasses the requireGitWorkdir
+  // check on agents/<id>/keep-pids.json. Plumbed via env so spawn-agent's
+  // close handler (which runs in the subprocess and computes the reap plan)
+  // can honor it without re-reading the WI meta.
+  if (meta?.item?.meta?.keep_processes_skip_workdir_check
+      || dispatchItem.meta?.keep_processes_skip_workdir_check) {
+    childEnv.MINIONS_KEEP_PROCESSES_SKIP_WORKDIR_CHECK = '1';
+  }
 
   if (getRepoHost(project) === 'ado') {
     // Inject cached ADO token so ADO agents skip re-authentication (#998).
@@ -1445,18 +1622,30 @@ async function spawnAgent(dispatchItem, config) {
     }
   } catch { /* rotation is best-effort — overwrite still happens below */ }
 
-  // Stamp the log synchronously before spawn. If the synchronous write throws,
-  // we still attempt to spawn (log-file stamp failure must not block the agent),
-  // but we note it so the diagnostic trail isn't silent either.
+  // Setup-and-spawn block guarded by partial-setup cleanup (P-f4d2e8a1).
+  // If anything between log-stamping and activeProcesses.set throws, the
+  // catch below tears down every artifact we managed to create so the work
+  // item isn't left "stuck active" with an orphan PID file, log fd, or
+  // realActivityMap entry. The dispatch loop's existing null-return /
+  // throw handler (engine.js ~5184) already re-queues the work item;
+  // here we just guarantee in-memory + on-disk state is consistent.
+  let pidFilePath, logFd, registeredInActivityMap, registeredInActiveProcesses, proc;
+  // The PID file at this path is written asynchronously by the spawned
+  // child (engine/spawn-agent.js:423) once it starts. We compute the path
+  // upfront so the catch block can unlink it whether spawn fails before
+  // the child wrote it (no-op) or after (real cleanup).
+  pidFilePath = promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid');
   try {
-    safeWrite(liveOutputPath, `# Live output for ${agentId} — ${id}\n# Started: ${startedAt}\n# Task: ${dispatchItem.task}\n[${new Date().toISOString()}] spawn: agent=${agentId} item=${id}\n\n`);
-  } catch (stubErr) {
-    log('warn', `Failed to stamp live-output stub for ${agentId} (${id}): ${stubErr.message}`);
-  }
+    // Stamp the log synchronously before spawn. If the synchronous write throws,
+    // we still attempt to spawn (log-file stamp failure must not block the agent),
+    // but we note it so the diagnostic trail isn't silent either.
+    try {
+      safeWrite(liveOutputPath, `# Live output for ${agentId} — ${id}\n# Started: ${startedAt}\n# Task: ${dispatchItem.task}\n[${new Date().toISOString()}] spawn: agent=${agentId} item=${id}\n\n`);
+    } catch (stubErr) {
+      log('warn', `Failed to stamp live-output stub for ${agentId} (${id}): ${stubErr.message}`);
+    }
 
-  let proc;
-  _phaseT.spawnCallStart = Date.now();
-  try {
+    _phaseT.spawnCallStart = Date.now();
     // `detached: true` puts the agent in its own process group (POSIX) / job
     // object (Windows), so when the engine dies — gracefully via stop, abruptly
     // via taskkill, or because of a crash — the agent keeps running and can be
@@ -1470,41 +1659,65 @@ async function spawnAgent(dispatchItem, config) {
       detached: true,
     });
     _phaseT.spawnCallEnd = Date.now();
+
+    // Seed realActivityMap and stamp PID immediately — BEFORE any handlers (#W-mo25loq8kjer).
+    // Why NOW, not later in the function:
+    //  1. Error-handler race. The `proc.on('error', ...)` handler below calls realActivityMap.delete(id)
+    //     on synchronous spawn failures. Seeding before registering handlers ensures delete sees a value
+    //     to clear rather than leaving an absent-then-absent no-op that downstream code must guard.
+    //  2. Orphan diagnostics. The PID line gives timeout.js a deterministic way to tell "spawn died
+    //     before first write" (stub-only log) from "process started and is hung" (stub + pid line).
+    realActivityMap.set(id, Date.now());
+    registeredInActivityMap = true;
+    try {
+      fs.appendFileSync(liveOutputPath, `[${new Date().toISOString()}] pid: ${proc.pid ?? 'unknown'}\n`);
+    } catch { /* log stamp is best-effort — don't block spawn on fs failure */ }
+
+    const initialProcInfo = {
+      proc,
+      agentId,
+      startedAt,
+      runtimeName,
+      sessionId: cachedSessionId,
+      _completionNonce: completionNonce,
+      ...(cachedSessionId ? {
+        _runtimeResumeAt: Date.now(),
+        _runtimeResumeAwaitingFirstOutput: true,
+      } : {}),
+      _pendingSteeringFiles: pendingSteering.entries,
+    };
+    activeProcesses.set(id, initialProcInfo);
+    registeredInActiveProcesses = true;
   } catch (spawnErr) {
-    // Synchronous spawn failure — record it to the (already-stamped) log so the
-    // orphan detector's "logSize > stub-only" check can tell this apart from a
-    // hung process. Then rethrow so the dispatch loop handles it normally.
-    try { fs.appendFileSync(liveOutputPath, `[${new Date().toISOString()}] spawn-failed: ${spawnErr.message}\n[process-exit] spawn-failed\n`); } catch { /* cleanup-only best effort */ }
+    // Partial-setup cleanup (P-f4d2e8a1): tear down every artifact in the
+    // reverse order it was created. Each step is conditional + best-effort
+    // so cleanup itself never throws on top of the original error.
+    if (proc === undefined) {
+      // Synchronous spawn failure — record it to the (already-stamped) log so the
+      // orphan detector's "logSize > stub-only" check can tell this apart from a
+      // hung process. Preserves the diagnostic the prior inline catch wrote.
+      try { fs.appendFileSync(liveOutputPath, `[${new Date().toISOString()}] spawn-failed: ${spawnErr.message}\n[process-exit] spawn-failed\n`); } catch { /* cleanup-only best effort */ }
+    } else if (proc && typeof proc.kill === 'function') {
+      // spawn() returned a handle but a later registration step threw —
+      // kill the orphan child so it doesn't run unmonitored.
+      try { proc.kill('SIGKILL'); } catch { /* already exited */ }
+    }
+    if (registeredInActiveProcesses) {
+      try { activeProcesses.delete(id); } catch { /* map.delete never throws but be defensive */ }
+    }
+    if (registeredInActivityMap) {
+      try { realActivityMap.delete(id); } catch { /* defensive */ }
+    }
+    if (logFd !== undefined) {
+      try { fs.closeSync(logFd); } catch { /* fd may already be closed */ }
+    }
+    if (pidFilePath) {
+      try { safeUnlink(pidFilePath); } catch { /* may not exist yet */ }
+    }
     cleanupTempAgent(agentId);
     throw spawnErr;
   }
 
-  // Seed realActivityMap and stamp PID immediately — BEFORE any handlers (#W-mo25loq8kjer).
-  // Why NOW, not later in the function:
-  //  1. Error-handler race. The `proc.on('error', ...)` handler below calls realActivityMap.delete(id)
-  //     on synchronous spawn failures. Seeding before registering handlers ensures delete sees a value
-  //     to clear rather than leaving an absent-then-absent no-op that downstream code must guard.
-  //  2. Orphan diagnostics. The PID line gives timeout.js a deterministic way to tell "spawn died
-  //     before first write" (stub-only log) from "process started and is hung" (stub + pid line).
-  realActivityMap.set(id, Date.now());
-  try {
-    fs.appendFileSync(liveOutputPath, `[${new Date().toISOString()}] pid: ${proc.pid ?? 'unknown'}\n`);
-  } catch { /* log stamp is best-effort — don't block spawn on fs failure */ }
-
-  const initialProcInfo = {
-    proc,
-    agentId,
-    startedAt,
-    runtimeName,
-    sessionId: cachedSessionId,
-    ...(cachedSessionId ? {
-      _runtimeResumeAt: Date.now(),
-      _runtimeResumeAwaitingFirstOutput: true,
-    } : {}),
-    _pendingSteeringFiles: pendingSteering.entries,
-  };
-  activeProcesses.set(id, initialProcInfo);
-
   // Emit per-phase timing for spawn-latency analysis. One structured line per
   // dispatch; grep `[spawn-timing]` to aggregate. Null phases didn't run for
   // this dispatch (e.g. stale_head only runs for fix tasks; dep_* only when
@@ -1677,6 +1890,10 @@ async function spawnAgent(dispatchItem, config) {
       const spawnScript = path.join(ENGINE_DIR, 'spawn-agent.js');
       const childEnv = shared.cleanChildEnv();
       if (completionReportPath) childEnv.MINIONS_COMPLETION_REPORT = completionReportPath;
+      // P-d2a8f6c1: preserve the per-dispatch nonce across steering resume so
+      // the agent's completion JSON still validates after the resumed turn.
+      // The dispatch id is the unit of trust, not the spawn instance.
+      if (completionNonce) childEnv.MINIONS_COMPLETION_NONCE = completionNonce;
       childEnv.MINIONS_LIVE_OUTPUT_PATH = liveOutputPath;
       childEnv.MINIONS_REPO_HOST = getRepoHost(project);
       if (getRepoHost(project) === 'ado') {
@@ -1686,6 +1903,11 @@ async function spawnAgent(dispatchItem, config) {
           if (adoToken) childEnv.MINIONS_ADO_TOKEN = adoToken;
         } catch { /* non-fatal */ }
       }
+      // W-mp6k7ywi000fa33c — propagate keep_processes workdir-check override across steering resume.
+      if (dispatchItem.meta?.item?.meta?.keep_processes_skip_workdir_check
+          || dispatchItem.meta?.keep_processes_skip_workdir_check) {
+        childEnv.MINIONS_KEEP_PROCESSES_SKIP_WORKDIR_CHECK = '1';
+      }
       let resumeProc;
       try {
         // detached so the resumed steering session also survives engine death (matches initial spawn)
@@ -1716,6 +1938,8 @@ async function spawnAgent(dispatchItem, config) {
         startedAt: procInfo.startedAt,
         runtimeName,
         sessionId: steerSessionId,
+        // P-d2a8f6c1: keep the per-dispatch nonce alive across the steering resume.
+        _completionNonce: procInfo._completionNonce || completionNonce,
         _runtimeResumeAt: Date.now(),
         _runtimeResumeAwaitingFirstOutput: true,
         _pendingSteeringFiles: mergePendingSteeringEntries(
@@ -1851,30 +2075,127 @@ async function spawnAgent(dispatchItem, config) {
     }
 
     // Parse output and run all post-completion hooks
-    const { resultSummary, autoRecovered, completionContractFailure, structuredCompletion, agentReportedFailure, agentRetryable } = await runPostCompletionHooks(dispatchItem, agentId, code, stdout, config);
+    // P-d2a8f6c1: hand the per-spawn nonce to lifecycle so it can validate the
+    // report's `nonce` field. Read it from activeProcesses BEFORE any later
+    // delete clears the entry.
+    const expectedNonce = activeProcesses.get(id)?._completionNonce || null;
+    const completionNonceRequired = engineConfig.completionNonceRequired ?? ENGINE_DEFAULTS.completionNonceRequired;
+    const { resultSummary, autoRecovered, completionContractFailure, structuredCompletion, agentReportedFailure, agentRetryable, nonceMismatch } = await runPostCompletionHooks(dispatchItem, agentId, code, stdout, config, { expectedNonce, completionNonceRequired });
     const retryableDecision = typeof agentRetryable === 'boolean' ? agentRetryable : failureInfo.retryable;
 
+    // W-mp6k7ywi000fa33c — keep_processes acceptance gate. When the work
+    // item carried `meta.keep_processes: true` and produced a keep-pids.json
+    // sidecar whose `cwd` does not look like a real git worktree (default
+    // `requireGitWorkdir: true` in ENGINE_DEFAULTS.keepProcesses), reject
+    // the file and force the dispatch to fail with a dedicated failure
+    // class. spawn-agent's close handler has already reaped the kept PIDs
+    // (the same validation runs there via computeReapPlan), so the engine's
+    // job here is just (a) flip the dispatch outcome to ERROR, (b) emit an
+    // inbox alert that the responsible agent will see on its next dispatch,
+    // and (c) delete the now-rejected sidecar so it does not accumulate.
+    //
+    // Per-WI override: `meta.keep_processes_skip_workdir_check: true` skips
+    // the gate entirely (legitimate non-git keep_processes use cases).
+    let keepProcessesWorkdirFailure = null;
+    {
+      const _wiMeta = dispatchItem.meta?.item?.meta || {};
+      const _kpEnabled = !!_wiMeta.keep_processes
+        || !!dispatchItem.meta?.keep_processes;
+      const _kpSkipWorkdir = !!_wiMeta.keep_processes_skip_workdir_check
+        || !!dispatchItem.meta?.keep_processes_skip_workdir_check;
+      if (_kpEnabled && !_kpSkipWorkdir && ENGINE_DEFAULTS.keepProcesses?.requireGitWorkdir !== false) {
+        try {
+          const keepProcessSweep = require('./engine/keep-process-sweep');
+          const evalResult = keepProcessSweep.evaluateKeepPidsAcceptance(agentId, { requireGitWorkdir: true });
+          if (evalResult.exists && evalResult.isWorkdirRejection) {
+            keepProcessesWorkdirFailure = {
+              reason: evalResult.reason,
+              cwd: evalResult.recordedCwd || '',
+              filePath: evalResult.filePath,
+            };
+            // Delete the sidecar so it does not anchor stale PIDs on later
+            // sweeps and does not show up as "malformed" forever.
+            try { fs.unlinkSync(evalResult.filePath); } catch (_e) { /* gone or busy */ }
+            log('warn', `keep-processes acceptance: REJECTED ${agentId} (${id}) — ${evalResult.reason}; PIDs reaped by spawn-agent, sidecar deleted`);
+            // Emit inbox alert so the agent sees this on its next turn.
+            try {
+              const wiId = dispatchItem.meta?.item?.id || '';
+              const slug = `keep-processes-workdir-${agentId}`;
+              const alertBody = [
+                `# keep_processes setup REJECTED for ${agentId}`,
+                '',
+                `Your kept-PIDs setup at \`${evalResult.recordedCwd || '<unknown>'}\` failed validation: ${evalResult.reason}.`,
+                'The directory is not a git worktree. PIDs were NOT protected and will be reaped.',
+                '',
+                wiId ? `Work item: ${wiId}` : '',
+                `Agent: ${agentId}`,
+                `Dispatch: ${id}`,
+                '',
+                'Why this matters: a keep_processes work item that runs in a non-git directory',
+                'is almost always a partial copy of a repo (a selective `cp -r`). The Minions',
+                'cleanup sweep cannot reason about such directories safely; later sweeps may',
+                'rmSync subdirs treating them as separate worktrees. Re-run the work item',
+                'inside a real `git worktree add` directory, or set',
+                '`meta.keep_processes_skip_workdir_check: true` on the work item if you',
+                'genuinely intend to keep PIDs alive in a non-git directory.',
+                '',
+              ].join('\n');
+              writeInboxAlert(slug, alertBody);
+            } catch (alertErr) {
+              log('warn', `keep-processes acceptance: failed to emit inbox alert for ${agentId}: ${alertErr.message}`);
+            }
+          } else if (evalResult.exists && !evalResult.accepted) {
+            // Non-workdir validation failure (oversize pids, bad TTL, etc.) —
+            // already handled by validateKeepPidsRecord; just log for audit.
+            log('warn', `keep-processes acceptance: ${agentId} (${id}) sidecar rejected — ${evalResult.reason} (not a workdir failure)`);
+          }
+        } catch (e) {
+          log('warn', `keep-processes acceptance check failed for ${agentId} (${id}): ${e.message}`);
+        }
+      }
+    }
+
     // Move from active to completed in dispatch (single source of truth for agent status)
     // autoRecovered: agent failed after creating PRs — treat as success
     const hardContractFail = completionContractFailure?.severity === 'hard'
       || completionContractFailure?.nonTerminal === true;
-    const effectiveResult = hardContractFail ? DISPATCH_RESULT.ERROR : (((code === 0 && !agentReportedFailure) || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
+    // P-d2a8f6c1: nonce mismatch (or missing+required) is a security failure —
+    // override effectiveResult to ERROR and surface the dedicated failure_class.
+    // We mark the work item as failed (processWorkItemFailure NOT suppressed)
+    // so the dispatch is not silently retried by the auto-recovery path.
+    const nonceFail = nonceMismatch && nonceMismatch.severity === 'hard';
+    // W-mp6k7ywi000fa33c — keep_processes workdir rejection is a hard
+    // failure: the agent's claim that "everything was set up correctly" is
+    // structurally false. Force ERROR so the dispatch is not silently treated
+    // as success even when exit code is 0.
+    const keepProcessesWorkdirFail = !!keepProcessesWorkdirFailure;
+    const effectiveResult = (hardContractFail || nonceFail || keepProcessesWorkdirFail)
+      ? DISPATCH_RESULT.ERROR
+      : (((code === 0 && !agentReportedFailure) || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
     const finalCompletionReportPath = structuredCompletion?._path || dispatchItem.meta?.completionReportPath || shared.dispatchCompletionReportPath(id);
     const completionOpts = {
       ...(finalCompletionReportPath ? { completionReportPath: finalCompletionReportPath } : {}),
       ...(structuredCompletion ? { structuredCompletion } : {}),
     };
-    const completeOpts = hardContractFail
-      ? { ...completionOpts, processWorkItemFailure: false }
-      : (effectiveResult === DISPATCH_RESULT.ERROR ? {
-          ...completionOpts,
-          ...(failureClass ? { failureClass } : {}),
-          ...(typeof retryableDecision === 'boolean' ? { agentRetryable: retryableDecision } : {}),
-          ...(structuredCompletion?.failure_class ? { failureClass: structuredCompletion.failure_class } : {}),
-        } : completionOpts);
+    const completeOpts = keepProcessesWorkdirFail
+      ? { ...completionOpts, failureClass: FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR, agentRetryable: false }
+      : (nonceFail
+          ? { ...completionOpts, failureClass: nonceMismatch.failureClass, agentRetryable: false }
+          : (hardContractFail
+              ? { ...completionOpts, processWorkItemFailure: false }
+              : (effectiveResult === DISPATCH_RESULT.ERROR ? {
+                  ...completionOpts,
+                  ...(failureClass ? { failureClass } : {}),
+                  ...(typeof retryableDecision === 'boolean' ? { agentRetryable: retryableDecision } : {}),
+                  ...(structuredCompletion?.failure_class ? { failureClass: structuredCompletion.failure_class } : {}),
+                } : completionOpts)));
     // Extract last 5 non-empty stderr lines as error context when exit code is non-zero
     let errorReason = '';
-    if (hardContractFail) {
+    if (keepProcessesWorkdirFail) {
+      errorReason = `invalid_keep_processes_workdir: ${keepProcessesWorkdirFailure.reason} (cwd=${keepProcessesWorkdirFailure.cwd || '<unknown>'})`.slice(0, 300);
+    } else if (nonceFail) {
+      errorReason = nonceMismatch.reason || 'completion nonce mismatch';
+    } else if (hardContractFail) {
       errorReason = completionContractFailure.reason || 'PR attachment contract failed';
     } else if (agentReportedFailure) {
       errorReason = structuredCompletion
@@ -1894,8 +2215,76 @@ async function spawnAgent(dispatchItem, config) {
       const hint = diagnoseEmptyOutput(failureClass, code, elapsedMs);
       if (hint) errorReason = errorReason ? `${hint} ${errorReason}` : hint;
     }
+
+    // ── Pool return (W-mp73ya3e000me6c5) ────────────────────────────────────
+    // Park a healthy worktree as IDLE in the per-project pool so the next
+    // dispatch can reuse it without paying the cold install/build cost. Run
+    // BEFORE completeDispatch so the dispatch is still in dispatch.active
+    // during the git ops — otherwise pruneStale() racing on another tick
+    // could see borrowedBy as orphaned and evict the entry mid-return.
+    // Skipped when keep_processes PIDs are still alive: the worktree may be
+    // the cwd of a left-running dev server or watcher.
+    if (effectiveResult === DISPATCH_RESULT.SUCCESS && worktreePath && fs.existsSync(worktreePath)) {
+      let _keepPidsAlive = false;
+      try {
+        const _ks = require('./engine/keep-process-sweep');
+        const _anchorRes = _ks.getActiveAnchorPidsForAgent(agentId);
+        if (_anchorRes && _anchorRes.pids && _anchorRes.pids.size > 0) _keepPidsAlive = true;
+      } catch (_e) { /* keep-process-sweep import optional — fall through */ }
+
+      const _projForReturn = project?.name || 'default';
+      const _poolSizeReturn = worktreePool.getProjectPoolSize(_projForReturn, config);
+      if (!_keepPidsAlive && _poolSizeReturn > 0) {
+        try {
+          const _mainRefRet = sanitizeBranch(shared.resolveMainBranch(rootDir, project?.mainBranch));
+          await shared.shellSafeGit(['reset', '--hard', 'HEAD'], { ..._gitOpts, cwd: worktreePath, timeout: 30000 });
+          // -fd preserves gitignored files (node_modules, .vite, .next caches) — that's the whole point.
+          await shared.shellSafeGit(['clean', '-fd'], { ..._gitOpts, cwd: worktreePath, timeout: 30000 });
+          await shared.shellSafeGit(['fetch', 'origin', _mainRefRet], { ..._gitOpts, cwd: rootDir, timeout: 30000 });
+          // Detach at origin/<main> — local main is typically checked out in
+          // the project root and git refuses two checkouts of the same branch.
+          await shared.shellSafeGit(['checkout', '--detach', `origin/${_mainRefRet}`], { ..._gitOpts, cwd: worktreePath, timeout: 30000 });
+          const _outcome = worktreePool.returnToPool(_projForReturn, worktreePath, {
+            poolSize: _poolSizeReturn,
+            branch: branchName || '',
+          });
+          log('info', `worktree-pool: return outcome=${_outcome} for ${_projForReturn} at ${worktreePath}`);
+          if (_outcome === 'rejected') {
+            // Capacity rejected — drop any stale entry so cleanup can reap normally.
+            worktreePool.evictEntry(worktreePath, 'capacity-rejected');
+          }
+        } catch (returnErr) {
+          log('warn', `worktree-pool: return failed for ${worktreePath}: ${returnErr.message} — evicting from pool`);
+          worktreePool.evictEntry(worktreePath, 'return-git-failed');
+        }
+      } else if (_keepPidsAlive) {
+        // Skip the pool — the worktree is in use by left-running processes.
+        // Make sure no stale entry lingers (defensive).
+        worktreePool.evictEntry(worktreePath, 'keep-processes-alive');
+      }
+    }
+
     completeDispatch(id, effectiveResult, errorReason, resultSummary, completeOpts);
 
+    // W-mp6k7ywi000fa33c — surface the workdir-rejection on the WI so the
+    // dashboard pending-reason area shows the missing structure instead of
+    // a bare failure_class label. _pendingReason on a failed item is treated
+    // by the dashboard as "additional context" rather than a queue gate.
+    if (keepProcessesWorkdirFailure && dispatchItem.meta?.item?.id) {
+      try {
+        const wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (wiPath) {
+          mutateJsonFileLocked(wiPath, data => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i.id === dispatchItem.meta.item.id);
+            if (!wi) return data;
+            wi._pendingReason = `invalid_keep_processes_workdir: ${keepProcessesWorkdirFailure.reason}`.slice(0, 500);
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `keep-processes acceptance: failed to set _pendingReason: ${e.message}`); }
+    }
+
     // Cleanup temp files (including PID file now that dispatch is complete)
     try { fs.unlinkSync(sysPromptPath); } catch { /* cleanup */ }
     try { fs.unlinkSync(promptPath); } catch { /* cleanup */ }
@@ -1974,6 +2363,7 @@ async function spawnAgent(dispatchItem, config) {
     startedAt,
     runtimeName,
     sessionId: existingProcInfo.sessionId || cachedSessionId,
+    _completionNonce: existingProcInfo._completionNonce || completionNonce,
     _pendingSteeringFiles: mergePendingSteeringEntries(existingProcInfo._pendingSteeringFiles, pendingSteering.entries),
   });
 
@@ -2288,6 +2678,51 @@ function safePrdFilenameForProject(projectName, suffix) {
   return path.basename(resolved);
 }
 
+/**
+ * Atomically reserve a unique PRD filename in `prdDir` (P-9b7e5d3c).
+ *
+ * Replaces the racy "fs.existsSync(...) then write" pattern: two parallel
+ * materializations on the same plan slug previously both observed a 'free'
+ * filename and silently overwrote each other. This helper uses
+ * `fs.openSync(path, 'wx')` so the OS rejects duplicate creates atomically.
+ *
+ * Attempt schedule (100 attempts total):
+ *   attempt = 0 → baseFileName              (e.g. "slug.json")
+ *   attempt = 1 → "${stem}-1${ext}"          (e.g. "slug-1.json")
+ *   attempt = 2 → "${stem}-2${ext}"
+ *   ...
+ *   attempt = 99 → "${stem}-99${ext}"
+ *
+ * Behavior:
+ *   - On EEXIST: increment attempt and retry.
+ *   - Any other openSync error propagates immediately.
+ *   - After 100 EEXIST failures: throw
+ *     'Could not reserve unique PRD filename after 100 attempts'.
+ *   - On success: write `content` to the reserved file, close fd, return basename.
+ */
+function reservePrdFilename(prdDir, baseFileName, content = '') {
+  const ext = path.extname(baseFileName);
+  const stem = ext ? baseFileName.slice(0, -ext.length) : baseFileName;
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const candidateName = attempt === 0 ? baseFileName : `${stem}-${attempt}${ext}`;
+    const candidatePath = path.join(prdDir, candidateName);
+    let fd;
+    try {
+      fd = fs.openSync(candidatePath, 'wx');
+    } catch (err) {
+      if (err && err.code === 'EEXIST') continue;
+      throw err;
+    }
+    try {
+      if (content) fs.writeSync(fd, content);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return candidateName;
+  }
+  throw new Error('Could not reserve unique PRD filename after 100 attempts');
+}
+
 function materializePlansAsWorkItems(config) {
   if (!fs.existsSync(PRD_DIR)) { try { fs.mkdirSync(PRD_DIR, { recursive: true }); } catch (e) { log('warn', 'create PRD directory: ' + e.message); } }
   const writePrdLocked = (fileName, data) => {
@@ -2409,9 +2844,11 @@ function materializePlansAsWorkItems(config) {
           const parsed = JSON.parse(stripped);
           if (parsed.missing_features) {
             const jsonName = mf.replace(/\.md$/, '.json');
-            writePrdLocked(jsonName, parsed);
+            // Atomic open ('wx' + retry) so two parallel migrations on the
+            // same slug don't both overwrite a single PRD (P-9b7e5d3c).
+            const reserved = reservePrdFilename(checkDir, jsonName, JSON.stringify(parsed, null, 2));
             try { fs.unlinkSync(path.join(checkDir, mf)); } catch { /* cleanup */ }
-            log('info', `Plan enforcement: moved ${mf} → prd/${jsonName} (PRDs must be .json in prd/)`);
+            log('info', `Plan enforcement: moved ${mf} → prd/${reserved} (PRDs must be .json in prd/)`);
           }
         } catch {} // Not JSON — it's a proper plan .md, leave it
       }
@@ -2424,9 +2861,11 @@ function materializePlansAsWorkItems(config) {
           try {
             const parsed = safeJson(path.join(PLANS_DIR, jf));
             if (parsed?.missing_features) {
-              writePrdLocked(jf, parsed);
+              // Atomic open ('wx' + retry) so two parallel migrations on the
+              // same slug don't both overwrite a single PRD (P-9b7e5d3c).
+              const reserved = reservePrdFilename(PRD_DIR, jf, JSON.stringify(parsed, null, 2));
               try { fs.unlinkSync(path.join(PLANS_DIR, jf)); } catch { /* cleanup */ }
-              log('info', `Auto-migrated PRD ${jf} from plans/ to prd/`);
+              log('info', `Auto-migrated PRD ${jf} from plans/ to prd/${reserved}`);
             }
           } catch (e) { log('warn', 'migrate PRD from plans: ' + e.message); }
         }
@@ -2669,12 +3108,20 @@ function materializePlansAsWorkItems(config) {
           const reconciled = reconcileItemsWithPrs(existingItems, allPrsForReconcile, { onlyIds: newlyCreatedIds });
           if (reconciled > 0) log('info', `Plan reconciliation: marked ${reconciled} item(s) as done → ${projName}`);
 
-          // PRD removal sync: cancel pending work items whose PRD item was removed from the plan
+          // PRD removal sync: cancel pending work items whose PRD item was removed from the plan.
+          // IMPORTANT: decomposed sub-items (children spawned by the decompose agent for
+          // implement:large parents) carry parent_id and have IDs of the shape
+          // <parentId>-a/-b/-c. They are NEVER written back into the PRD's missing_features
+          // array, so an id-only predicate cancels them every time the materializer creates a
+          // new WI for the same plan. Accept WIs whose parent_id matches any current PRD id
+          // (one-hop only — decompose produces a single level of children today).
           const currentPrdIds = new Set(plan.missing_features.map(f => f.id));
           let cancelled = 0;
           for (const wi of existingItems) {
             if (wi.status !== WI_STATUS.PENDING || wi.sourcePlan !== file) continue;
-            if (!currentPrdIds.has(wi.id)) {
+            const ownIdInPrd = currentPrdIds.has(wi.id);
+            const parentInPrd = wi.parent_id && currentPrdIds.has(wi.parent_id);
+            if (!ownIdInPrd && !parentInPrd) {
               wi.status = WI_STATUS.CANCELLED;
               wi.cancelledAt = ts();
               wi.cancelReason = `PRD item removed from ${file}`;
@@ -2718,8 +3165,9 @@ function materializePlansAsWorkItems(config) {
           const mainBranch = shared.resolveMainBranch(root, firstProject.mainBranch);
           const branch = sanitizeBranch(plan.feature_branch);
           // Create branch from main (idempotent — ignores if exists)
-          exec(`git branch "${branch}" "${mainBranch}" 2>/dev/null || true`, { cwd: root, stdio: 'pipe' });
-          exec(`git push -u origin "${branch}" 2>/dev/null || true`, { cwd: root, stdio: 'pipe' });
+          // P-a7c4d2e8 (F3): argv-form (shell:false) replaces shell-piped exec.
+          try { shared.shellSafeGitSync(['branch', branch, mainBranch], { cwd: root }); } catch { /* idempotent — branch may already exist */ }
+          try { shared.shellSafeGitSync(['push', '-u', 'origin', branch], { cwd: root }); } catch (e) { log('warn', `git push -u origin ${branch} (pre-create): ${e.message?.split('\n')[0]}`); }
           log('info', `Shared branch pre-created: ${branch} for plan ${file}`);
         } catch (err) {
           log('warn', `Failed to pre-create shared branch for ${file}: ${err.message}`);
@@ -3437,6 +3885,13 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     pr_url: item.pr_url || item.prUrl || '',
     reviewer: item.reviewer || 'Reviewer',
     review_note: item.review_note || item.reviewNote || item.description || item.title || 'See PR thread comments',
+    // W-mp68q6ke0010de68 — opt-in keep_processes hint plumbed via item.meta.
+    // Truthy `keep_processes` triggers the playbook hint section; missing flag
+    // means the agent never learns the feature exists (default-off).
+    keep_processes: !!(item.meta && item.meta.keep_processes),
+    keep_processes_ttl_minutes: item.meta && Number.isFinite(Number(item.meta.keep_processes_ttl_minutes))
+      ? Math.floor(Number(item.meta.keep_processes_ttl_minutes))
+      : '',
   };
   const cpResult = buildWorkItemDispatchVars(item, vars, config, {
     worktreePath: vars.worktree_path || root,
@@ -4661,6 +5116,23 @@ let tickRunning = false;
 let _tickStartedAt = 0;
 const TICK_TIMEOUT_MS = 300000; // 5 min — force-release tick lock if stuck
 
+// P-c2e5a1d9-a — Generation counter that is incremented on every tick start
+// AND every time the force-release branch reclaims a hung tick. The in-flight
+// (hung) tickInner captures its own `myGeneration` at entry; if a force-release
+// later bumps `tickGeneration`, the stale tick can detect the mismatch via
+// `_isTickStale()` and abort instead of mutating shared state alongside the
+// fresh tick that took over. Sub-task -a wires the scaffolding + a single
+// guard call after the heartbeat write; per-phase guards land in -b.
+let tickGeneration = 0;
+
+function _isTickStale(gen) {
+  if (gen !== tickGeneration) {
+    log('warn', 'Tick generation mismatch, aborting stale tick');
+    return true;
+  }
+  return false;
+}
+
 function _pollIntervalMsFromTicks(ticks, tickIntervalMs) {
   const normalizedTicks = Math.max(1, Number(ticks) || 1);
   const normalizedTickInterval = Math.max(1, Number(tickIntervalMs) || ENGINE_DEFAULTS.tickInterval);
@@ -4683,6 +5155,10 @@ async function tick() {
       log('error', `Tick hung for ${Math.round((Date.now() - _tickStartedAt) / 1000)}s — force-releasing lock`);
       tickRunning = false;
       _tickStartedAt = 0;
+      // P-c2e5a1d9-a — Bump generation so the in-flight (hung) tickInner sees
+      // a mismatch via `_isTickStale()` and bails out before mutating shared
+      // state alongside the fresh tick that's about to take over.
+      tickGeneration++;
     }
     return;
   }
@@ -4699,6 +5175,11 @@ async function tick() {
 }
 
 async function tickInner() {
+  // P-c2e5a1d9-a — Capture this tick's generation as the very first statement
+  // so any guard later in this function can detect a force-release that
+  // reclaimed the lock while we were still running.
+  const myGeneration = ++tickGeneration;
+
   const control = getControl();
   if (control.state !== 'running' && control.state !== 'stopping') {
     log('info', `Engine state is "${control.state}" — exiting process`);
@@ -4708,6 +5189,11 @@ async function tickInner() {
   // Write heartbeat so dashboard can detect stale engine
   try { mutateControl(c => ({ ...c, heartbeat: Date.now() })); } catch (e) { log('warn', 'write heartbeat: ' + e.message); }
 
+  // P-c2e5a1d9-a — Initial wiring guard: bail immediately if a force-release
+  // reclaimed our lock while the heartbeat write was in flight. Per-phase
+  // guards inside the rest of tickInner are sub-task -b's scope.
+  if (_isTickStale(myGeneration)) return;
+
   const config = getConfig();
   tickCount++;
   const now = Date.now();
@@ -4737,6 +5223,23 @@ async function tickInner() {
   // 2.5. Periodic cleanup + MCP sync (every 10 ticks = ~5 minutes)
   if (tickCount % 10 === 0) {
     try { await runCleanup(config); } catch (e) { log('warn', `runCleanup: ${e.message}`); }
+    if (_isTickStale(myGeneration)) return;
+  }
+
+  // 2.52. keep_processes TTL/dead-PID sweep (W-mp68q6ke0010de68). Walks
+  // agents/*/keep-pids.json, kills+unlinks expired entries, silently unlinks
+  // entries whose PIDs are all gone, leaves malformed files alone. Cheap (one
+  // readdir + N small file reads), bounded by ENGINE_DEFAULTS.keepProcesses.
+  const keepSweepEvery = Math.max(1, ENGINE_DEFAULTS.keepProcesses?.sweepEvery || 30);
+  if (ENGINE_DEFAULTS.keepProcesses?.enabled !== false && tickCount % keepSweepEvery === 0) {
+    safe('sweepKeepProcesses', () => {
+      const { sweepKeepProcesses } = require('./engine/keep-process-sweep');
+      const stats = sweepKeepProcesses();
+      if (stats.scanned > 0 && (stats.expiredFiles || stats.deadFiles || stats.malformed)) {
+        log('info', `keep-processes sweep: scanned=${stats.scanned} expired=${stats.expiredFiles} dead=${stats.deadFiles} malformed=${stats.malformed} killed=${stats.killedPids}`);
+      }
+    });
+    if (_isTickStale(myGeneration)) return;
   }
 
   // 2.55. Check persistent watches (3 tick-equivalents, default ~3 minutes)
@@ -4831,7 +5334,9 @@ async function tickInner() {
       log('info', '[gh] PR status poll skipped — throttled');
     }
     if (statusPolls.length) await Promise.allSettled(statusPolls);
+    if (_isTickStale(myGeneration)) return;
     try { await processPendingRebases(config); } catch (err) { log('warn', `Pending rebase processing error: ${err?.message || err}`); }
+    if (_isTickStale(myGeneration)) return;
     // Sync PR status back to PRD items (missing → done when active PR exists)
     try { syncPrdFromPrs(config); } catch (err) { log('warn', `PRD sync error: ${err?.message || err}`); }
     // Check if any plans can be marked completed (all features done/in-pr)
@@ -4875,12 +5380,14 @@ async function tickInner() {
       log('info', '[gh] PR comment poll skipped — throttled');
     }
     if (commentPolls.length) await Promise.allSettled(commentPolls);
+    if (_isTickStale(myGeneration)) return;
     // Reconciliation runs regardless of poll flags — it's a recovery sweep, not a convenience poll
     // Reconciliation also parallelized — ADO and GitHub reconciliation are independent
     const reconcilePolls = [];
     reconcilePolls.push(reconcilePrs(config).catch(err => { log('warn', `ADO PR reconciliation error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
     reconcilePolls.push(ghReconcilePrs(config).catch(err => { log('warn', `GitHub PR reconciliation error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
     await Promise.allSettled(reconcilePolls);
+    if (_isTickStale(myGeneration)) return;
   }
 
   // 2.9. Stalled dispatch detection — auto-retry failed items blocking the graph (every 20 ticks = ~10 min)
@@ -4903,6 +5410,7 @@ async function tickInner() {
             const dispatchKeysToClear = [];
             const cooldownKeysToClear = [];
 
+            if (_isTickStale(myGeneration)) return;
             mutateWorkItems(wiPath, items => {
               let changed = false;
               const failedIds = new Set(items.filter(w => w.status === WI_STATUS.FAILED).map(w => w.id));
@@ -4959,6 +5467,7 @@ async function tickInner() {
             // Clear dispatch entries AFTER work-items lock is released (no nested locks)
             for (const key of dispatchKeysToClear) {
               try {
+                if (_isTickStale(myGeneration)) return;
                 mutateDispatch((dp) => {
                   dp.completed = dp.completed.filter(d => d.meta?.dispatchKey !== key);
                   return dp;
@@ -4997,6 +5506,7 @@ async function tickInner() {
   try { pruneStalePrDispatches(config); } catch (e) { log('warn', 'prune stale PR dispatches: ' + e.message); }
   let discoveryOk = true;
   try { await discoverWork(config); } catch (e) { log('warn', 'discoverWork: ' + e.message); discoveryOk = false; }
+  if (_isTickStale(myGeneration)) return;
 
   // 4. Update snapshot
   safe('updateSnapshot', () => updateSnapshot(config));
@@ -5022,6 +5532,7 @@ async function tickInner() {
     const pa = itemPriority[a.meta?.item?.priority] ?? 1, pb = itemPriority[b.meta?.item?.priority] ?? 1;
     return pa - pb;
   });
+  if (_isTickStale(myGeneration)) return;
   mutateDispatch((dp) => {
     dp.pending = dispatch.pending;
     dp.active = dispatch.active || dp.active;
@@ -5069,6 +5580,7 @@ async function tickInner() {
       delete item.skipReason;
       refreshDeferredWorkItemPrompt(item, config);
       try {
+        if (_isTickStale(myGeneration)) return;
         mutateDispatch((dp) => {
           const p = (dp.pending || []).find(d => d.id === item.id);
           if (p) {
@@ -5185,6 +5697,7 @@ async function tickInner() {
         log('error', `spawnAgent exception for ${item.id}: ${spawnErr.message}`);
         proc = null;
       }
+      if (_isTickStale(myGeneration)) return;
       if (proc === null) {
         // spawnAgent failed (e.g., worktree creation error). It already called
         // completeDispatch internally which handles retry logic, but log at the
@@ -5198,6 +5711,7 @@ async function tickInner() {
               ? path.join(ENGINE_DIR, '..', 'work-items.json')
               : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
             if (wiPath) {
+              if (_isTickStale(myGeneration)) return;
               mutateWorkItems(wiPath, items => {
                 const wi = items.find(i => i.id === item.meta.item.id);
                 if (wi && wi.status === WI_STATUS.DISPATCHED) {
@@ -5267,6 +5781,7 @@ async function tickInner() {
     }
   }
   if (skipReasonChanged) {
+    if (_isTickStale(myGeneration)) return;
     mutateDispatch((dp) => { dp.pending = postDispatch.pending; return dp; });
   }
 }
@@ -5300,6 +5815,7 @@ module.exports = {
   // Discovery
   discoverWork, discoverFromPrs, discoverFromWorkItems, discoverCentralWorkItems,
   materializePlansAsWorkItems,
+  reservePrdFilename, // exported for testing (P-9b7e5d3c)
   sweepStaleArchivedPrdBackups, // exported for testing
 
   // Shared helpers (used by lifecycle.js and tests)
@@ -5333,6 +5849,14 @@ module.exports = {
   // Tick
   tick,
   resolveMaxConcurrent, _pollIntervalMsFromTicks, _shouldRunPeriodicPhase, // exported for testing
+  // P-c2e5a1d9-a — exported for testing the tick-generation force-release path
+  _isTickStale,
+  get tickGeneration() { return tickGeneration; },
+  set tickGeneration(v) { tickGeneration = v; },
+  get tickRunning() { return tickRunning; },
+  set tickRunning(v) { tickRunning = v; },
+  get _tickStartedAt() { return _tickStartedAt; },
+  set _tickStartedAt(v) { _tickStartedAt = v; },
 };
 
 // ─── Entrypoint ─────────────────────────────────────────────────────────────