@yemi33/minions 0.1.2238 → 0.1.2239

package/engine/queries.js

@@ -526,6 +526,61 @@ function _wiIdFromNoteFrontmatter(fm) {
   return fm.work_item || fm.wi || fm.sourceItem || null;
 }
 
+// Archive notes-by-WI cache. The archive dir accumulates thousands of
+// immutable note files (2000+ and growing); reading + frontmatter-parsing all
+// of them was the single dominant SYNCHRONOUS cost inside getWorkItems()
+// (measured: multiple seconds with a cold OS file cache, a few hundred ms warm)
+// — and getWorkItems runs on a 1 s TTL, so the dashboard re-read the whole
+// archive every few seconds. That blocked the dashboard event loop and starved
+// the Command Center SSE heartbeat into stalls + reconnects. Archive files are
+// written once (consolidation moves inbox → archive and never edits in place),
+// so an mtime-gated cache on the archive DIRECTORY is safe: any add/remove
+// bumps the dir mtime and busts the cache; the TTL is a belt-and-suspenders
+// backstop. Inbox is NOT cached here — it is tiny and churns constantly, so
+// _buildNotesByWiMap scans it fresh every call (see below).
+let _archiveNotesByWiCache = null;
+let _archiveNotesByWiCacheAt = 0;
+let _archiveNotesByWiCacheMtime = null;
+// The dir-mtime gate is the PRIMARY freshness signal (NTFS/POSIX bump the
+// archive dir mtime on every add/remove/rename, so a newly-archived note busts
+// the cache on the next call). The TTL is only a belt-and-suspenders backstop
+// for the rare FS that misses an mtime update — kept long so we don't pay the
+// full multi-thousand-file re-read on a fixed cadence when nothing changed.
+const ARCHIVE_NOTES_BY_WI_TTL = 300000; // 5 min
+
+function _buildArchiveNotesByWiMap() {
+  let dirMtime = null;
+  try { dirMtime = fs.statSync(ARCHIVE_DIR).mtimeMs; } catch { dirMtime = null; }
+  const now = Date.now();
+  if (_archiveNotesByWiCache
+    && (now - _archiveNotesByWiCacheAt) < ARCHIVE_NOTES_BY_WI_TTL
+    && _archiveNotesByWiCacheMtime === dirMtime) {
+    return _archiveNotesByWiCache;
+  }
+  const out = Object.create(null);
+  for (const f of safeReadDir(ARCHIVE_DIR)) {
+    if (!f.endsWith('.md')) continue;
+    const fm = _parseNoteFrontmatter(safeRead(path.join(ARCHIVE_DIR, f)));
+    const wiId = _wiIdFromNoteFrontmatter(fm);
+    if (!wiId) continue;
+    if (!out[wiId]) out[wiId] = [];
+    out[wiId].push('archive:' + f);
+  }
+  _archiveNotesByWiCache = out;
+  _archiveNotesByWiCacheAt = now;
+  _archiveNotesByWiCacheMtime = dirMtime;
+  return out;
+}
+
+// Test/maintenance hook — drop the archive notes cache (mirrors the other
+// invalidate* helpers). Not normally needed: the cache self-heals via the
+// dir-mtime gate + TTL.
+function invalidateArchiveNotesByWiCache() {
+  _archiveNotesByWiCache = null;
+  _archiveNotesByWiCacheAt = 0;
+  _archiveNotesByWiCacheMtime = null;
+}
+
 // Build a wiId → [filename, ...] map by scanning the inbox + archive dirs.
 // Archive entries are prefixed with `archive:` so the dashboard renderer can
 // tell them apart (matches the convention already used by _artifacts.notes).
@@ -537,17 +592,18 @@ function _buildNotesByWiMap() {
     if (!out[wiId]) out[wiId] = [];
     if (!out[wiId].includes(token)) out[wiId].push(token);
   };
+  // Inbox: tiny and churns constantly — scan fresh every call.
   for (const f of safeReadDir(INBOX_DIR)) {
     if (!f.endsWith('.md')) continue;
     const fm = _parseNoteFrontmatter(safeRead(path.join(INBOX_DIR, f)));
     const wiId = _wiIdFromNoteFrontmatter(fm);
     if (wiId) addNote(wiId, f);
   }
-  for (const f of safeReadDir(ARCHIVE_DIR)) {
-    if (!f.endsWith('.md')) continue;
-    const fm = _parseNoteFrontmatter(safeRead(path.join(ARCHIVE_DIR, f)));
-    const wiId = _wiIdFromNoteFrontmatter(fm);
-    if (wiId) addNote(wiId, 'archive:' + f);
+  // Archive: large + immutable — served from the mtime-gated cache so we don't
+  // re-read thousands of files on every getWorkItems() rebuild.
+  const archiveMap = _buildArchiveNotesByWiMap();
+  for (const wiId in archiveMap) {
+    for (const token of archiveMap[wiId]) addNote(wiId, token);
   }
   return out;
 }
@@ -635,7 +691,11 @@ function getAgentStatus(agentId) {
     const staleOrphanTimeout = config.engine?.heartbeatTimeout || ENGINE_DEFAULTS.heartbeatTimeout;
     const staleThresholdMs = staleOrphanTimeout * 2;
     const now = Date.now();
-    const allItems = getWorkItems(config);
+    // Lean read — this fallback only inspects core fields (dispatched_to,
+    // status, dispatched_at, …), never _pr/_artifacts/_notes. Skipping
+    // enrichment keeps the per-idle-agent getAgents() roster build off the
+    // heavy detail-modal path. (Fix #3 — dashboard event-loop perf.)
+    const allItems = getWorkItems(config, { enrich: false });
     const latestInFlight = allItems
       .filter(w => {
         if ((w.dispatched_to || '').toLowerCase() !== String(agentId).toLowerCase()) return false;
@@ -1711,10 +1771,24 @@ function getKnowledgeBaseIndex() {
 let _workItemsCache = null;
 let _workItemsCacheAt = 0;
 let _workItemsCacheMtimes = null;
+// Lean cache for getWorkItems(config, { enrich: false }) — core fields only,
+// skipping the PR cross-reference + per-item _artifacts/_notes detail-modal
+// enrichment (the synchronous KB-scan + agent-dir reads that the detail modal
+// needs but hot callers don't). getAgentStatus()'s per-idle-agent fallback and
+// count-only callers use this so the agent roster / CC preamble never pay the
+// enrichment cost. Held separately so an enrich:false caller can't poison the
+// enriched cache (and vice-versa) — readAllWorkItems() returns fresh row
+// objects each call, so the two caches never share mutable references.
+let _workItemsLeanCache = null;
+let _workItemsLeanCacheAt = 0;
+let _workItemsLeanCacheMtimes = null;
 function invalidateWorkItemsCache() {
   _workItemsCache = null;
   _workItemsCacheAt = 0;
   _workItemsCacheMtimes = null;
+  _workItemsLeanCache = null;
+  _workItemsLeanCacheAt = 0;
+  _workItemsLeanCacheMtimes = null;
 }
 
 function _workItemsFilePaths(config) {
@@ -1744,14 +1818,29 @@ function _workItemsMtimesDiffer(prev, curr) {
   return false;
 }
 
-function getWorkItems(config) {
+// getWorkItems(config, { enrich })
+//   enrich (default true): also cross-reference PRs and populate the
+//     detail-modal _artifacts/_notes fields. The /api/work-items list payload
+//     needs these (PR badges + note chips).
+//   enrich: false — core fields only (status, dispatched_to, depends_on, …)
+//     plus the cheap dispatch cross-reference. Skips the synchronous PR
+//     cross-ref and per-item KB/agent-dir enrichment. Use from hot callers that
+//     never read _artifacts/_notes (getAgentStatus fallback, count-only callers)
+//     so the agent roster / CC preamble don't pay the enrichment cost on every
+//     cold rebuild.
+function getWorkItems(config, opts) {
+  const enrich = !(opts && opts.enrich === false);
   const now = Date.now();
   config = config || getConfig();
-  if (_workItemsCache && (now - _workItemsCacheAt) < 1000) {
+  if (enrich) {
+    if (_workItemsCache && (now - _workItemsCacheAt) < 1000) {
+      const currMtimes = _snapshotWorkItemsMtimes(config);
+      if (!_workItemsMtimesDiffer(_workItemsCacheMtimes, currMtimes)) return _workItemsCache;
+    }
+  } else if (_workItemsLeanCache && (now - _workItemsLeanCacheAt) < 1000) {
     const currMtimes = _snapshotWorkItemsMtimes(config);
-    if (!_workItemsMtimesDiffer(_workItemsCacheMtimes, currMtimes)) return _workItemsCache;
+    if (!_workItemsMtimesDiffer(_workItemsLeanCacheMtimes, currMtimes)) return _workItemsLeanCache;
   }
-  const projects = getProjects(config);
   let allItems = [];
 
   // SQL is the canonical (and only) work-items store after Phase 9.
@@ -1795,6 +1884,10 @@ function getWorkItems(config) {
     }
   }
 
+  // Detail-modal enrichment (PR cross-ref + _artifacts/_notes). Skipped for
+  // enrich:false callers — see the getWorkItems header.
+  if (enrich) {
+  const projects = getProjects(config);
   // Cross-reference with PRs
   const allPrs = getPullRequests(config);
   for (const item of allItems) {
@@ -1890,6 +1983,7 @@ function getWorkItems(config) {
     const mentions = _notesByWi[item.id];
     if (mentions && mentions.length > 0) item._notes = mentions;
   }
+  } // end if (enrich)
 
   const statusOrder = {
     pending: 0,
@@ -1906,9 +2000,16 @@ function getWorkItems(config) {
     return (b.created || '').localeCompare(a.created || '');
   });
 
-  _workItemsCache = allItems;
-  _workItemsCacheAt = now;
-  _workItemsCacheMtimes = _snapshotWorkItemsMtimes(config);
+  const cacheMtimes = _snapshotWorkItemsMtimes(config);
+  if (enrich) {
+    _workItemsCache = allItems;
+    _workItemsCacheAt = now;
+    _workItemsCacheMtimes = cacheMtimes;
+  } else {
+    _workItemsLeanCache = allItems;
+    _workItemsLeanCacheAt = now;
+    _workItemsLeanCacheMtimes = cacheMtimes;
+  }
   return allItems;
 }
 
@@ -3103,7 +3204,7 @@ module.exports = {
   getKnowledgeBaseEntries, getKnowledgeBaseEntriesSnapshot, getKnowledgeBaseIndex,
 
   // Work items & PRD
-  getWorkItems, invalidateWorkItemsCache, getPrdInfo,
+  getWorkItems, invalidateWorkItemsCache, invalidateArchiveNotesByWiCache, getPrdInfo,
 
   // W-mq5uzmc6001d708f — test hooks for the defensive PR enrichment cache.
   _resetPrEnrichmentCacheForTest,

package/engine/shared.js

@@ -4297,7 +4297,9 @@ const FAILURE_CLASS = {
   INVALID_MANAGED_SPAWN: 'invalid-managed-spawn', // P-7a3b1c92: agents/<id>/managed-spawn.json failed validator (bad schema, broken workdir, executable/env not on allowlist, healthcheck shape wrong). Engine refuses to spawn any spec — agent must fix file; never retryable as-is.
   MANAGED_SPAWN_HEALTHCHECK_FAILED: 'managed-spawn-healthcheck-failed', // P-7a3b1c92: at least one managed-spawn spec was spawned but failed its healthcheck within timeout_s. Engine killed the failing PIDs; siblings stay alive. Dispatch ERROR with the failing spec name + log tail surfaced in the inbox alert.
   INJECTION_FLAGGED: 'injection-flagged', // F5 (W-mpeklod3000we69c): the agent set `securityFlags.injectionAttempt:true` in its completion report after spotting a prompt-injection attempt inside an <UNTRUSTED-INPUT> fence. Engine writes a security inbox note + stamps `_securityFlag` on the WI and treats the dispatch as non-retryable so a human can review the source before the agent re-runs.
-  LIVE_CHECKOUT_DIRTY: 'live-checkout-dirty', // P-a3f9b204 (live-checkout dispatch mode): spawnAgent ran prepareLiveCheckout against project.localPath and `git status --porcelain` reported uncommitted changes. Engine refused to spawn (it never runs `git reset`/`git clean` against the operator tree). Inbox alert lists dirty files; WI is stamped `_pendingReason: 'live_checkout_dirty'`. Non-retryable — operator must commit/stash/discard before re-dispatch.
+  LIVE_CHECKOUT_DIRTY: 'live-checkout-dirty', // P-a3f9b204 (live-checkout dispatch mode): spawnAgent ran prepareLiveCheckout against project.localPath and `git status --porcelain` reported uncommitted changes. Engine refused to spawn (it never runs `git reset`/`git clean` against the operator tree). Inbox alert lists dirty files; WI is stamped `_pendingReason: 'live_checkout_dirty'`. Non-retryable — operator must commit/stash/discard before re-dispatch. RESERVED for confirmed dirty status results only — a thrown helper/git exception is LIVE_CHECKOUT_FAILED, not this (#305).
+  LIVE_CHECKOUT_FAILED: 'live-checkout-failed', // #305 (live-checkout dispatch mode): prepareLiveCheckout THREW before agent spawn (helper guard, ref validation, or a transient `git status`/`rev-parse`/`checkout` failure) — distinct from the confirmed-dirty result (LIVE_CHECKOUT_DIRTY) which the helper returns, not throws. A thrown error is NOT proof the tree is dirty, so it must not be over-classified as dirty. Retryable with bounded backoff (NOT in dispatch.js neverRetry): racy branch-lock handoff, just-finished sibling dispatch, or transient git errors frequently clear on the next attempt; the engine auto-retries up to ENGINE_DEFAULTS.maxRetries before giving up. Genuinely terminal underlying reasons (auth, validation) still short-circuit via the reason-string check in isRetryableFailureReason.
+  LIVE_CHECKOUT_MID_OPERATION: 'live-checkout-mid-operation', // P-a7f3c1d9 (live-checkout dispatch mode): spawnAgent could not switch/create the target branch in project.localPath because the operator tree is mid-operation — an in-progress merge/rebase/cherry-pick/bisect or a detached HEAD. Distinct from LIVE_CHECKOUT_DIRTY (uncommitted changes): here the tree may be clean but the branch op cannot proceed. Engine refuses to spawn (it never runs `git reset`/`git clean`/`git rebase --abort` against the operator tree). Non-retryable — operator must finish or abort the in-progress operation, or checkout a branch, before re-dispatch.
   INVALID_WORKDIR: 'invalid-workdir',     // P-714ef144: dispatch carried a meta.workdir override that failed validation — non-string, absolute path, drive-letter prefix, null byte, ".." segment, or post-resolve containment escape against project.localPath / worktree root. Engine refuses to spawn (the subpath would either be unreachable on disk or point outside the operator's allowed surface). Non-retryable — operator must fix the WI's meta.workdir before re-dispatch. Inbox alert lists the offending value + the resolved-vs-base mismatch.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).
   WORKSPACE_MANIFEST_REPO: 'workspace-manifest-repo-forbidden', // W-mq07avbk000m5543: dispatch routed an agent to a project/repo not present in its workspace_manifest.allowed_repos. Structural — never retryable until the manifest is widened or a different agent is chosen.

package/engine/timeout.js

@@ -748,7 +748,16 @@ function checkTimeouts(config) {
         // mid-multi-turn session. Confirmed 2026-05-11: agents on both Copilot and
         // Claude died at turn boundaries with claude/copilot.exe still actively
         // making API calls, with the sentinel + claude events interleaved in the log.
-        if (processAlive) {
+        //
+        // PID requirement: the alive guard is only reliable when a verifiable OS PID
+        // is present. A PID-less tracked object (e.g. stale in-memory handle after
+        // engine restart, or a Copilot spawn that never resolved its PID) has no
+        // real process behind it — isTrackedProcessAlive falls back to `!!proc &&
+        // !proc.killed` which is unverifiable. Trusting it loops forever (#319).
+        // When the PID is null, the terminal sentinel is the strongest available
+        // signal; complete from output unconditionally.
+        const pidVerifiable = trackedProcessPid(procInfo) !== null;
+        if (processAlive && pidVerifiable) {
           log('warn', `${item.id}: [process-exit] code=${processExitCode} sentinel found in live-output.log but tracked process (pid=${trackedProcessPid(procInfo) || '?'}) is still alive — treating sentinel as stale/premature, skipping completion`);
         } else {
           completeFromOutput(item, liveLogPath, processExitCode, liveLogTail, hasProcess);

package/engine/watchdog.js

@@ -46,6 +46,54 @@ const WATCHDOG_LOG_NAME = 'watchdog-stdio.log';
 // over months. Truncates to half-size on overflow (oldest lines dropped).
 const WATCHDOG_LOG_MAX_BYTES = 2 * 1024 * 1024;
 
+// Post-spawn grace beacon (P-b2d6c14a). Each watchdog tick is a fresh OS-
+// scheduled process with NO in-memory memory of the previous tick, and the
+// engine writes its PID to control.json LATE in boot. So on a slow Windows
+// cold-start the next scheduled tick can read a not-yet-written PID, conclude
+// "dead", and fire a SECOND `minions start` before the first finished binding
+// — re-introducing the documented duplicate-engine/dashboard storm class. The
+// in-process supervisor avoids this with an in-memory POST_SPAWN_GRACE_MS
+// (engine/supervisor.js:76); the watchdog can't keep state across ticks, so it
+// persists a tiny timestamp beacon to disk and stands down inside the window.
+const WATCHDOG_SPAWN_BEACON_NAME = 'watchdog-spawn.json';
+// Floor for the grace window. The effective window is max(2 × interval, floor)
+// so a fast cadence (e.g. --interval=1) still leaves a slow cold-start time to
+// finish, while a long cadence scales the window up with the interval.
+const POST_SPAWN_GRACE_FLOOR_MS = 90 * 1000;
+
+function watchdogSpawnBeaconPath(minionsHome) {
+  return path.join(minionsHome, 'engine', WATCHDOG_SPAWN_BEACON_NAME);
+}
+
+// Effective grace window: max(2 × interval, 90s). intervalMin defaults to the
+// scheduler's default cadence when the caller doesn't thread one through.
+function resolvePostSpawnGraceMs(intervalMin) {
+  const iv = Number.isFinite(intervalMin) && intervalMin > 0 ? intervalMin : DEFAULT_INTERVAL_MIN;
+  return Math.max(2 * iv * 60 * 1000, POST_SPAWN_GRACE_FLOOR_MS);
+}
+
+// Read the last-spawn timestamp (ms epoch) from the beacon. Returns null when
+// the beacon is missing, unreadable, or malformed — any of which means "no
+// recent spawn on record", so recovery proceeds (fail-open).
+function readSpawnBeaconTs(minionsHome) {
+  try {
+    const obj = JSON.parse(fs.readFileSync(watchdogSpawnBeaconPath(minionsHome), 'utf8'));
+    const ts = obj && Number(obj.ts);
+    return Number.isFinite(ts) ? ts : null;
+  } catch { return null; }
+}
+
+// Stamp the beacon just before we spawn. Failure is swallowed (fail-open): a
+// beacon we couldn't write must never block the recovery spawn — at worst we
+// lose the double-fire guard for one window, which is the pre-existing risk.
+function writeSpawnBeacon(minionsHome, nowMs, action) {
+  try {
+    const dir = path.join(minionsHome, 'engine');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(watchdogSpawnBeaconPath(minionsHome), JSON.stringify({ ts: nowMs, action }));
+  } catch { /* fail-open — recovery still proceeds */ }
+}
+
 function logLine(minionsHome, msg) {
   try {
     const dir = path.join(minionsHome, 'engine');
@@ -155,6 +203,24 @@ async function tick(opts) {
 
   const partial = engineAlive || dashUp;
   const action = partial ? 'restart' : 'start';
+
+  // Post-spawn grace: if a previous tick already issued a spawn within the
+  // grace window, stand down instead of double-firing. Each tick is a fresh
+  // stateless process, so the only memory is the on-disk beacon. This closes
+  // the slow-cold-start race where control.json's late PID write lets the next
+  // scheduled tick spawn a second daemon stack.
+  const graceMs = resolvePostSpawnGraceMs(opts.intervalMin);
+  const nowMs = now().getTime();
+  const lastSpawnTs = readSpawnBeaconTs(minionsHome);
+  if (lastSpawnTs != null && nowMs - lastSpawnTs < graceMs) {
+    logLine(
+      minionsHome,
+      `unhealthy but recent spawn ${nowMs - lastSpawnTs}ms ago (< grace ${graceMs}ms) ` +
+      `→ standing down (post-spawn grace, avoiding double-fire)`
+    );
+    return { healthy: false, action: 'skip', reason: 'post-spawn-grace' };
+  }
+
   logLine(
     minionsHome,
     `unhealthy engine=${enginePid || '-'}(${engineAlive ? 'alive' : 'dead'}) ` +
@@ -162,6 +228,11 @@ async function tick(opts) {
   );
 
   try {
+    // Stamp the spawn beacon BEFORE spawning so the next tick (which may fire
+    // before the new stack has bound its port / written control.json) sees the
+    // in-flight spawn and stands down. Write failure is swallowed — recovery
+    // proceeds regardless (fail-open).
+    writeSpawnBeacon(minionsHome, nowMs, action);
     // Detach the child so its lifetime is independent of this tick process.
     // The OS scheduler closes our stdio shortly after exit; we don't want
     // that closure to cascade into the new daemon stack.
@@ -477,6 +548,10 @@ module.exports = {
   MAC_PLIST_LABEL,
   LINUX_UNIT_NAME,
   WATCHDOG_LOG_NAME,
+  WATCHDOG_SPAWN_BEACON_NAME,
+  POST_SPAWN_GRACE_FLOOR_MS,
+  watchdogSpawnBeaconPath,
+  resolvePostSpawnGraceMs,
   buildMacPlist,
   buildLinuxService,
   buildLinuxTimer,

package/engine.js

@@ -2257,10 +2257,15 @@ async function spawnAgent(dispatchItem, config) {
   //   cwd = project.localPath, worktreeRootDir = null, liveMode = true.
   // Instead of creating an engine-managed worktree we run prepareLiveCheckout
   // in-place: it validates a clean tree and then checks out (or creates) the
-  // target branch. On dirty refusal we write an inbox alert, stamp
+  // target branch. On a CONFIRMED dirty refusal (the helper returns
+  // { ok:false, reason:'dirty', dirtyFiles:[…] }) we write an inbox alert, stamp
   // `_pendingReason: 'live_checkout_dirty'` on the WI, complete the dispatch
   // non-retryably with FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, and return — the
-  // engine never runs `git reset`/`git clean` against the operator tree.
+  // engine never runs `git reset`/`git clean` against the operator tree. If the
+  // helper instead THROWS (guard/ref-validation/transient git error), that is
+  // NOT proof of a dirty tree (#305): we complete with the separate
+  // FAILURE_CLASS.LIVE_CHECKOUT_FAILED, which is retryable with bounded backoff
+  // so racy branch-lock handoff or a transient git failure auto-recovers.
   // On success we fall through; the worktree-creation block below is gated
   // on `!liveMode`, so it never runs, and downstream cleanup paths
   // (worktreePool.returnToPool, worktree-gc.gcDispatchWorktreeIfOrphan) are
@@ -2284,14 +2289,22 @@ async function spawnAgent(dispatchItem, config) {
         log: (msg, lvl) => log(lvl || 'info', msg),
       });
     } catch (liveErr) {
-      log('error', `spawnAgent: live-checkout helper failed for ${id}: ${liveErr.message}`);
+      // #305: A THROWN helper/git error is NOT proof the worktree is dirty.
+      // Classify it as LIVE_CHECKOUT_FAILED (transient/pre-spawn) and let the
+      // dispatch retry path decide retryability via isRetryableFailureReason —
+      // racy branch-lock handoff, a just-finished sibling dispatch, or a
+      // transient `git status`/`rev-parse`/`checkout` failure usually clears on
+      // the next attempt (bounded by ENGINE_DEFAULTS.maxRetries). Do NOT stamp
+      // _pendingReason: 'live_checkout_dirty' or write a dirty-files alert here —
+      // those belong to the confirmed-dirty result path below.
+      log('error', `spawnAgent: live-checkout helper threw for ${id}: ${liveErr.message}`);
       _cleanupPromptFiles();
       completeDispatch(
         id,
         DISPATCH_RESULT.ERROR,
         `live-checkout failed: ${liveErr.message}`.slice(0, 800),
-        'Live-checkout helper threw before agent spawn; non-retryable until the underlying git state or invocation is fixed.',
-        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, agentRetryable: false },
+        'Live-checkout helper threw before agent spawn (not proof of a dirty tree). Auto-retried with bounded backoff; transient git/branch-lock state usually clears on the next attempt.',
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_FAILED },
       );
       cleanupTempAgent(agentId);
       return null;
@@ -2342,7 +2355,96 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // P-c5a1f3b8: mid-operation / detached-HEAD refusal. The tree is clean
+    // (the dirty branch above already bailed) but the branch op cannot proceed
+    // because the operator is mid-merge/rebase/cherry-pick/revert or sitting on
+    // a detached HEAD. Distinct operator condition from `dirty` → distinct
+    // FAILURE_CLASS (LIVE_CHECKOUT_MID_OPERATION) and distinct recovery
+    // guidance. The engine NEVER runs git reset/clean/stash or aborts the
+    // operator's in-progress operation — it refuses and tells the operator how
+    // to recover with their own commands.
+    if (_liveResult && _liveResult.ok === false
+        && (_liveResult.reason === 'mid-operation' || _liveResult.reason === 'detached-head')) {
+      const _isMidOp = _liveResult.reason === 'mid-operation';
+      const _op = _isMidOp ? (_liveResult.op || 'operation') : null;
+      const _sha = _isMidOp ? null : (_liveResult.sha || '(unknown)');
+      const _alertBody = [
+        _isMidOp
+          ? '# Live-checkout blocked: in-progress git operation'
+          : '# Live-checkout blocked: detached HEAD',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**Branch:** ${branchName}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        _isMidOp
+          ? `The engine refused to spawn the agent because \`${cwd}\` has an in-progress **${_op}**. Live-checkout mode runs in your project directly — the engine never \`git reset\`, \`git clean\`, or aborts an operation in your tree.`
+          : `The engine refused to spawn the agent because \`${cwd}\` is in a **detached-HEAD** state (HEAD at \`${_sha}\`). Branching off a detached HEAD would strand your anonymous commits, so the engine refuses rather than risk losing work.`,
+        '',
+        '## Recovery',
+        '',
+        _isMidOp
+          ? `Finish or abort the in-progress ${_op} with your own git commands (e.g. \`git ${_op} --continue\` or \`git ${_op} --abort\`), or checkout a branch, then re-dispatch the work item.`
+          : 'Checkout a branch (e.g. `git checkout <branch>`) so HEAD points at a named ref, then re-dispatch the work item. If you have commits on the detached HEAD you want to keep, create a branch first (`git branch <name>`).',
+      ].join('\n');
+      try { writeInboxAlert(`live-checkout-blocked-${_wiIdForAlert}`, _alertBody); }
+      catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
+      const _pendingReason = _isMidOp ? 'live_checkout_mid_operation' : 'live_checkout_detached_head';
+      try {
+        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (_wiPath && dispatchItem.meta?.item?.id) {
+          mutateJsonFileLocked(_wiPath, (data) => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
+            if (wi) wi._pendingReason = _pendingReason;
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      const _shortMsg = _isMidOp
+        ? `live-checkout blocked: in-progress ${_op} in ${cwd}`
+        : `live-checkout blocked: detached HEAD (${_sha}) in ${cwd}`;
+      const _guidance = _isMidOp
+        ? `Live-checkout mode cannot switch/create a branch while a ${_op} is in progress; the engine never aborts operator operations. Finish/abort the ${_op} or checkout a branch, then re-dispatch.`
+        : 'Live-checkout mode cannot branch off a detached HEAD without risking operator commits; the engine never moves HEAD for you. Checkout a branch, then re-dispatch.';
+      log('error', `spawnAgent: ${_shortMsg}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        _shortMsg.slice(0, 800),
+        _guidance,
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
     log('info', `live-checkout: ${_liveResult.created ? 'created' : 'switched to'} branch ${branchName} in ${cwd} (in-place; no worktree)`);
+    // P-c5a1f3b8: persist the operator's original ref on the dispatch record so
+    // the dispatch-end auto-restore (P-d9e6b2c4) can return the tree to where the
+    // operator started — even after an engine restart + re-attach, where the
+    // spawnAgent closure is gone and only the persisted dispatch record survives
+    // (same pattern as resolveHarnessPropagated at engine/lifecycle.js:3576).
+    if (_liveResult.originalRef) {
+      dispatchItem.originalRef = _liveResult.originalRef;
+      dispatchItem.originalRefType = _liveResult.originalRefType || 'branch';
+      try {
+        mutateDispatch((dispatch) => {
+          for (const queue of ['pending', 'active', 'completed']) {
+            const arr = Array.isArray(dispatch?.[queue]) ? dispatch[queue] : null;
+            if (!arr) continue;
+            const found = arr.find(d => d && d.id === id);
+            if (found) {
+              found.originalRef = _liveResult.originalRef;
+              found.originalRefType = _liveResult.originalRefType || 'branch';
+            }
+          }
+          return dispatch;
+        });
+      } catch (e) { log('warn', `live-checkout: failed to persist originalRef for ${id}: ${e.message}`); }
+    }
   }
 
   if (branchName && !liveMode) {
@@ -3814,6 +3916,15 @@ 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
+    // 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
+    // for live mode (regression-guarded in
+    // test/unit/spawn-agent-live-mode-wiring.test.js). A null cwd would push from
+    // the engine's own process dir and open the PR off the wrong tree.
     // `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
@@ -4946,6 +5057,43 @@ async function spawnAgent(dispatchItem, config) {
       }
     }
 
+    // ── P-d9e6b2c4 — live-mode dispatch-end auto-restore + terminal-failure
+    //    notify. Runs on EVERY terminal result for a live-mode dispatch: the
+    //    agent ran in-place in the operator's checkout, so switch the tree back
+    //    to the ref it was on before (see engine/live-checkout.js#
+    //    restoreLiveCheckoutAtDispatchEnd). The worktree-GC block above no-ops
+    //    in live mode (worktreePath===null); this is its live-mode counterpart.
+    //    originalRef was captured by prepareLiveCheckout and persisted on the
+    //    dispatch record at branch-resolution time (P-c5a1f3b8); the in-memory
+    //    closure copy is authoritative here. The engine-restart reattach path
+    //    fires the same helper from the persisted record in engine/cli.js. The
+    //    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) {
+      try {
+        const _liveRestore = require('./engine/live-checkout');
+        await _liveRestore.restoreLiveCheckoutAtDispatchEnd({
+          localPath: cwd,
+          branchName,
+          originalRef: dispatchItem.originalRef || '',
+          originalRefType: dispatchItem.originalRefType || 'branch',
+          dispatchId: id,
+          projectName: project?.name,
+          isTerminalFailure: effectiveResult !== DISPATCH_RESULT.SUCCESS,
+          resultLabel: errorReason || effectiveResult,
+          gitOpts: _gitOpts,
+          log,
+          writeInboxAlert,
+        });
+      } catch (restoreErr) {
+        // restoreLiveCheckoutAtDispatchEnd swallows its own errors; this guard
+        // is belt-and-suspenders so a require() hiccup can never break the
+        // dispatch-completion path that follows.
+        log('warn', `live-checkout: dispatch-end restore wiring threw for ${id}: ${restoreErr.message}`);
+      }
+    }
+
     completeDispatch(id, effectiveResult, errorReason, resultSummary, completeOpts);
 
     // W-mpbpexrg00110661 — surface managed-spawn partial-healthcheck failures

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2238",
+  "version": "0.1.2239",
   "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"