@yemi33/minions 0.1.2237 → 0.1.2239

package/engine/consolidation.js

@@ -65,6 +65,26 @@ function _capNotesPreservingOverflow(newContent) {
   return kept;
 }
 
+// Read notes.md for an in-lock append, distinguishing "absent" from
+// "present but unreadable". The consolidation write paths run inside the
+// NOTES_PATH lock and append `current + entry`. getNotes()/safeRead swallow
+// ALL errors and return '' (shared.js:691-692), so a transient EBUSY/EACCES/
+// lock on a NON-EMPTY notes.md would make `'' + entry` clobber the entire
+// file — a confirmed total-loss vector for accumulated team notes. The lock
+// guarantees exclusion, not a correct read of its own target. safeReadOrNull
+// (shared.js:700) lets us tell the two states apart:
+//   - string (incl. '')        → readable; use it (verbatim empty file is fine)
+//   - null + file ABSENT       → first-ever consolidation; treat as ''
+//   - null + file PRESENT      → unreadable; return null so the caller ABORTS
+//                                the cycle (leave inbox notes to retry next tick)
+function _readNotesForAppendOrNull() {
+  const body = shared.safeReadOrNull(NOTES_PATH);
+  if (body !== null) return body;
+  // null: a genuinely missing file is the benign first-run case ('');
+  // a file that EXISTS but failed to read must abort to avoid clobbering it.
+  return fs.existsSync(NOTES_PATH) ? null : '';
+}
+
 // Per-agent memory files live under knowledge/agents/<agent>.md and are
 // injected into individual agent prompts (in addition to the broadcast
 // notes.md). See knowledge/agents/README.md for the convention.
@@ -920,7 +940,7 @@ function consolidateWithLLM(items, existingNotes, files, config) {
     }, 10000);
   }, 180000);
 
-  llmCall.then((result) => {
+  llmCall.then(async (result) => {
     if (_cleared) return;
     clearTimeout(timeoutHandle);
     trackEngineUsage('consolidation', result.usage);
@@ -947,15 +967,31 @@ function consolidateWithLLM(items, existingNotes, files, config) {
 
       const entry = '\n\n---\n\n' + digest;
       // Wrap read-modify-write in file lock to prevent race with concurrent consolidation or manual edits
-      shared.withFileLock(NOTES_PATH + '.lock', () => {
-        const current = getNotes() || '';
+      const wrote = shared.withFileLock(NOTES_PATH + '.lock', () => {
+        const current = _readNotesForAppendOrNull();
+        if (current === null) {
+          // notes.md exists but is unreadable (transient lock/EBUSY/EACCES).
+          // ABORT rather than rebuild the file from '' + entry (full-file
+          // clobber). Leave inbox notes in place to retry next cycle.
+          log('warn', 'LLM consolidation aborted: notes.md present but unreadable — preserving existing content, retrying next cycle');
+          return false;
+        }
         // DATA-LOSS GUARD: cap size but archive the overflow instead of
         // silently discarding it (see _capNotesPreservingOverflow).
         const newContent = _capNotesPreservingOverflow(current + entry);
         safeWrite(NOTES_PATH, newContent);
+        return true;
       });
-      classifyToKnowledgeBase(items, config);
-      archiveInboxFiles(files);
+      if (!wrote) {
+        // Unreadable notes.md: do NOT classify to KB or archive inbox — the
+        // notes survive on disk for the next tick to retry.
+        log('info', `LLM consolidation deferred: notes.md unreadable, ${files.length} notes left in inbox for retry`);
+        return;
+      }
+      // P-8c2b471f: archive only after per-agent memory routing resolves;
+      // skip notes whose eligible memory write failed (retried next pass).
+      const deferred = await classifyToKnowledgeBase(items, config);
+      archiveInboxFiles(files.filter(f => !deferred.has(f)));
       log('info', `LLM consolidation complete: ${files.length} notes processed`);
     } else {
       _fallback(`LLM consolidation failed (code=${result.code}) — falling back to regex`, result.stderr ? { message: result.stderr.slice(0, 500) } : null);
@@ -1068,20 +1104,39 @@ function consolidateWithRegex(items, files, config) {
   if (dupCount > 0) entry += `_Deduplication: ${dupCount} duplicate(s) removed._\n`;
 
   // Wrap read-modify-write in file lock to prevent race with concurrent consolidation or manual edits
-  shared.withFileLock(NOTES_PATH + '.lock', () => {
-    const current = getNotes() || '';
+  const wrote = shared.withFileLock(NOTES_PATH + '.lock', () => {
+    const current = _readNotesForAppendOrNull();
+    if (current === null) {
+      // notes.md exists but is unreadable (transient lock/EBUSY/EACCES).
+      // ABORT rather than rebuild the file from '' + entry (full-file
+      // clobber). Leave inbox notes in place to retry next cycle.
+      log('warn', 'Regex consolidation aborted: notes.md present but unreadable \u2014 preserving existing content, retrying next cycle');
+      return false;
+    }
     // DATA-LOSS GUARD: cap size but archive the overflow (see LLM path).
     const newContent = _capNotesPreservingOverflow(current + entry);
     safeWrite(NOTES_PATH, newContent);
+    return true;
   });
-  classifyToKnowledgeBase(items, config);
-  archiveInboxFiles(files);
+  if (!wrote) {
+    // Unreadable notes.md: do NOT classify to KB or archive inbox — the
+    // notes survive on disk for the next tick to retry.
+    log('info', `Regex consolidation deferred: notes.md unreadable, ${files.length} notes left in inbox for retry`);
+    return;
+  }
+  // P-8c2b471f: keep consolidateWithRegex synchronous — the notes.md lock
+  // error above must still surface as a sync throw before any archiving.
+  // Gate inbox archiving on per-agent memory routing via the returned promise
+  // so a transient memory-append failure defers (not loses) the inbox note.
+  Promise.resolve(classifyToKnowledgeBase(items, config))
+    .then((deferred) => archiveInboxFiles(files.filter(f => !deferred.has(f))))
+    .catch((err) => log('warn', `agent-memory routing/archive failed: ${err?.message || err}`));
   log('info', `Regex fallback: consolidated ${files.length} notes \u2192 ${deduped.length} insights into notes.md`);
 }
 
 // ─── Knowledge Base Classification ───────────────────────────────────────────
 
-function classifyToKnowledgeBase(items, config) {
+async function classifyToKnowledgeBase(items, config) {
 
   if (!fs.existsSync(KNOWLEDGE_DIR)) fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
 
@@ -1098,6 +1153,9 @@ function classifyToKnowledgeBase(items, config) {
   }
 
   let classified = 0;
+  // P-8c2b471f: per-item per-agent-memory routing outcomes, awaited after the
+  // loop so inbox archiving can be gated on the memory write (see end of fn).
+  const memoryRoutes = [];
   for (const item of items) {
     const content = item.content || '';
     const rawCategory = classifyInboxItem(item.name, content);
@@ -1128,30 +1186,52 @@ function classifyToKnowledgeBase(items, config) {
     // Appends the inbox content to knowledge/agents/<agent>.md when the
     // author is a configured team member (skips temp-* and unknown agents).
     // When the new entry has contradiction signals, the reconcile pass calls
-    // Haiku to identify and rewrite stale facts before the append. Reconcile
-    // is fire-and-forget — any failure or hang falls back to plain append
-    // inside reconcileAndAppendToAgentMemory; the consolidation pipeline is
-    // never blocked on the LLM. (W-mpbi7qus0011bf77)
+    // Haiku to identify and rewrite stale facts before the append. Any LLM
+    // failure or hang falls back to plain append inside
+    // reconcileAndAppendToAgentMemory; the consolidation pipeline is never
+    // blocked on the LLM. (W-mpbi7qus0011bf77)
     //
     // After every successful append, chain the optional sliding-window
-    // summary pass (W-mq07b8do000nc86a) — also fire-and-forget, disabled
+    // summary pass (W-mq07b8do000nc86a) — fire-and-forget, disabled
     // by default (engine.agentMemorySummaryEnabled), and a strict no-op
     // when the entry-count and age triggers don't fire. The chain runs
     // for ALL writes (reconcile-edit AND plain-append paths), not just
     // the contradiction-signal fast path, so steady-state +1/-1 pruning
-    // can still build up enough evictions to trigger a fold.
+    // can still build up enough evictions to trigger a fold. The summary
+    // never gates archiving.
+    //
+    // P-8c2b471f: the memory-write outcome is tracked (not fire-and-forget)
+    // so the loop's caller can archive the inbox note only AFTER the per-agent
+    // append has completed. An ELIGIBLE route (known team agent, non-empty
+    // body) whose write transiently fails is recorded so the note is deferred
+    // — left in the inbox for the next consolidation pass — rather than
+    // archived-and-forgotten. Ineligible routes (temp-*/unknown author, empty
+    // body) legitimately skip the memory copy and stay archivable.
+    const routeAgent = extractInboxAgent(item);
+    const routeEligible = !!routeAgent
+      && !routeAgent.startsWith('temp-')
+      && !!knownAgents && knownAgents.has(routeAgent)
+      && String(item?.content || '').trim().length > 0;
     try {
-      const agentForSummary = extractInboxAgent(item);
       const p = reconcileAndAppendToAgentMemory(item, knownAgents, config);
-      if (p && typeof p.then === 'function') {
-        p.then((ok) => {
-          if (!ok || !agentForSummary) return;
-          return maybeSummarizeAgentMemory(agentForSummary, config);
-        }).catch(err => log('warn', `agent-memory reconcile/append failed: ${err?.message || err}`));
-      }
+      const tracked = Promise.resolve(p).then((ok) => {
+        if (ok && routeAgent) {
+          // Sliding-window summary follow-up (unchanged trigger) — kept
+          // fire-and-forget so it never gates archiving.
+          Promise.resolve(maybeSummarizeAgentMemory(routeAgent, config))
+            .catch(err => log('warn', `agent-memory summary failed: ${err?.message || err}`));
+        }
+        return ok;
+      }).catch((err) => {
+        log('warn', `agent-memory reconcile/append failed: ${err?.message || err}`);
+        return false;
+      });
+      memoryRoutes.push({ name: item.name, eligible: routeEligible, tracked });
     } catch (err) {
       log('warn', `agent-memory reconcile/append threw: ${err?.message || err}`);
-      appendToAgentMemory(item, knownAgents, config);
+      // Synchronous plain-append fallback path (preserved).
+      const ok = appendToAgentMemory(item, knownAgents, config);
+      memoryRoutes.push({ name: item.name, eligible: routeEligible, tracked: Promise.resolve(ok) });
     }
   }
 
@@ -1168,6 +1248,21 @@ function classifyToKnowledgeBase(items, config) {
     }
     shared.mutateKbCheckpoint(() => ({ count, updatedAt: ts() }));
   } catch (err) { log('warn', `KB checkpoint: ${err.message}`); }
+
+  // P-8c2b471f: gate inbox archiving on per-agent memory routing completing.
+  // Await each route's write outcome; defer archiving any ELIGIBLE note whose
+  // memory append failed (transient lock/disk error) so a later consolidation
+  // pass retries it. The broadcast notes.md + KB classification copies already
+  // landed synchronously above — this only governs the per-agent-memory
+  // durability of the archive step. Returns the set of inbox filenames the
+  // caller must NOT archive this pass.
+  const deferredArchive = new Set();
+  for (const route of memoryRoutes) {
+    let ok = false;
+    try { ok = await route.tracked; } catch { ok = false; }
+    if (route.eligible && !ok) deferredArchive.add(route.name);
+  }
+  return deferredArchive;
 }
 
 function archiveInboxFiles(files) {

package/engine/dispatch-store.js

@@ -17,6 +17,18 @@
 
 const SECTIONS = ['pending', 'active', 'completed', 'review'];
 
+// First-touch guard (P-5f0e8c27). Tracks whether a dispatch mutation has
+// written SQL in THIS process. Once SQL has been written, an empty read
+// reflects a genuine prune-to-zero — NOT a fresh install — so we must not
+// resurrect a stale dispatch.json (e.g. a crash between the SQL COMMIT and
+// the post-commit mirror write leaves dispatch.json holding the pre-prune
+// rows). This mirrors the `_resyncIfJsonDiverged` first-touch discipline the
+// work-items / pull-requests / metrics / watches stores already use: once SQL
+// is the established source of truth this process, JSON never overrides it.
+// Reset only by process restart (module reload); test isolation re-requires
+// the module via withFreshDb's cache-bust, so each test starts fresh.
+let _sqlWrittenThisProcess = false;
+
 function _emptySectioned() {
   return { pending: [], active: [], completed: [], review: [] };
 }
@@ -48,15 +60,23 @@ function readDispatchSectioned() {
     ORDER BY status, created_at
   `).all();
 
-  if (rows.length === 0) {
-    // SQL has no live dispatches. Two scenarios:
-    //   (a) Production fresh install (or all pruned) — JSON file is empty/missing,
-    //       fallback returns the same empty sectioned object. No harm.
+  if (rows.length === 0 && !_sqlWrittenThisProcess) {
+    // SQL has no live dispatches AND no mutation has written SQL this process.
+    // Only then is the JSON file a trustworthy fallback. Two scenarios:
+    //   (a) Production fresh install — JSON file is empty/missing, fallback
+    //       returns the same empty sectioned object. No harm.
     //   (b) Test that wrote dispatch.json directly (legacy test helpers in
     //       timeout-behavioral / orphan-* / etc. — they bypass the proper
     //       mutateDispatch API and seed via fs.writeFileSync). Picking up
     //       the JSON keeps those tests working through the transition without
     //       touching every helper. Phase 1.5 migrates them to the proper API.
+    //
+    // The `!_sqlWrittenThisProcess` gate is the first-touch guard: once a
+    // mutation has written SQL this process (e.g. the engine pruned the last
+    // dispatch to zero), an empty SQL read is the real state. Adopting a stale
+    // non-empty dispatch.json here would resurrect pruned records and could
+    // trigger a duplicate dispatch before the next mutation self-heals the
+    // mirror — the exact crash-window bug this guard closes.
     const fallback = _readDispatchJsonFallback();
     const hasContent = (
       (fallback.pending && fallback.pending.length > 0) ||
@@ -250,6 +270,9 @@ function applyDispatchMutation(mutator) {
     }
     const diff = _computeDispatchDiff(beforeSnapshot, after);
     const wrote = _applyDispatchDiff(db, diff);
+    // First-touch guard: record that SQL was written this process so a later
+    // empty read won't resurrect a stale dispatch.json (see readDispatchSectioned).
+    if (wrote) _sqlWrittenThisProcess = true;
     return { wrote, result: after };
   });
 }

package/engine/dispatch.js

@@ -518,6 +518,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED, // W-mpbhxg3b000u8411 — healthcheck timed out; agent must fix the spec or the service it spawned
       FAILURE_CLASS.INJECTION_FLAGGED, // F5 (W-mpeklod3000we69c) — agent spotted a prompt-injection attempt in spliced untrusted content; a human must review the source before re-dispatch
       FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, // P-a3f9b204 — live-checkout refused to spawn because operator localPath is dirty; mechanical retry won't fix it (operator must commit/stash/discard)
+      FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION, // P-a7f3c1d9 — live-checkout refused to spawn because the operator tree is mid-operation (in-progress merge/rebase/cherry-pick/bisect or detached HEAD); mechanical retry won't fix it (operator must finish/abort the op or checkout a branch)
       FAILURE_CLASS.OUTPUT_TRUNCATED, // P-8e4c2a17 — agent stdout exceeded the hard capture cap before the terminal result event; mechanical retry just reproduces the overflow (agent must reduce output volume or the task must be split)
     ]);
     if (neverRetry.has(failureClass)) return false;

package/engine/github.js

@@ -154,7 +154,10 @@ function _isNonActionableComment(c, config = {}) {
   const ignoredAuthors = new Set((config.engine?.ignoredCommentAuthors || []).map(a => String(a).toLowerCase()));
   const login = String(c?.user?.login || '').toLowerCase();
   if (ignoredAuthors.has(login)) return true;
-  if (_isGitHubBotComment(c)) return true;
+  // W-mqr41te300026723: removed blanket _isGitHubBotComment author-type drop.
+  // Bot comments are now filtered by CONTENT (isPreviewStatusBody below), not
+  // author type — symmetric with ADO's pollPrHumanComments which has no
+  // user.type==='bot' equivalent and relies solely on body-content + marker gates.
   if (_isAgentComment(c)) return true;
   // P-f23classifier (F2): body-only preview/CI-report check is now host-
   // agnostic. The legacy `_isCiReportCommentBody` body match (Coverage /

package/engine/live-checkout.js

@@ -3,14 +3,37 @@
  *
  * Pure helper for the live-checkout dispatch mode (plan-w-mq5rmtt9000a42f9-2026-06-08).
  *
- * `prepareLiveCheckout({ localPath, branchName, mainRef, gitOpts, dispatchId, wiId, log, _git })`
+ * `prepareLiveCheckout({ localPath, branchName, mainRef, gitOpts, dispatchId, wiId, log, _git, _exists })`
  *
  * Lifecycle (called by spawnAgent in engine.js when resolveSpawnPaths returns liveMode:true):
  *   1. `git status --porcelain` from localPath. Non-empty output → bail with
  *      { ok:false, reason:'dirty', dirtyFiles:[…] } so spawnAgent can fail the
  *      dispatch non-retryably and write an inbox alert. NO mutating git calls
  *      after this point if dirty.
- *   2. Branch resolution (NO `git fetch` — issue #226):
+ *   2. MID-OPERATION / DETACHED-HEAD PREFLIGHT (P-b2e8d4a6 — runs BETWEEN the
+ *      dirty check and branch resolution, before any checkout):
+ *        a. Resolve the git dir robustly via `git rev-parse --git-dir` (NOT by
+ *           assuming localPath/.git) so submodule / gitdir-file / repo-managed
+ *           trees — the very setups that motivate live mode — are covered.
+ *        b. Probe sentinel paths under the resolved git dir via the injectable
+ *           `_exists` seam (defaults to fs.existsSync): MERGE_HEAD → merge,
+ *           rebase-merge/ & rebase-apply/ → rebase, CHERRY_PICK_HEAD →
+ *           cherry-pick, REVERT_HEAD → revert. First hit → bail with
+ *           { ok:false, reason:'mid-operation', op, details } so spawnAgent
+ *           refuses non-retryably rather than committing into a half-finished
+ *           operation in the operator's tree.
+ *        c. Detached HEAD via `git symbolic-ref -q HEAD` non-zero exit → bail
+ *           with { ok:false, reason:'detached-head', sha } (sha from
+ *           `git rev-parse HEAD`). Branching off a detached HEAD would strand
+ *           the operator's anonymous commits.
+ *   3. ORIGINAL-REF CAPTURE (P-b2e8d4a6 — before any checkout): capture the
+ *      operator's starting ref so the dispatch-end auto-restore (P-c5a1f3b8 /
+ *      P-d9e6b2c4 engine wiring) can put the tree back. `git symbolic-ref
+ *      --short HEAD` → { originalRef:<branch>, originalRefType:'branch' };
+ *      falls back to `git rev-parse HEAD` → { originalRef:<sha>,
+ *      originalRefType:'detached' } when symbolic-ref fails. These additive
+ *      fields ride on the success object.
+ *   4. Branch resolution (NO `git fetch` — issue #226):
  *        a. `git rev-parse --verify <branchName>` succeeds → branch exists
  *           locally → `git checkout <branchName>` (NO --force, NO auto-pull,
  *           NO fast-forward, NO reset). The operator owns the checkout
@@ -23,7 +46,13 @@
  *           partial clones (Scalar/GVFS-managed ADO repos), which fails in
  *           headless mode because the GVFS cache server receives no auth and
  *           credential.helper is disabled. See issue #226.
- *   3. Returns { ok:true, branch, created:boolean }.
+ *   5. Returns { ok:true, branch, created:boolean, originalRef, originalRefType }.
+ *
+ * RETURN SHAPES:
+ *   { ok:true,  branch, created, originalRef, originalRefType:'branch'|'detached' }
+ *   { ok:false, reason:'dirty',         dirtyFiles:[…] }
+ *   { ok:false, reason:'mid-operation', op:'merge'|'rebase'|'cherry-pick'|'revert', details }
+ *   { ok:false, reason:'detached-head', sha }
  *
  * NOTE: `mainRef` is still accepted (and validated) for caller-contract
  * stability, but it is NOT used to seed the new branch in live mode — HEAD
@@ -44,13 +73,17 @@
  * crafted branch name like "--evil-flag" is rejected before reaching git.
  *
  * Tests inject a mock runner via the private `_git` option (signature
- * `(args:string[], opts:{cwd, gitExtraArgs?:string[]}) => Promise<string>`).
- * Production callers omit `_git` and the helper falls back to
- * `require('./shared').shellSafeGit`.
+ * `(args:string[], opts:{cwd, gitExtraArgs?:string[]}) => Promise<string>`)
+ * and a mock sentinel-existence probe via the private `_exists` option
+ * (signature `(absPath:string) => boolean`, defaulting to fs.existsSync).
+ * Production callers omit both and the helper falls back to
+ * `require('./shared').shellSafeGit` and `fs.existsSync` respectively.
  */
 
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const shared = require('./shared');
 
 async function prepareLiveCheckout(opts = {}) {
@@ -63,6 +96,7 @@ async function prepareLiveCheckout(opts = {}) {
     wiId,       // accepted for caller bookkeeping; not used by the helper
     log,
     _git,       // private injection for testing — defaults to shared.shellSafeGit
+    _exists,    // private injection for testing — defaults to fs.existsSync
   } = opts;
 
   // ── Required-arg guards. Throw rather than return {ok:false} so a
@@ -88,6 +122,7 @@ async function prepareLiveCheckout(opts = {}) {
   catch (e) { throw new Error('prepareLiveCheckout: invalid mainRef — ' + e.message); }
 
   const git = (typeof _git === 'function') ? _git : shared.shellSafeGit;
+  const exists = (typeof _exists === 'function') ? _exists : fs.existsSync;
   const baseOpts = { cwd: localPath, ...(gitOpts || {}) };
 
   // ── Step 1: git status --porcelain. Bail early on dirty tree. ─────────
@@ -106,7 +141,80 @@ async function prepareLiveCheckout(opts = {}) {
     return { ok: false, reason: 'dirty', dirtyFiles };
   }
 
-  // ── Step 2: branch resolution + checkout. ─────────────────────────────
+  // ── Step 2: mid-operation / detached-HEAD preflight (P-b2e8d4a6). ──────
+  // Runs AFTER the dirty bail and BEFORE branch resolution — never mutates.
+  // Resolve the git dir via rev-parse (NOT localPath/.git) so submodule /
+  // gitdir-file / repo-managed trees resolve correctly. On failure fall back
+  // to <localPath>/.git so the sentinel probe still has a reasonable target.
+  let gitDir = path.join(localPath, '.git');
+  try {
+    const gitDirRaw = await git(['rev-parse', '--git-dir'], baseOpts);
+    const gitDirStr = (typeof gitDirRaw === 'string' ? gitDirRaw : '').trim();
+    if (gitDirStr) {
+      gitDir = path.isAbsolute(gitDirStr) ? gitDirStr : path.join(localPath, gitDirStr);
+    }
+  } catch {
+    // keep the <localPath>/.git fallback
+  }
+
+  // Probe sentinel paths under the resolved git dir. First hit wins; map each
+  // to its in-progress operation. rebase-merge/ (interactive/merge rebase) and
+  // rebase-apply/ (am-based rebase) both mean a rebase is underway.
+  const MID_OP_SENTINELS = [
+    { name: 'MERGE_HEAD', op: 'merge' },
+    { name: 'rebase-merge', op: 'rebase' },
+    { name: 'rebase-apply', op: 'rebase' },
+    { name: 'CHERRY_PICK_HEAD', op: 'cherry-pick' },
+    { name: 'REVERT_HEAD', op: 'revert' },
+  ];
+  for (const sentinel of MID_OP_SENTINELS) {
+    const sentinelPath = path.join(gitDir, sentinel.name);
+    if (exists(sentinelPath)) {
+      return { ok: false, reason: 'mid-operation', op: sentinel.op, details: sentinelPath };
+    }
+  }
+
+  // Detached HEAD: `git symbolic-ref -q HEAD` exits non-zero (→ shellSafeGit
+  // rejects) when HEAD does not point at a branch. Branching off a detached
+  // HEAD would strand the operator's anonymous commits, so refuse.
+  let detached = false;
+  try {
+    await git(['symbolic-ref', '-q', 'HEAD'], baseOpts);
+  } catch {
+    detached = true;
+  }
+  if (detached) {
+    let sha = '';
+    try {
+      const shaRaw = await git(['rev-parse', 'HEAD'], baseOpts);
+      sha = (typeof shaRaw === 'string' ? shaRaw : '').trim();
+    } catch {
+      // best-effort sha; leave empty if even rev-parse fails
+    }
+    return { ok: false, reason: 'detached-head', sha };
+  }
+
+  // ── Step 3: original-ref capture (P-b2e8d4a6). ────────────────────────
+  // Capture the operator's starting ref BEFORE any checkout so the
+  // dispatch-end auto-restore can put the tree back. Prefer the symbolic
+  // branch name; fall back to the raw HEAD sha when symbolic-ref fails.
+  let originalRef = '';
+  let originalRefType = 'branch';
+  try {
+    const refRaw = await git(['symbolic-ref', '--short', 'HEAD'], baseOpts);
+    originalRef = (typeof refRaw === 'string' ? refRaw : '').trim();
+    originalRefType = 'branch';
+  } catch {
+    originalRefType = 'detached';
+    try {
+      const refRaw = await git(['rev-parse', 'HEAD'], baseOpts);
+      originalRef = (typeof refRaw === 'string' ? refRaw : '').trim();
+    } catch {
+      originalRef = '';
+    }
+  }
+
+  // ── Step 4: branch resolution + checkout. ─────────────────────────────
   // NO `git fetch` (issue #226): the operator's existing HEAD is the
   // baseline in live mode, and a fetch against a Scalar/GVFS partial clone
   // pulls blobs through an auth-less cache server in headless mode (fails).
@@ -121,7 +229,7 @@ async function prepareLiveCheckout(opts = {}) {
   if (branchExists) {
     // Plain checkout — NO --force, NO -B, NO pull. Operator owns local commits.
     await git(['checkout', branchName], baseOpts);
-    return { ok: true, branch: branchName, created: false };
+    return { ok: true, branch: branchName, created: false, originalRef, originalRefType };
   }
 
   // New branch — create from the current HEAD (issue #226). NOT
@@ -129,7 +237,181 @@ async function prepareLiveCheckout(opts = {}) {
   // seeding from a remote ref forces auth-less GVFS blob fetches that fail
   // on partial clones in headless mode.
   await git(['checkout', '-b', branchName], baseOpts);
-  return { ok: true, branch: branchName, created: true };
+  return { ok: true, branch: branchName, created: true, originalRef, originalRefType };
+}
+
+/**
+ * restoreLiveCheckoutAtDispatchEnd — P-d9e6b2c4
+ *
+ * Dispatch-end counterpart to prepareLiveCheckout. Runs from spawnAgent's
+ * onAgentClose (engine.js) on EVERY terminal result AND from the engine-restart
+ * orphan/reattach completion path (engine/cli.js), so the operator's working
+ * tree is switched back to the ref it was on before the live-mode agent ran.
+ *
+ * Behaviour (locked by human steer steer-bc5861ff95, 2026-06-19):
+ *   (A) TERMINAL-FAILURE NOTIFY: when the dispatch ended in a non-success
+ *       terminal state (`isTerminalFailure`), write a deduped inbox alert
+ *       `live-checkout-failed-<dispatchId>` so the operator knows a live-mode
+ *       run failed inside their checkout (where side effects are visible).
+ *   (B) AUTO-RESTORE (best-effort, never throws, NEVER --force):
+ *         • No-op when there is nothing to restore — no captured originalRef,
+ *           or the agent branch IS the original ref, or HEAD already sits on
+ *           the original ref (branch name OR raw sha, so the detached-HEAD
+ *           restore is recognized too).
+ *         • Otherwise a PLAIN `git checkout <originalRef>` (no --force, no
+ *           reset, no clean, no stash). git refuses if uncommitted agent work
+ *           would be overwritten; that refusal is HONORED — the tree is left
+ *           exactly as the agent left it and a `live-checkout-branch-<dispatchId>`
+ *           notify alert is written so the operator can resolve it manually.
+ *         • Any unexpected error is swallowed and logged; restore is strictly
+ *           best-effort and must NEVER alter the dispatch result.
+ *
+ * SIDE-EFFECTING (unlike prepareLiveCheckout) but every effect routes through
+ * an injected seam: git via `_git` (defaults to shared.shellSafeGit) and the
+ * inbox write via the required `writeInboxAlert(slug, body)` callback. This
+ * keeps the engine's dispatch module the owner of inbox I/O while letting unit
+ * tests capture every git argv and alert with zero filesystem / process touch.
+ *
+ * @param {object} opts
+ * @param {string} opts.localPath          operator checkout root (git cwd)
+ * @param {string} opts.branchName         branch the agent worked on
+ * @param {string} opts.originalRef        ref to switch back to (branch or sha)
+ * @param {string} [opts.originalRefType]  'branch' | 'detached' (informational)
+ * @param {string} opts.dispatchId         dispatch id (alert dedupe key)
+ * @param {string} [opts.projectName]      project name for log/alert text
+ * @param {boolean} [opts.isTerminalFailure] true on error/timeout/crash
+ * @param {string} [opts.resultLabel]      short status word for the alert body
+ * @param {object} [opts.gitOpts]          extra execFile opts merged into cwd
+ * @param {function} [opts.log]            (level, msg) => void
+ * @param {function} opts.writeInboxAlert  (slug, body) => any  (false = deduped)
+ * @param {function} [opts._git]           test seam; defaults to shellSafeGit
+ * @returns {Promise<{restored:boolean, reason:string|null, failureAlerted:boolean, fallbackAlerted:boolean}>}
+ */
+async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
+  const {
+    localPath,
+    branchName,
+    originalRef,
+    originalRefType, // informational; kept for caller symmetry
+    dispatchId,
+    projectName,
+    isTerminalFailure,
+    resultLabel,
+    gitOpts,
+    log,
+    writeInboxAlert,
+    _git, // private injection for testing — defaults to shared.shellSafeGit
+  } = opts;
+
+  const logFn = (typeof log === 'function') ? log : () => {};
+  const git = (typeof _git === 'function') ? _git : shared.shellSafeGit;
+  const alert = (typeof writeInboxAlert === 'function') ? writeInboxAlert : () => {};
+  const proj = projectName || 'project';
+  const did = dispatchId || '(unknown)';
+  const baseOpts = { cwd: localPath, ...(gitOpts || {}) };
+
+  const result = { restored: false, reason: null, failureAlerted: false, fallbackAlerted: false };
+
+  // ── (A) Terminal-failure notify. Independent of restore; deduped per
+  //    dispatch by the alert slug+date. Only fires on a non-success terminal
+  //    result so operators get a heads-up that a live-mode run failed in
+  //    their own working tree.
+  if (isTerminalFailure && localPath && branchName) {
+    try {
+      const body = [
+        `A live-checkout dispatch ended in a non-success state` +
+          (resultLabel ? ` (${resultLabel})` : '') + `.`,
+        ``,
+        `Project: ${proj}`,
+        `Dispatch: ${did}`,
+        `Branch: ${branchName}`,
+        `Working tree: ${localPath}`,
+        ``,
+        `The agent ran in-place in your checkout, so any partial work is visible there.`,
+        `Inspect the tree, then keep, set aside, or discard the changes as you see fit.`,
+        `The engine only switches branches — it never resets, cleans, or discards your work.`,
+      ].join('\n');
+      const wrote = alert(`live-checkout-failed-${did}`, body);
+      result.failureAlerted = (wrote !== false);
+    } catch (e) {
+      logFn('warn', `live-checkout: could not write terminal-failure alert for ${did}: ${e && e.message}`);
+    }
+  }
+
+  // ── (B) Auto-restore (best-effort). ──────────────────────────────────────
+  if (!localPath || !originalRef) {
+    result.reason = 'no-original-ref';
+    return result;
+  }
+  if (originalRef === branchName) {
+    result.reason = 'already-on-branch';
+    return result;
+  }
+
+  try {
+    // No-op when HEAD already sits on the original ref. Compare both the
+    // symbolic branch name and the raw HEAD sha so the detached-HEAD restore
+    // (originalRefType:'detached', originalRef = sha) is recognized too.
+    let alreadyThere = false;
+    try {
+      const curBranchRaw = await git(['rev-parse', '--abbrev-ref', 'HEAD'], baseOpts);
+      const curBranch = (typeof curBranchRaw === 'string' ? curBranchRaw : '').trim();
+      if (curBranch && curBranch === originalRef) alreadyThere = true;
+    } catch { /* best-effort — fall through to the sha probe */ }
+    if (!alreadyThere) {
+      try {
+        const curShaRaw = await git(['rev-parse', 'HEAD'], baseOpts);
+        const curSha = (typeof curShaRaw === 'string' ? curShaRaw : '').trim();
+        if (curSha && curSha === originalRef) alreadyThere = true;
+      } catch { /* best-effort */ }
+    }
+    if (alreadyThere) {
+      result.reason = 'already-on-original-ref';
+      return result;
+    }
+
+    // PLAIN checkout — NO --force. git refuses if uncommitted changes would be
+    // overwritten; that refusal is honored rather than clobbering the tree.
+    try {
+      await git(['checkout', originalRef], baseOpts);
+      result.restored = true;
+      result.reason = 'restored';
+      logFn('info', `live-checkout: restored ${proj} to ${originalRef} after dispatch ${did}`);
+      return result;
+    } catch (checkoutErr) {
+      // Refused (most likely uncommitted agent work). Do NOT force. Notify.
+      result.reason = 'checkout-refused';
+      logFn('warn',
+        `live-checkout: could not auto-restore ${proj} to ${originalRef} (leaving tree as-is): ` +
+        `${checkoutErr && checkoutErr.message}`);
+      try {
+        const body = [
+          `Could not automatically switch ${proj} back to "${originalRef}" after a live-checkout`,
+          `dispatch — git declined the switch, most likely because the working tree has`,
+          `uncommitted changes that a plain checkout would overwrite.`,
+          ``,
+          `Dispatch: ${did}`,
+          `Current branch: ${branchName}`,
+          `Working tree: ${localPath}`,
+          ``,
+          `Your tree was left untouched (no force, no reset, no clean, no stash). To return`,
+          `to your original ref, keep or set aside the pending changes, then switch manually:`,
+          ``,
+          `    git -C "${localPath}" checkout ${originalRef}`,
+        ].join('\n');
+        const wrote = alert(`live-checkout-branch-${did}`, body);
+        result.fallbackAlerted = (wrote !== false);
+      } catch (e) {
+        logFn('warn', `live-checkout: could not write restore-fallback alert for ${did}: ${e && e.message}`);
+      }
+      return result;
+    }
+  } catch (restoreErr) {
+    // Strictly best-effort — swallow so restore never alters the dispatch result.
+    result.reason = 'error';
+    logFn('warn', `live-checkout: restore hiccup for ${did}: ${restoreErr && restoreErr.message}`);
+    return result;
+  }
 }
 
-module.exports = { prepareLiveCheckout };
+module.exports = { prepareLiveCheckout, restoreLiveCheckoutAtDispatchEnd };