@yemi33/minions 0.1.1984 → 0.1.1986

package/engine/cc-worker-pool.js

@@ -136,6 +136,12 @@ class Worker {
     this.killed = false;
     this.spawnError = null;
     this.firstSystemPromptSent = false;
+    // In-flight spawn+initialize+session/new promise. Set by getSession()
+    // before the worker is registered in _tabs, cleared after the handshake
+    // settles. Racing getSession() callers await this to avoid the
+    // "warm-reuse path returns sessionId=null while init is still pending"
+    // hang on first message of a freshly-warmed tab (W-mpd45blx00072f04).
+    this.initPromise = null;
   }
 
   // ── Spawn + initialize handshake ────────────────────────────────────────
@@ -499,6 +505,31 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
   //   'cold-spawn'  — fresh proc + initialize + session/new
   let lifecycle = 'warm-reuse';
 
+  if (worker) {
+    // W-mpd45blx00072f04: if the existing worker is still mid-init (warm
+    // fired but session/new hasn't resolved yet), await the in-flight init
+    // BEFORE evaluating warm-reuse / newSession / cold-spawn — otherwise we
+    // return a SessionHandle with sessionId=null and the caller's first
+    // session/prompt fires with a null sessionId, causing every subsequent
+    // session/update notification to be dropped by _handleMessage's
+    // sessionId-match guard. User-visible symptom: first message on a
+    // freshly-warmed CC tab hangs (no chunks streamed, eventual onDone
+    // with empty text).
+    if (worker.initPromise) {
+      try {
+        await worker.initPromise;
+      } catch (err) {
+        // Warm init failed (e.g., auth). The originating call has already
+        // (or is about to) delete _tabs[tabId] and close the worker in its
+        // own catch handler. Surface the same error to this caller so the
+        // dashboard's spawn-failed path runs instead of hanging.
+        throw err;
+      }
+      // Re-read in case the failing initPromise's cleanup already ran.
+      worker = _tabs.get(tabId) || null;
+    }
+  }
+
   if (worker) {
     if (worker.killed) {
       _tabs.delete(tabId);
@@ -533,8 +564,24 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
       tabId, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd,
     });
     _tabs.set(tabId, worker);
+    // Set initPromise BEFORE awaiting so concurrent getSession() callers
+    // landing during the spawn+initialize+session/new round-trip can detect
+    // and await it (W-mpd45blx00072f04). Clear on settle so callers that
+    // arrive AFTER init succeeds skip the no-op await. Attach the clear
+    // handler as both success+failure listeners (not .finally()) so the
+    // chained promise has a rejection handler and doesn't surface as an
+    // unhandled rejection when init throws.
+    const initPromise = worker._spawnAndInit();
+    worker.initPromise = initPromise;
+    const clearInit = () => {
+      // Only clear if we're still the active promise — defensive against
+      // a future refactor that calls _spawnAndInit twice for the same
+      // Worker (current code path never does).
+      if (worker.initPromise === initPromise) worker.initPromise = null;
+    };
+    initPromise.then(clearInit, clearInit);
     try {
-      await worker._spawnAndInit();
+      await initPromise;
     } catch (err) {
       _tabs.delete(tabId);
       try { worker.close(); } catch { /* already torn down */ }

package/engine/cleanup.js

@@ -273,35 +273,42 @@ function _killProcessInWorktree(dir, activeProcesses, activeIds) {
     log('info', `Killed orphaned process for dispatch ${id} before worktree removal`);
   }
 
-  // Check PID files in engine/tmp/ — only kill if no active dispatch matches
+  // Check PID files in engine/tmp/ — both legacy flat layout and per-dispatch
+  // dirs (P-f6-tmp-toctou). Only kill if no active dispatch matches.
   try {
-    const tmpDir = path.join(ENGINE_DIR, 'tmp');
-    for (const f of fs.readdirSync(tmpDir)) {
-      if (!f.startsWith('pid-') || !f.endsWith('.pid')) continue;
-      const pidFileName = f.replace(/^pid-/, '').replace(/\.pid$/, '');
-      if (!dirLower.includes(pidFileName.slice(-8))) continue;
+    shared.forEachPidFile((pidFilePath, fileName, layout) => {
+      const pidFileName = fileName.replace(/^pid-/, '').replace(/\.pid$/, '');
+      if (!dirLower.includes(pidFileName.slice(-8))) return;
       // Verify this PID file's dispatch is not active
       let isActive = false;
       for (const id of activeIds) { if (pidFileName.includes(id.slice(-8))) { isActive = true; break; } }
-      if (isActive) continue; // still active — do not kill
-      const pid = parseInt(fs.readFileSync(path.join(tmpDir, f), 'utf8').trim(), 10);
+      if (isActive) return; // still active — do not kill
+      let pid;
+      try { pid = parseInt(fs.readFileSync(pidFilePath, 'utf8').trim(), 10); }
+      catch { return; }
       if (pid > 0) {
         // Verify the PID still belongs to a Minions runtime process before killing.
         // The shared helper inspects the PID's full command line for `claude` /
         // `copilot` so a recycled PID running an unrelated process is skipped.
         try {
           if (process.platform === 'win32') {
-            if (!shared.isProcessCommandLineMatchingAgent(pid)) continue;
+            if (!shared.isProcessCommandLineMatchingAgent(pid)) return;
             exec(`taskkill /F /T /PID ${pid}`, { stdio: 'pipe', timeout: 5000, windowsHide: true });
           } else {
-            if (!shared.isProcessCommandLineMatchingAgent(pid)) continue;
+            if (!shared.isProcessCommandLineMatchingAgent(pid)) return;
             try { process.kill(-pid, 'SIGKILL'); } catch { process.kill(pid, 'SIGKILL'); }
           }
-          log('info', `Killed orphaned PID ${pid} (${f}) before worktree removal`);
+          log('info', `Killed orphaned PID ${pid} (${fileName}, ${layout}) before worktree removal`);
         } catch {} // process may already be dead
       }
-      try { fs.unlinkSync(path.join(tmpDir, f)); } catch {}
-    }
+      if (layout === 'dispatch-dir') {
+        // Remove the entire per-dispatch dir — its remaining sidecars are
+        // orphans of the same dead process.
+        try { shared.removeDispatchTmpDir(path.dirname(pidFilePath)); } catch {}
+      } else {
+        try { fs.unlinkSync(pidFilePath); } catch {}
+      }
+    });
   } catch {} // tmp dir may not exist
 }
 
@@ -313,9 +320,35 @@ async function runCleanup(config, verbose = false) {
   let cleaned = { tempFiles: 0, liveOutputs: 0, worktrees: 0, zombies: 0 };
 
   // 1. Clean stale temp prompt/sysprompt files and orphaned safeWrite .tmp.* files (older than 1 hour)
+  // P-f6-tmp-toctou: also sweep abandoned per-dispatch dirs (engine/tmp/dispatch-*),
+  // and recurse into them so leftover prompt/sysprompt sidecars from crashed
+  // dispatches don't accumulate.
   const oneHourAgo = Date.now() - 3600000;
   const tmpDir = path.join(ENGINE_DIR, 'tmp');
   const scanDirs = [ENGINE_DIR, ...(fs.existsSync(tmpDir) ? [tmpDir] : [])];
+  // Discover dispatch-* dirs under engine/tmp/ and scan their contents too.
+  if (fs.existsSync(tmpDir)) {
+    try {
+      for (const entry of fs.readdirSync(tmpDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (!entry.name.startsWith('dispatch-')) continue;
+        const full = path.join(tmpDir, entry.name);
+        if (!shared.validateDispatchTmpDir(full)) continue;
+        scanDirs.push(full);
+      }
+    } catch { /* tmp dir may be empty/missing */ }
+  }
+  // Track which dispatch dirs we touch so we can rm empty ones whose owning
+  // dispatch is no longer in the active set.
+  const activeDispatchTmpDirs = new Set();
+  try {
+    const dispatch = getDispatch();
+    for (const queue of ['pending', 'active']) {
+      for (const e of dispatch[queue] || []) {
+        if (e?.tmpDir) activeDispatchTmpDirs.add(path.resolve(e.tmpDir));
+      }
+    }
+  } catch { /* dispatch.json may be empty */ }
   for (const dir of scanDirs) {
     // Each directory gets its own try-catch so one failure doesn't abort other directories (Bug #27)
     let dirEntries;
@@ -341,6 +374,22 @@ async function runCleanup(config, verbose = false) {
       }
     }
   }
+  // Reap empty/stale per-dispatch tmp dirs not referenced by an active entry.
+  cleaned.dispatchDirs = 0;
+  if (fs.existsSync(tmpDir)) {
+    try {
+      for (const entry of fs.readdirSync(tmpDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.startsWith('dispatch-')) continue;
+        const full = path.join(tmpDir, entry.name);
+        if (!shared.validateDispatchTmpDir(full)) continue;
+        if (activeDispatchTmpDirs.has(path.resolve(full))) continue;
+        let stat;
+        try { stat = fs.statSync(full); } catch { continue; }
+        if (stat.mtimeMs >= oneHourAgo) continue;
+        if (shared.removeDispatchTmpDir(full)) cleaned.dispatchDirs++;
+      }
+    } catch { /* sweep is best-effort */ }
+  }
 
   // 2. Clean live-output.log and live-output-prev.log for idle agents (not currently working)
   for (const [agentId] of Object.entries(config.agents || {})) {
@@ -1111,31 +1160,31 @@ async function runCleanup(config, verbose = false) {
   } catch (e) { log('warn', 'cap cooldowns: ' + e.message); }
 
   // 12. Clean stale PID files — remove PID files whose process is no longer running
+  // P-f6-tmp-toctou: walks BOTH legacy flat layout and per-dispatch-dir layout
+  // via shared.forEachPidFile.
   cleaned.pidFiles = 0;
   try {
     const tmpDir = path.join(ENGINE_DIR, 'tmp');
     if (fs.existsSync(tmpDir)) {
-      let pidDirEntries;
-      try { pidDirEntries = fs.readdirSync(tmpDir); } catch { pidDirEntries = []; }
       const activePids = new Set();
       for (const [, info] of activeProcesses) {
         if (info.proc?.pid) activePids.add(String(info.proc.pid));
       }
-      for (const f of pidDirEntries) {
-        if (!f.startsWith('pid-') || !f.endsWith('.pid')) continue;
-        const fp = path.join(tmpDir, f);
+      shared.forEachPidFile((pidFilePath, fileName, layout) => {
         try {
-          const pidStr = fs.readFileSync(fp, 'utf8').trim();
+          const pidStr = fs.readFileSync(pidFilePath, 'utf8').trim();
           // Skip if actively tracked
-          if (activePids.has(pidStr)) continue;
+          if (activePids.has(pidStr)) return;
           // Check if file is stale (>1 hour old)
-          const stat = fs.statSync(fp);
+          const stat = fs.statSync(pidFilePath);
           if (stat.mtimeMs < oneHourAgo) {
-            fs.unlinkSync(fp);
+            fs.unlinkSync(pidFilePath);
             cleaned.pidFiles++;
+            // For dispatch-dir layout, the empty/stale dispatch dir gets reaped
+            // by the stale-dispatch-dir sweep in step 1.
           }
         } catch { /* cleanup */ }
-      }
+      });
     }
   } catch (e) { log('warn', 'clean stale PID files: ' + e.message); }
 

package/engine/cli.js

@@ -57,7 +57,9 @@ function dispatchSafeId(itemId) {
 }
 
 function readDispatchPid(itemId) {
-  const pidFile = path.join(ENGINE_DIR, 'tmp', `pid-${dispatchSafeId(itemId)}.pid`);
+  // P-f6-tmp-toctou: prefer per-dispatch dir layout, fall back to legacy flat.
+  const pidFile = shared.findDispatchPidFile(itemId);
+  if (!pidFile) return null;
   let raw;
   try { raw = fs.readFileSync(pidFile, 'utf8').trim(); }
   catch { return null; }
@@ -90,6 +92,32 @@ function summarizeActiveDispatchPids(activeItems = []) {
   return summary;
 }
 
+// W-mpcyvff6000pf828 (#2653) — Heartbeat writer decoupled from tickInner.
+// `writeHeartbeatNow` mirrors the legacy in-tick write (synchronous, fast,
+// non-throwing) but is driven from the main start loop on a 15s setInterval
+// instead. See engine.js#tickInner for the load-bearing rationale comment.
+const HEARTBEAT_INTERVAL_MS = 15000;
+
+function writeHeartbeatNow() {
+  try {
+    // Synchronous callback inside the lock — just `s.heartbeat = Date.now()`,
+    // no awaits, no other state mutation. Mirrors mutateControl's contract.
+    shared.mutateControl(c => { c.heartbeat = Date.now(); return c; });
+  } catch (err) {
+    try { engine().log('warn', `write heartbeat: ${err.message}`); }
+    catch { /* during shutdown logger can be torn down — silent */ }
+  }
+}
+
+// Factory used by tests to drive the heartbeat interval without spinning up
+// the full engine start loop. Returns the underlying timer so callers (the
+// real start handler in production, tests in unit/engine-heartbeat.test.js)
+// can clearInterval(...) on shutdown. Default to the production cadence.
+function createHeartbeatInterval(intervalMs = HEARTBEAT_INTERVAL_MS, writer = writeHeartbeatNow) {
+  return setInterval(writer, intervalMs);
+}
+
+
 function createControlOwner(pid = process.pid) {
   return { pid, ownerToken: `${pid}-${shared.uid()}` };
 }
@@ -162,6 +190,7 @@ const CLI_COMMAND_DOCS = Object.freeze({
   doctor:     { args: '',                      summary: 'Check prerequisites and runtime health' },
   config:     { args: 'set-cli <R> [--model M]', summary: 'Persist defaultCli/defaultModel without starting' },
   pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh' },
+  bridge:     { args: 'status|health|enable|disable',         summary: 'Constellation bridge: toggle and inspect the read-only cross-repo feed' },
 });
 
 function formatCliCommandHelpLines() {
@@ -872,6 +901,18 @@ const commands = {
     // Start tick loop
     const tickTimer = setInterval(() => e.tick(), interval);
 
+    // W-mpcyvff6000pf828 (#2653) — Heartbeat decoupled from tickInner.
+    // The dashboard flips the engine badge to STALE when
+    // `Date.now() - control.heartbeat > 120000`; tying the write to tickInner
+    // meant any legitimately slow tick (cold runtime spawn, sequential
+    // ADO/gh polls, slow worktree create) blocked the next heartbeat and
+    // surfaced a healthy engine as crashed. We now write every 15s on a
+    // dedicated interval — 8× headroom vs the 120s threshold even under
+    // event-loop pressure, and orders of magnitude under TICK_TIMEOUT_MS so
+    // a hung tick still looks distinct from a wedged event loop.
+    writeHeartbeatNow(); // prime control.heartbeat immediately
+    const heartbeatTimer = setInterval(writeHeartbeatNow, HEARTBEAT_INTERVAL_MS);
+
     // Fast poll: check steering every 1s (lightweight — just fs.stat per agent)
     // and wakeup signals every 1s (control.json read)
     const { checkSteering } = require('./timeout');
@@ -948,6 +989,7 @@ const commands = {
       console.log(`\n${signal} received — initiating graceful shutdown...`);
       clearInterval(tickTimer);
       clearInterval(fastPollTimer);
+      clearInterval(heartbeatTimer);
       for (const f of _watchedFiles) { try { fs.unwatchFile(f); } catch { /* cleanup */ } }
       const stoppingAt = e.ts();
       const stoppingWrite = markControlStoppingForOwner(controlOwner, stoppingAt);
@@ -1528,13 +1570,10 @@ const commands = {
     const shared = require('./shared');
 
     // Kill processes via PID files (expensive — outside dispatch lock).
-    // PID files live in engine/tmp/ (see engine/spawn-agent.js:220 — derived from
-    // the prompt-<id>.md sidecar path that engine.js builds in engine/tmp/).
-    // Reading from ENGINE_DIR directly is a no-op: spawn-agent never writes there.
-    const pidDir = path.join(ENGINE_DIR, 'tmp');
-    const pidFiles = shared.safeReadDir(pidDir).filter(f => f.startsWith('pid-') && f.endsWith('.pid'));
-    for (const f of pidFiles) {
-      const pidPath = path.join(pidDir, f);
+    // PID files live in engine/tmp/ — both legacy flat layout
+    // (`pid-<id>.pid`) and per-dispatch dirs (`dispatch-<id>-XXX/pid-<id>.pid`)
+    // post-P-f6-tmp-toctou. shared.forEachPidFile visits both.
+    shared.forEachPidFile((pidPath, fileName, layout) => {
       const raw = safeRead(pidPath).trim();
       // Guard against falsy/zero/NaN PIDs. Empty pid files would resolve to
       // Number('') === 0, and process.kill(0) on POSIX targets the entire
@@ -1542,13 +1581,17 @@ const commands = {
       let pidNum = NaN;
       try { pidNum = shared.validatePid(raw); } catch { /* invalid — skip */ }
       if (pidNum > 0) {
-        try { process.kill(pidNum); console.log(`Killed process ${pidNum} (${f})`); }
+        try { process.kill(pidNum); console.log(`Killed process ${pidNum} (${fileName})`); }
         catch { console.log(`Process ${pidNum} already dead`); }
       } else {
-        console.log(`Skipping ${f}: invalid or empty PID`);
+        console.log(`Skipping ${fileName}: invalid or empty PID`);
       }
-      try { fs.unlinkSync(pidPath); } catch { /* may not exist */ }
-    }
+      if (layout === 'dispatch-dir') {
+        try { shared.removeDispatchTmpDir(path.dirname(pidPath)); } catch { /* may not exist */ }
+      } else {
+        try { fs.unlinkSync(pidPath); } catch { /* may not exist */ }
+      }
+    });
 
     // Atomically read and clear dispatch.active (locked read-modify-write)
     let killed = [];
@@ -1776,6 +1819,116 @@ const commands = {
       console.error(`error: ${e.message}`);
       process.exit(1);
     }
+  },
+
+  // `minions bridge <subcommand>` — Constellation read-only bridge surface.
+  // Owns the on/off flag and the marker-file projection used by the
+  // Constellation agent. Bridge polling logic itself lives in the
+  // Constellation repo (P-wi1-bridge-readonly).
+  //
+  // Subcommands:
+  //   status   Print enabled flag + last-seen Constellation agent timestamp.
+  //   health   Probe http://127.0.0.1:7331/api/status and print the same
+  //            curated projection the Constellation bridge would consume.
+  //   enable   Atomically set engine.constellationBridge.enabled = true.
+  //   disable  Atomically set engine.constellationBridge.enabled = false.
+  bridge(subcmd, ...rest) {
+    const bridge = require('./bridge');
+    const BRIDGE_USAGE = 'Usage: minions bridge <status|health|enable|disable>';
+
+    if (!subcmd || subcmd === 'help' || subcmd === '--help' || subcmd === '-h') {
+      console.log(BRIDGE_USAGE);
+      console.log('');
+      console.log('  status   Show enabled flag + last-seen Constellation agent timestamp');
+      console.log('  health   Probe http://127.0.0.1:7331/api/status and print bridge projection');
+      console.log('  enable   Set engine.constellationBridge.enabled = true');
+      console.log('  disable  Set engine.constellationBridge.enabled = false');
+      return;
+    }
+
+    if (rest.length > 0) {
+      console.error(`error: unexpected arguments after bridge ${subcmd}: ${rest.join(' ')}`);
+      process.exit(2);
+    }
+
+    if (subcmd === 'enable' || subcmd === 'disable') {
+      const enabled = subcmd === 'enable';
+      const { previous, current } = bridge.setBridgeEnabled(enabled);
+      const verb = previous === current ? 'already' : 'now';
+      console.log(`bridge: ${verb} ${current ? 'enabled' : 'disabled'}`);
+      console.log('  config: engine.constellationBridge.enabled = ' + current);
+      if (!previous && current) {
+        console.log('  note: Constellation-side bridge must also be enabled to project state.');
+      }
+      return;
+    }
+
+    if (subcmd === 'status') {
+      const config = getConfig();
+      const enabled = bridge.isBridgeEnabled(config);
+      console.log(`bridge: ${enabled ? 'enabled' : 'disabled'}`);
+      console.log('  config: engine.constellationBridge.enabled = ' + enabled);
+      const marker = bridge.readBridgeMarker();
+      if (!marker) {
+        console.log('  marker: no Constellation agent has registered yet');
+        console.log(`  (expected at ${bridge.CONSTELLATION_BRIDGE_MARKER_PATH})`);
+      } else {
+        console.log(`  last seen: ${bridge.formatRelativeAge(marker.lastSeenAt)} (${marker.lastSeenAt})`);
+        if (marker.agentVersion) console.log(`  agent version: ${marker.agentVersion}`);
+        if (marker.source) console.log(`  source: ${marker.source}`);
+      }
+      return;
+    }
+
+    if (subcmd === 'health') {
+      const http = require('http');
+      const req = http.get(
+        { hostname: '127.0.0.1', port: 7331, path: '/api/status', timeout: 5000 },
+        (res) => {
+          let body = '';
+          res.setEncoding('utf8');
+          res.on('data', (chunk) => { body += chunk; });
+          res.on('end', () => {
+            if (res.statusCode !== 200) {
+              console.error(`error: dashboard returned HTTP ${res.statusCode}`);
+              process.exit(1);
+            }
+            let parsed;
+            try { parsed = JSON.parse(body); }
+            catch (e) {
+              console.error(`error: dashboard response was not JSON: ${e.message}`);
+              process.exit(1);
+            }
+            const projection = bridge.projectStatusForBridge(parsed);
+            if (!projection) {
+              console.error('error: dashboard /api/status returned an unexpected shape');
+              process.exit(1);
+            }
+            console.log('bridge: dashboard reachable on http://127.0.0.1:7331');
+            console.log('  projection (same fields the Constellation bridge would read):');
+            for (const [k, v] of Object.entries(projection)) {
+              console.log(`    ${k}: ${v === null ? '(unknown)' : v}`);
+            }
+          });
+        }
+      );
+      req.on('timeout', () => {
+        req.destroy(new Error('connect timeout'));
+      });
+      req.on('error', (err) => {
+        if (err.code === 'ECONNREFUSED') {
+          console.error('error: dashboard not running on :7331 — start it with `minions dash`');
+        } else {
+          console.error(`error: ${err.message}`);
+        }
+        process.exit(1);
+      });
+      return;
+    }
+
+    console.error(`Unknown bridge subcommand: ${subcmd}`);
+    console.error(BRIDGE_USAGE);
+    process.exit(2);
   }
 };
 
@@ -1799,4 +1952,8 @@ module.exports = {
   _readDispatchPid: readDispatchPid,
   _normalizeSessionBranch: normalizeSessionBranch,
   _dispatchSessionBranch: dispatchSessionBranch,
+  // W-mpcyvff6000pf828 (#2653) — heartbeat writer + factory exported for tests
+  _writeHeartbeatNow: writeHeartbeatNow,
+  _createHeartbeatInterval: createHeartbeatInterval,
+  _HEARTBEAT_INTERVAL_MS: HEARTBEAT_INTERVAL_MS,
 };

package/engine/dispatch.js

@@ -343,6 +343,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
     const neverRetry = new Set([
       FAILURE_CLASS.CONFIG_ERROR,
       FAILURE_CLASS.PERMISSION_BLOCKED,
+      FAILURE_CLASS.AUTH, // W-mpcuc8i80003a7b3 — git/network credential failure; mechanical retry won't fix missing az / GCM creds
       FAILURE_CLASS.WORKTREE_PREFLIGHT, // pre-spawn worktree validation — recompute will produce the same failure
       FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR, // W-mp6k7ywi000fa33c — keep-pids cwd is not a real git worktree; re-running won't fix the structural issue
       FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA, // W-mp7i902u000l991f — keep-pids.json failed shape validation; re-running with the same wrong file won't fix it
@@ -653,6 +654,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
             [FAILURE_CLASS.OUT_OF_CONTEXT]: 'context window exhausted',
             [FAILURE_CLASS.CONFIG_ERROR]: 'configuration error',
             [FAILURE_CLASS.PERMISSION_BLOCKED]: 'permission or auth failure',
+            [FAILURE_CLASS.AUTH]: 'ADO/git authentication failed (missing or expired credentials)',
             [FAILURE_CLASS.WORKTREE_PREFLIGHT]: 'worktree preflight rejected (nested in project root or rootDir collapsed to drive root)',
             [FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR]: 'keep_processes cwd is not a real git worktree (rerun in a `git worktree add` directory)',
             [FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA]: 'keep-pids.json failed shape validation (wrong keys/types/values — see inbox alert for the canonical shape)',
@@ -821,6 +823,7 @@ function cleanDispatchEntries(matchFn) {
   let removed = 0;
   const pidsToKill = [];
   const filesToDelete = [];
+  const dispatchDirsToRemove = [];
   try {
     mutateJsonFileLocked(dispatchPath, (dispatch) => {
       for (const queue of ['pending', 'active', 'completed']) {
@@ -829,17 +832,26 @@ function cleanDispatchEntries(matchFn) {
         if (queue === 'active') {
           for (const d of dispatch[queue]) {
             if (!matchFn(d)) continue;
-            // PID files live in engine/tmp/ (see engine/spawn-agent.js:220 — derived
-            // from the prompt-<id>.md path that engine.js builds in engine/tmp/).
-            const pidFile = path.join(tmpDir, `pid-${d.id}.pid`);
-            try {
-              const pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim());
-              if (pid) pidsToKill.push(pid);
-            } catch { /* PID file may not exist */ }
-            filesToDelete.push(pidFile);
-            filesToDelete.push(path.join(tmpDir, `prompt-${d.id}.md`));
-            filesToDelete.push(path.join(tmpDir, `sysprompt-${d.id}.md`));
-            filesToDelete.push(path.join(tmpDir, `sysprompt-${d.id}.md.tmp`));
+            // P-f6-tmp-toctou: prefer the dispatch's recorded tmpDir. Fall
+            // back to legacy flat layout for active dispatches that pre-date
+            // the per-dispatch-dir layout. shared.findDispatchPidFile honors
+            // the same resolution order so we agree on which PID to kill.
+            const pidPath = shared.findDispatchPidFile(d);
+            if (pidPath) {
+              try {
+                const pid = parseInt(fs.readFileSync(pidPath, 'utf8').trim());
+                if (pid) pidsToKill.push(pid);
+              } catch { /* PID file may not exist */ }
+            }
+            if (d.tmpDir && shared.validateDispatchTmpDir(d.tmpDir)) {
+              dispatchDirsToRemove.push(d.tmpDir);
+            } else {
+              // Legacy individual-file cleanup for pre-migration entries.
+              filesToDelete.push(path.join(tmpDir, `pid-${d.id}.pid`));
+              filesToDelete.push(path.join(tmpDir, `prompt-${d.id}.md`));
+              filesToDelete.push(path.join(tmpDir, `sysprompt-${d.id}.md`));
+              filesToDelete.push(path.join(tmpDir, `sysprompt-${d.id}.md.tmp`));
+            }
           }
         }
         dispatch[queue] = dispatch[queue].filter(d => !matchFn(d));
@@ -863,6 +875,9 @@ function cleanDispatchEntries(matchFn) {
   for (const fp of filesToDelete) {
     try { fs.unlinkSync(fp); } catch { /* may not exist */ }
   }
+  for (const dir of dispatchDirsToRemove) {
+    shared.removeDispatchTmpDir(dir);
+  }
   return removed;
 }