@yemi33/minions 0.1.2383 → 0.1.2384

package/engine.js

@@ -445,6 +445,25 @@ function _buildAgentSpawnFlags(runtime, opts = {}) {
   return buildSpawnFlags(runtime, opts);
 }
 
+function _syncAgentWorkerPoolConfig(engineConfig = {}) {
+  const enabled = (engineConfig.agentUseWorkerPool ?? ENGINE_DEFAULTS.agentUseWorkerPool) === true;
+  agentWorkerPool.setEnabled(enabled);
+  if (enabled) agentWorkerPool.setPoolSize(shared.resolveAgentAcpPoolSize(engineConfig));
+  return enabled;
+}
+
+function _resolveAgentPoolProcessCwd(project, engineConfig) {
+  const scratchRoot = shared.resolveAgentTempBaseDir(project, engineConfig, MINIONS_DIR)
+    || path.join(os.tmpdir(), 'minions-agent-temp');
+  const processCwd = path.join(
+    scratchRoot,
+    'acp-workers',
+    shared.safeSlugComponent(project?.name || project?.repoName || 'project')
+  );
+  fs.mkdirSync(processCwd, { recursive: true });
+  return processCwd;
+}
+
 function _runtimeLogger() {
   return {
     info: (msg) => log('info', msg),
@@ -995,15 +1014,6 @@ async function _probeBranchLocally(rootDir, branchName, gitOpts) {
   }
 }
 
-// W-mr3tayu4 — thin wrapper around shared.removeStaleIndexLock. The age-gated
-// (>300000ms) stale-lock removal now lives in engine/shared.js so both the
-// worktree-add retry paths here and engine/live-checkout.js#prepareLiveCheckout
-// share one implementation (no circular import). Kept as a named local because
-// three internal call sites and the test harness reference `removeStaleIndexLock`.
-function removeStaleIndexLock(rootDir) {
-  return shared.removeStaleIndexLock(rootDir);
-}
-
 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
@@ -1018,7 +1028,6 @@ async function runWorktreeAdd(rootDir, worktreePath, addArgs, gitOpts, worktreeC
     try {
       if (attempt > 0) {
         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 shared.shellSafeGit(['worktree', 'add', worktreePath, ...addArgs], { ...gitOpts, cwd: rootDir });
@@ -2388,8 +2397,12 @@ async function spawnAgent(dispatchItem, config) {
     updateAgentStatus(id, AGENT_STATUS.FAILED, err.message);
     throw err;
   }
-  const metaProjectFields = metaProject && typeof metaProject === 'object' ? metaProject : {};
-  const project = projectResolution.project ? { ...projectResolution.project, ...metaProjectFields } : {};
+  // Persisted dispatch metadata is an identity hint only. Never merge stale
+  // checkout configuration back into the current configured project.
+  const project = projectResolution.project ? { ...projectResolution.project } : {};
+  const configuredProjects = getProjects(config);
+  const assertSafeWorktreePath = (candidate) =>
+    shared.assertWorktreeOutsideProjects(candidate, configuredProjects);
 
   // ── Workspace manifest repo gate (W-mq07avbk000m5543) ────────────────────
   // Dispatch-time enforcement of `agents.<id>.workspace_manifest.allowed_repos`.
@@ -2423,19 +2436,14 @@ async function spawnAgent(dispatchItem, config) {
 
   // 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)
+  //   - project-bound read-only types: detached worktree placement
+  //   - project-less read-only types: { cwd: MINIONS_DIR, worktreeRootDir: null }
   //   - 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).
-  // W-mp8ho6w500034a58: read-only task types (meeting/ask/explore/plan/plan-to-prd)
-  // never need a worktree — even when carrying a pipeline branch. Pipeline branches
-  // on read-only stages are a no-op label; the stage doesn't commit anything, so
-  // the worktree had no functional purpose and was only there to absorb a drive-
-  // root preflight that fired against MINIONS_DIR's parent. Read-only pipeline
-  // stages now short-circuit alongside any other read-only WI (see the gate at
-  // `if (branchName && READ_ONLY_ROOT_TASK_TYPES.has(type))` below).
+  // Pipeline branch labels remain irrelevant to read-only tasks, so they are
+  // discarded before detached placement.
   const _preBranchName = meta?.branch ? sanitizeBranch(meta.branch) : null;
 
   // ── Per-WI meta.workdir override (P-714ef144) ─────────────────────────
@@ -2482,9 +2490,10 @@ async function spawnAgent(dispatchItem, config) {
   }
   const validatedWorkdir = _wdValidation.value;  // null when unset / empty
 
-  let cwd, worktreeRootDir, liveMode = false;
+  let cwd, worktreeRootDir, liveMode = false, readOnlyWorktree = false;
   try {
-    ({ cwd, worktreeRootDir, liveMode = false } = shared.resolveSpawnPaths(project, type, MINIONS_DIR, { workdir: validatedWorkdir }));
+    ({ cwd, worktreeRootDir, liveMode = false, readOnlyWorktree = false } =
+      shared.resolveSpawnPaths(project, type, MINIONS_DIR, { workdir: validatedWorkdir }));
   } 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}`);
@@ -2533,6 +2542,29 @@ async function spawnAgent(dispatchItem, config) {
     }
     throw rootErr;
   }
+  const checkoutModeAtDispatch = liveMode
+    ? shared.CHECKOUT_MODES.LIVE
+    : shared.CHECKOUT_MODES.WORKTREE;
+  const resolvedProjectMeta = project?.name || project?.localPath
+    ? { name: project.name, localPath: project.localPath }
+    : null;
+  dispatchItem.checkoutMode = checkoutModeAtDispatch;
+  if (resolvedProjectMeta && dispatchItem.meta) {
+    dispatchItem.meta.project = resolvedProjectMeta;
+  }
+  try {
+    mutateDispatch((dispatch) => {
+      for (const queue of ['pending', 'active']) {
+        const found = (dispatch?.[queue] || []).find(d => d && d.id === id);
+        if (!found) continue;
+        found.checkoutMode = checkoutModeAtDispatch;
+        if (resolvedProjectMeta && found.meta) found.meta.project = resolvedProjectMeta;
+      }
+      return dispatch;
+    });
+  } catch (e) {
+    log('warn', `spawnAgent: failed to persist checkout context for ${id}: ${e.message}`);
+  }
   // 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
@@ -2752,17 +2784,11 @@ async function spawnAgent(dispatchItem, config) {
   _phaseT.afterPrompt = Date.now();
 
   if (branchName && READ_ONLY_ROOT_TASK_TYPES.has(type)) {
-    // W-mp7havqf0007ce6b: read-only types (meeting/ask/explore/plan/plan-to-prd)
-    // short-circuit BEFORE the worktree-creation block. resolveSpawnPaths returns
-    // worktreeRootDir=null for read-only types, and path.resolve(null, ...) throws
-    // ("paths[0] must be of type string. Received null"). Pipeline branches used
-    // to be exempt — they don't need to be (W-mp8ho6w500034a58): read-only stages
-    // never commit, so a pipeline-branch label is meaningless for them and the
-    // forced worktree only existed to feed the drive-root preflight that this
-    // short-circuit now correctly avoids.
-    log('info', `${type}: read-only task with branch ${branchName} — skipping worktree, running in cwd ${cwd}`);
+    // Read-only dispatches never own a branch. Project-bound worktree-mode
+    // dispatches still get a detached worktree below; project-less/live tasks
+    // keep their resolved cwd.
+    log('info', `${type}: ignoring branch label ${branchName} for read-only dispatch`);
     branchName = null;
-    worktreePath = null;
   }
 
   // ── Live-checkout mode handling (P-a3f9b204) ─────────────────────────────
@@ -3521,6 +3547,55 @@ async function spawnAgent(dispatchItem, config) {
     }
   }
 
+  const needsDetachedProjectWorktree = !liveMode && !!rootDir && !!project?.localPath && !branchName;
+  if (needsDetachedProjectWorktree) {
+    const detachedKind = readOnlyWorktree ? 'read-only' : 'branchless';
+    updateAgentStatus(id, AGENT_STATUS.WORKTREE_SETUP, `Setting up detached ${detachedKind} worktree for ${project.name || 'project'}`);
+    const wtDirName = shared.buildWorktreeDirName({
+      dispatchId: id,
+      projectName: project.name || 'default',
+      branchName: detachedKind,
+    });
+    const worktreeRoot = path.resolve(rootDir, engineConfig.worktreeRoot || '../worktrees');
+    worktreePath = path.resolve(worktreeRoot, wtDirName);
+    try {
+      assertSafeWorktreePath(worktreePath);
+      if (fs.existsSync(worktreePath)) {
+        shared.removeWorktree(worktreePath, rootDir, worktreeRoot, { excludeDispatchId: id });
+      }
+      const mainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
+      await runWorktreeAdd(
+        rootDir,
+        worktreePath,
+        ['--detach', mainRef],
+        _worktreeGitOpts,
+        worktreeCreateRetries,
+      );
+      cwd = worktreePath;
+      log('info', `${type}: running in detached ${detachedKind} worktree ${worktreePath}; operator checkout ${project.localPath} is protected`);
+    } catch (readOnlyWtErr) {
+      try {
+        if (worktreePath && fs.existsSync(worktreePath)) {
+          shared.removeWorktree(worktreePath, rootDir, worktreeRoot, { excludeDispatchId: id });
+        }
+      } catch (cleanupErr) {
+        log('warn', `read-only worktree cleanup failed for ${id}: ${cleanupErr.message}`);
+      }
+      const summary = `Detached ${detachedKind} worktree setup failed: ${readOnlyWtErr.message}`;
+      log('error', `spawnAgent: ${summary}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        summary.slice(0, 800),
+        'The operator checkout was not used. Fix the worktree setup failure and retry.',
+        { failureClass: FAILURE_CLASS.WORKTREE_PREFLIGHT, agentRetryable: true },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
+  }
+
   if (branchName && !liveMode) {
     updateAgentStatus(id, AGENT_STATUS.WORKTREE_SETUP, `Setting up worktree for branch ${branchName}`);
     // W-mpwy3mp5 (#2996): track whether we ended up reusing an existing
@@ -3538,7 +3613,7 @@ async function spawnAgent(dispatchItem, config) {
     // nested worktrees cause glob/grep to match both copies (mirror writes).
     // 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); }
+    try { assertSafeWorktreePath(worktreePath); }
     catch (assertErr) {
       if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
       throw assertErr;
@@ -3552,7 +3627,7 @@ 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.
-      try { shared.assertWorktreeOutsideProject(existingWt, rootDir); }
+      try { assertSafeWorktreePath(existingWt); }
       catch (assertErr) {
         if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
         throw assertErr;
@@ -3604,7 +3679,7 @@ async function spawnAgent(dispatchItem, config) {
         if (!_branchOnRemote) {
           const borrowed = worktreePool.tryBorrow(_poolProject, id);
           if (borrowed && borrowed.path && fs.existsSync(borrowed.path)) {
-            try { shared.assertWorktreeOutsideProject(borrowed.path, rootDir); }
+            try { assertSafeWorktreePath(borrowed.path); }
             catch (assertErr) {
               // Always evict before deciding what to do — leaves no BORROWED
               // orphan tied to a dispatch that won't complete normally.
@@ -3666,9 +3741,6 @@ async function spawnAgent(dispatchItem, config) {
           const isSharedBranch = meta?.branchStrategy === 'shared-branch' || meta?.useExistingBranch;
           // Prune stale worktree entries before creating (handles leftover entries from crashed runs)
           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}`);
             await _fetchWithTransientRetry(['origin', branchName], { ..._gitOpts, cwd: rootDir }, `origin/${branchName} (shared-branch pre-create)`);
@@ -3678,7 +3750,7 @@ async function spawnAgent(dispatchItem, config) {
               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)) {
-                  try { shared.assertWorktreeOutsideProject(existingWtPath, rootDir); }
+                  try { assertSafeWorktreePath(existingWtPath); }
                   catch (assertErr) {
                     if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
                     throw assertErr;
@@ -3763,7 +3835,7 @@ async function spawnAgent(dispatchItem, config) {
                       log('warn', `Branch ${branchName} actively used by another agent at ${existingWtPath} — cannot create worktree`);
                       throw eRemote;
                     }
-                    try { shared.assertWorktreeOutsideProject(existingWtPath, rootDir); }
+                    try { assertSafeWorktreePath(existingWtPath); }
                     catch (assertErr) {
                       if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
                       throw assertErr;
@@ -3829,10 +3901,10 @@ async function spawnAgent(dispatchItem, config) {
                 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
+                  // Transient error (lock, timeout) — prune and retry -b once more.
+                  // Never delete the operator checkout's .git/index.lock.
                   log('info', `Retrying -b create after prune for ${branchName}`);
                   try { await shared.shellSafeGit(['worktree', 'prune'], { ..._gitOpts, cwd: rootDir, timeout: 15000 }); } catch { /* optional */ }
-                  removeStaleIndexLock(rootDir);
                   // Clean up partial worktree directory from the failed -b
                   // attempt. This husk pre-dates `git worktree add`, so git
                   // does not yet own it and shared.removeWorktree's
@@ -3894,7 +3966,7 @@ async function spawnAgent(dispatchItem, config) {
                           log('warn', `Branch ${branchName} actively used by another agent at ${existingWtPath} — cannot create worktree`);
                           throw e2;
                         }
-                        try { shared.assertWorktreeOutsideProject(existingWtPath, rootDir); }
+                        try { assertSafeWorktreePath(existingWtPath); }
                         catch (assertErr) {
                           if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') { _failWorktreePreflight(assertErr); return null; }
                           throw assertErr;
@@ -4604,6 +4676,21 @@ async function spawnAgent(dispatchItem, config) {
     }
   }
 
+  if (worktreePath) {
+    dispatchItem.worktreePath = worktreePath;
+    try {
+      mutateDispatch((dispatch) => {
+        for (const queue of ['pending', 'active']) {
+          const found = (dispatch?.[queue] || []).find(d => d && d.id === id);
+          if (found) found.worktreePath = worktreePath;
+        }
+        return dispatch;
+      });
+    } catch (e) {
+      log('warn', `spawnAgent: failed to persist pre-spawn worktree path for ${id}: ${e.message}`);
+    }
+  }
+
   updateAgentStatus(id, AGENT_STATUS.READY, 'Worktree ready, preparing to spawn process');
 
   if (worktreePath && meta?.source === 'work-item' && meta?.item?.branchStrategy === 'shared-branch') {
@@ -4721,13 +4808,14 @@ async function spawnAgent(dispatchItem, config) {
   const resolvedMaxBudget = shared.resolveAgentMaxBudget(agentConfig, engineConfig);
   const resolvedBare = shared.resolveAgentBareMode(agentConfig, engineConfig);
   // Pool through the persistent ACP worker transport when the selected adapter
-  // opts into that capability and config allows it.
-  const useAgentPool = shared.resolveAgentUseWorkerPool(engineConfig, runtime);
-  if (useAgentPool) {
-    // Idempotent — cheap to call on every pooled dispatch so a live config
-    // change (agentAcpPoolSize / maxConcurrent) takes effect without a
-    // separate engine-restart-only wiring hook.
-    agentWorkerPool.setPoolSize(shared.resolveAgentAcpPoolSize(engineConfig));
+  // opts into that capability and config allows it. keep_processes requires
+  // the cold wrapper so descendant ownership remains enforceable.
+  _syncAgentWorkerPoolConfig(engineConfig);
+  const keepProcessesRequested = !!meta?.item?.meta?.keep_processes || !!dispatchItem.meta?.keep_processes;
+  const agentPoolRequested = shared.resolveAgentUseWorkerPool(engineConfig, runtime);
+  const useAgentPool = agentPoolRequested && !keepProcessesRequested;
+  if (keepProcessesRequested && agentPoolRequested) {
+    log('info', `spawnAgent: disabling ACP worker pool for keep_processes dispatch ${id} so descendants can be reaped safely`);
   }
 
   const prevFailureClass = meta?.item?._lastFailureClass || null;
@@ -4792,6 +4880,18 @@ async function spawnAgent(dispatchItem, config) {
 
   log('info', `Spawning agent: ${agentId} (${id}) in ${cwd}`);
   log('info', `Task type: ${type} | Branch: ${branchName || 'none'}`);
+  dispatchItem.executionCwd = cwd;
+  try {
+    mutateDispatch((dispatch) => {
+      for (const queue of ['pending', 'active']) {
+        const found = (dispatch?.[queue] || []).find(d => d && d.id === id);
+        if (found) found.executionCwd = cwd;
+      }
+      return dispatch;
+    });
+  } catch (e) {
+    log('warn', `spawnAgent: failed to persist execution cwd for ${id}: ${e.message}`);
+  }
 
   // Agent status is derived from dispatch state.
 
@@ -4808,6 +4908,11 @@ async function spawnAgent(dispatchItem, config) {
       || dispatchItem.meta?.keep_processes_skip_workdir_check) {
     childEnv.MINIONS_KEEP_PROCESSES_SKIP_WORKDIR_CHECK = '1';
   }
+  const keepProcessesAllowedCwdRoot = worktreePath
+    || (liveMode && project?.localPath ? path.resolve(String(project.localPath)) : cwd);
+  if (keepProcessesAllowedCwdRoot) {
+    childEnv.MINIONS_KEEP_PROCESSES_ALLOWED_CWD_ROOT = keepProcessesAllowedCwdRoot;
+  }
 
   // W-mpg54mi2000n7b7e — suppress Git's interactive credential prompts and
   // Git Credential Manager's GUI dialog for every agent spawn. Without these,
@@ -4918,9 +5023,9 @@ async function spawnAgent(dispatchItem, config) {
     }
 
     _phaseT.spawnCallStart = Date.now();
-    // P-c5a1f3b8 (Item D — live-mode push/PR-create cwd guard): in live mode
-    // worktreePath stays null, so `cwd` here is project.localPath (it is never
-    // reassigned to a worktree by the `if (worktreePath ...)` block above). The
+    // P-c5a1f3b8 (Item D — live-mode push/PR-create cwd guard): only live mode
+    // leaves worktreePath null with cwd=project.localPath. Worktree-mode
+    // project dispatches, including read-only types, have an isolated path. The
     // agent's `git push -u origin <branch>` and PR-create therefore run in-place
     // against the operator's checkout. This cwd MUST NEVER be null for a mutating
     // live dispatch — shared.resolveSpawnPaths returns cwd === project.localPath
@@ -4959,6 +5064,7 @@ async function spawnAgent(dispatchItem, config) {
         'MINIONS_LIVE_OUTPUT_PATH',
         'MINIONS_STEERING_ACK_DIR',
         'MINIONS_AGENT_CWD',
+        'MINIONS_KEEP_PROCESSES_ALLOWED_CWD_ROOT',
       ];
       const pooledProcessEnv = { ...childEnv };
       const pooledSessionContext = {};
@@ -4971,16 +5077,27 @@ async function spawnAgent(dispatchItem, config) {
         runtime,
         dispatchId: id,
         cwd,
-        model: effectiveModel,
-        effort: requestedEffort,
+        processCwd: _resolveAgentPoolProcessCwd(project, engineConfig),
+        model: runtimeOptions.model,
+        effort: runtimeOptions.effort,
         // Mirrors the CC worker pool's convention (dashboard.js) — a single
         // flat top-level config array, not per-agent-resolved.
         mcpServers: (engineConfig && engineConfig.mcpServers) || [],
         hermeticDirs: addDirs,
         processEnv: pooledProcessEnv,
+        workerOptions: runtimeOptions,
+        sessionId: cachedSessionId,
         sessionContext: pooledSessionContext,
+        agentId,
+        reapDescendants: true,
+        keepProcessesSkipWorkdirCheck: !!(
+          meta?.item?.meta?.keep_processes_skip_workdir_check
+          || dispatchItem.meta?.keep_processes_skip_workdir_check
+        ),
         systemPromptText: systemPrompt,
-        promptText: fullTaskPrompt,
+        // The prompt file may have gained dirty-file or cross-repo dependency
+        // sections after `fullTaskPrompt` was first built.
+        promptText: fs.readFileSync(promptPath, 'utf8'),
       });
       // The child_process PID file is normally written asynchronously by
       // spawn-agent.js itself (engine/spawn-agent.js:606) once it starts.
@@ -5336,6 +5453,24 @@ async function spawnAgent(dispatchItem, config) {
       // Re-expose the engine-resolved cwd on steering resume (matches the
       // initial spawn path) so $MINIONS_AGENT_CWD stays valid across resumes.
       childEnv.MINIONS_AGENT_CWD = cwd;
+      if (keepProcessesAllowedCwdRoot) {
+        childEnv.MINIONS_KEEP_PROCESSES_ALLOWED_CWD_ROOT = keepProcessesAllowedCwdRoot;
+      }
+      try {
+        mutateDispatch((dp) => {
+          const active = dp.active.find((entry) => entry.id === id);
+          if (active) delete active.pooled;
+          return dp;
+        });
+        delete dispatchItem.pooled;
+      } catch (e) {
+        log('warn', `Steering: failed to persist cold-resume mode for ${agentId}: ${e.message}`);
+        try { fs.unlinkSync(steerPromptPath); } catch { /* cleanup */ }
+        activeProcesses.delete(id);
+        completeDispatch(id, DISPATCH_RESULT.ERROR, `Steering state update failed: ${e.message}`);
+        cleanupTempAgent(agentId);
+        return;
+      }
       let resumeProc;
       try {
         // detached so the resumed steering session also survives engine death (matches initial spawn)
@@ -5354,6 +5489,12 @@ async function spawnAgent(dispatchItem, config) {
         cleanupTempAgent(agentId);
         return;
       }
+      const writeResumePid = () => {
+        if (!resumeProc.pid) return;
+        try { fs.writeFileSync(pidFilePath, String(resumeProc.pid)); } catch { /* best-effort */ }
+      };
+      if (resumeProc.pid) writeResumePid();
+      else if (typeof resumeProc.once === 'function') resumeProc.once('spawn', writeResumePid);
 
       // Re-attach to existing tracking — do NOT carry _steeringAt forward (#1052).
       // The kill watcher in timeout.js fires 30s after _steeringAt is set. If we carry it
@@ -5576,8 +5717,12 @@ async function spawnAgent(dispatchItem, config) {
           let evalResult = schemaResult;
           let isWorkdirRejection = false;
           const workdirGateOn = !_kpSkipWorkdir && ENGINE_DEFAULTS.keepProcesses?.requireGitWorkdir !== false;
-          if (schemaResult.exists && schemaResult.accepted && workdirGateOn) {
-            const workdirResult = keepProcessSweep.evaluateKeepPidsAcceptance(agentId, { requireGitWorkdir: true });
+          const allowedCwdRoot = keepProcessesAllowedCwdRoot;
+          if (schemaResult.exists && schemaResult.accepted && (workdirGateOn || allowedCwdRoot)) {
+            const workdirResult = keepProcessSweep.evaluateKeepPidsAcceptance(agentId, {
+              requireGitWorkdir: workdirGateOn,
+              ...(allowedCwdRoot ? { allowedCwdRoot } : {}),
+            });
             if (workdirResult.exists && !workdirResult.accepted && workdirResult.isWorkdirRejection) {
               evalResult = workdirResult;
               isWorkdirRejection = true;
@@ -5672,6 +5817,22 @@ async function spawnAgent(dispatchItem, config) {
             } catch (alertErr) {
               log('warn', `keep-processes acceptance: failed to emit inbox alert for ${agentId}: ${alertErr.message}`);
             }
+          } else if (evalResult.exists && evalResult.accepted) {
+            try {
+              const enriched = {
+                ...(evalResult.parsedRaw || {}),
+                cwd: evalResult.recordedCwd || '',
+                project: project?.name || '',
+                work_type: type,
+                checkout_mode: checkoutModeAtDispatch,
+                dispatch_root: allowedCwdRoot
+                  ? shared.realPathForComparison(allowedCwdRoot)
+                  : '',
+              };
+              fs.writeFileSync(evalResult.filePath, JSON.stringify(enriched, null, 2));
+            } catch (e) {
+              log('warn', `keep-processes acceptance: could not persist checkout provenance for ${agentId}: ${e.message}`);
+            }
           }
         } catch (e) {
           log('warn', `keep-processes acceptance check failed for ${agentId} (${id}): ${e.message}`);
@@ -5699,7 +5860,12 @@ async function spawnAgent(dispatchItem, config) {
       if (_msEnabled) {
         try {
           const managedSpawn = require('./engine/managed-spawn');
-          const evalResult = managedSpawn.evaluateManagedSpawnAcceptance(agentId);
+          const allowedCwdRoot = keepProcessesAllowedCwdRoot;
+          const evalResult = managedSpawn.evaluateManagedSpawnAcceptance(agentId, {
+            projects: getProjects(config),
+            project,
+            ...(allowedCwdRoot ? { allowedCwdRoot } : {}),
+          });
           if (evalResult.exists && !evalResult.accepted) {
             managedSpawnAcceptanceFailure = {
               reason: evalResult.reason,
@@ -5757,6 +5923,9 @@ async function spawnAgent(dispatchItem, config) {
               owner_agent: agentId,
               owner_wi: dispatchItem.meta?.item?.id || '',
               owner_project: project?.name || '',
+              owner_work_type: type,
+              dispatch_root: allowedCwdRoot || '',
+              checkout_mode: checkoutModeAtDispatch,
             };
             const spawnedItems = [];
             let spawnFailureReason = null;
@@ -6097,7 +6266,7 @@ async function spawnAgent(dispatchItem, config) {
     // crashed dispatch leaks `work/W-<id>` worktree entries that block
     // every retry with `fatal: 'work/W-<id>' is already used by worktree
     // at …` until the 2-hour age sweep in cleanup.js eventually catches up.
-    if (worktreePath && rootDir && branchName) {
+    if (worktreePath && rootDir) {
       try {
         const _wgc = require('./engine/worktree-gc');
         const _wtRoot = path.resolve(rootDir, engineConfig.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot);
@@ -6144,7 +6313,7 @@ async function spawnAgent(dispatchItem, config) {
     //    restore is a plain `git checkout <originalRef>` — never --force/reset/
     //    clean/stash — and is best-effort: a thrown restore never alters the
     //    dispatch result.
-    if (liveMode && branchName) {
+    if (liveMode && branchName && shared.isLiveCheckoutDispatchRecord(dispatchItem, getConfig())) {
       try {
         const _liveRestore = require('./engine/live-checkout');
         await _liveRestore.restoreLiveCheckoutAtDispatchEnd({
@@ -6335,6 +6504,10 @@ async function spawnAgent(dispatchItem, config) {
     // ACP worker isn't spawned detached and a fresh pool cold-starts empty —
     // a live worker PID must never be mistaken for a resumable dispatch.
     if (useAgentPool) item.pooled = true;
+    else delete item.pooled;
+    item.checkoutMode = checkoutModeAtDispatch;
+    item.executionCwd = cwd;
+    if (resolvedProjectMeta && item.meta) item.meta.project = resolvedProjectMeta;
     // W-mq5rwwss000f30a7 — persist the worktree path so the live-worktree
     // guard (shared.isWorktreePathLive) can correlate destructive callers
     // (removeWorktree, cleanup orphan-dir sweep, pool-return, quarantine)
@@ -6613,73 +6786,6 @@ function safePrdProjectSlug(projectName) {
   return slug || 'project';
 }
 
-// Fleet branches the engine/CC create. A worktree-mode operator checkout should
-// NEVER sit on one of these (or any branch); when it does, a flow ran raw
-// `git checkout`/`merge` in the live checkout instead of a worktree.
-const _FLEET_BRANCH_RE = /^(cc-pr|backport|e2e|verify|sched-|work)\//;
-
-// Self-heal: a worktree-mode project's operator checkout (project.localPath) must
-// always sit on its mainBranch — agents use isolated worktrees, CC Create-PR uses
-// prepare-create-pr-worktree. But fleet flows (CC raw git, backport, sync)
-// sometimes run `git checkout <branch>` + `git merge` THERE despite the rules,
-// leaving it stuck on a feature branch (often mid-conflict) — which restores
-// git-tracked dead PRDs and pollutes the operator's main, then the materializer
-// re-runs finished work. Detect + restore. Conservative: only acts on a stuck
-// merge/rebase OR a recognizably fleet-created branch, so a human's deliberate
-// `git checkout my-feature` in their checkout is left alone. Branch commits are
-// preserved on their ref (reset --hard only drops the uncommitted hijack state).
-function restoreHijackedOperatorCheckouts(config) {
-  if (config?.engine?.autoRestoreOperatorCheckout === false) return;
-  let projects;
-  try { projects = getProjects(config); } catch { return; }
-  for (const project of projects) {
-    try {
-      const localPath = project?.localPath;
-      if (!localPath || !fs.existsSync(localPath)) continue;
-      if (shared.resolveCheckoutMode(project) === shared.CHECKOUT_MODES.LIVE) continue; // live-mode: feature branch is intentional
-      const main = project.mainBranch || 'main';
-      const opts = { cwd: localPath };
-      // W-mrcvh5hw000o6cf1: use the argv-form (shell: false) git helper instead of
-      // execSilent(). execSilent() shells out via cmd.exe, which cannot chdir into
-      // a UNC path (`//wsl.localhost/...`, `\\server\share\...`) — it silently
-      // falls back to the Windows directory and every git call then fails with
-      // "fatal: not a git repository", every tick, forever, for WSL/UNC-hosted
-      // projects. shellSafeGitSync spawns git.exe directly (execFileSync,
-      // shell:false) so `cwd` is honored even for UNC paths.
-      let isRepo;
-      try { isRepo = String(shared.shellSafeGitSync(['rev-parse', '--is-inside-work-tree'], opts) || '').trim(); }
-      catch { continue; } // not a git repo (or transiently unreachable) — nothing to restore, skip quietly
-      if (isRepo !== 'true') continue;
-      const cur = String(shared.shellSafeGitSync(['rev-parse', '--abbrev-ref', 'HEAD'], opts) || '').trim();
-      if (!cur || cur === 'HEAD' || cur === main) continue; // on main or detached — fine
-      const gitDir = String(shared.shellSafeGitSync(['rev-parse', '--git-dir'], opts) || '').trim();
-      const absGitDir = gitDir ? (path.isAbsolute(gitDir) ? gitDir : path.join(localPath, gitDir)) : path.join(localPath, '.git');
-      const mergeStuck = fs.existsSync(path.join(absGitDir, 'MERGE_HEAD'));
-      const rebaseStuck = fs.existsSync(path.join(absGitDir, 'rebase-merge')) || fs.existsSync(path.join(absGitDir, 'rebase-apply'));
-      if (!mergeStuck && !rebaseStuck && !_FLEET_BRANCH_RE.test(cur)) continue; // likely a human's deliberate checkout — leave it
-      const why = mergeStuck ? ' (stuck merge)' : rebaseStuck ? ' (stuck rebase)' : ' (fleet branch in live checkout)';
-      log('warn', `Operator checkout for ${project.name} is on '${cur}'${why}; worktree-mode requires ${main} — restoring`);
-      if (mergeStuck) shared.shellSafeGitSync(['merge', '--abort'], opts);
-      if (rebaseStuck) shared.shellSafeGitSync(['rebase', '--abort'], opts);
-      shared.shellSafeGitSync(['reset', '--hard', 'HEAD'], opts); // drop uncommitted hijack state; branch commits stay on the ref
-      try { shared.validateGitRef(main); } catch (ve) { throw new Error(`restoreHijackedOperatorCheckouts: invalid mainBranch ${JSON.stringify(main)}: ${ve.message}`); }
-      shared.shellSafeGitSync(['checkout', main], opts);
-      const now = String(shared.shellSafeGitSync(['rev-parse', '--abbrev-ref', 'HEAD'], opts) || '').trim();
-      if (now === main) {
-        try {
-          writeInboxAlert(`operator-checkout-restored-${project.name}`,
-            `Operator checkout ${localPath} was hijacked onto '${cur}'${why} and restored to ${main}. ` +
-            'A fleet flow ran git checkout/merge in the LIVE operator checkout instead of an isolated worktree ' +
-            '(playbooks/shared-rules.md: "Do NOT checkout branches in the main working tree — use worktrees"). ' +
-            `The '${cur}' branch commits are preserved on its ref.`);
-        } catch { /* alert is best-effort */ }
-      } else {
-        log('warn', `Operator checkout restore for ${project.name} did not reach ${main} (now '${now}') — manual intervention needed`);
-      }
-    } catch (e) { log('warn', `restoreHijackedOperatorCheckouts ${project?.name || '?'}: ${e?.message || e}`); }
-  }
-}
-
 function materializePlansAsWorkItems(config) {
   const writePrdLocked = (fileName, data) => {
     return prdStore.writePrd(fileName, data);
@@ -10556,6 +10662,7 @@ async function tickInner() {
   catch (e) { log('warn', `lastTickAt write: ${e.message}`); }
 
   const config = getConfig();
+  _syncAgentWorkerPoolConfig(config.engine);
   tickCount++;
   const now = Date.now();
   const tickIntervalMs = Math.max(1, Number(config.engine?.tickInterval) || ENGINE_DEFAULTS.tickInterval);
@@ -11588,9 +11695,6 @@ async function tickInner() {
     const maxC = resolveMaxConcurrent(config);
     setTempBudget(Math.max(0, maxC - activeCountPre));
   }
-  // Self-heal a hijacked operator checkout BEFORE discovery/materialization, so a
-  // dead PRD restored by a stray `git checkout` can't be re-materialized this tick.
-  try { restoreHijackedOperatorCheckouts(config); } catch (e) { log('warn', 'restoreHijackedOperatorCheckouts: ' + e.message); }
   let discoveryOk = true;
   try { await withTickTimeout(() => discoverWork(config), 'discoverWork', tickOpTimeoutMs); } catch (e) { log('warn', 'discoverWork: ' + e.message); discoveryOk = false; }
   if (_isTickStale(myGeneration)) return;
@@ -11691,7 +11795,6 @@ module.exports = {
   discoverWork, discoverFromPrs, discoverFromWorkItems, discoverCentralWorkItems,
   materializePlansAsWorkItems,
   materializeSpecsAsWorkItems, // exported for testing (P-f7-git-log)
-  restoreHijackedOperatorCheckouts, // exported for testing — operator-checkout self-heal
 
   // Shared helpers (used by lifecycle.js and tests)
   reconcileItemsWithPrs, detectDependencyCycles,
@@ -11704,7 +11807,7 @@ module.exports = {
   buildDepConflictFixItem, deriveConflictFixKey, // exported for testing (W-mpcwojgr000a0244)
   runWorktreeAdd, // exported for testing (W-mqvaxv65000m76f2 — GVFS partial-checkout behavioral test)
   _fetchWithTransientRetry, _classifyFreshBaseFetchFailure, _probeBranchLocally, // exported for testing
-  isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, pushCleanAheadBranch, assertCleanSharedWorktree, _quarantineDirtyWorktree, // exported for testing
+  isWorktreeRetryableError, syncReusedWorktree, pushCleanAheadBranch, assertCleanSharedWorktree, _quarantineDirtyWorktree, // exported for testing
   _statusPorcelainCmd, _killGitDescendantsForWorktree, _bumpQuarantineOutcome, // exported for testing (W-mq5n1zx5)
   _reapWorktreeHolders, _findTerminalWorktreeOwners, // exported for testing (W-mqila0t5 — CWD-pinned holder reap)
   pruneStaleWorktreeForBranch, // exported for testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2383",
+  "version": "0.1.2384",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"