@yemi33/minions 0.1.2238 → 0.1.2240

package/dashboard/js/command-center.js

@@ -1144,6 +1144,14 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
   // render-utils.js ccSegments* helpers.
   var segments = [];
   if (activeTab) activeTab._segments = segments;
+  // Set when a stream interruption triggers a reconnect. The server replays the
+  // full accumulated snapshot (all tools + the whole text as one chunk) on
+  // reconnect, so the already-rendered segments must be cleared to avoid
+  // duplication — but we DEFER that clear until the replay's first event
+  // actually arrives (see _handleEvent) instead of blanking the bubble at
+  // reconnect time. Eager clearing produced a visible disappear/reappear of the
+  // streamed response during the >1s reconnect wait (health check + backoff).
+  var _ccReplayPending = false;
 
   // Get active tab's sessionId to send with request
   var tabSessionId = activeTab ? activeTab.sessionId : null;
@@ -1258,6 +1266,17 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
     var pendingEventName = '';
 
     async function _handleEvent(evt) {
+      // First event after a reconnect: the server replays the full accumulated
+      // snapshot (all prior tools, then the whole text as one chunk — see the
+      // reconnect branch in dashboard.js). Swap the pre-reconnect segments out
+      // atomically HERE, the instant the replay starts arriving, instead of
+      // blanking them at reconnect time. This keeps the streamed response on
+      // screen continuously across a reconnect (no disappear/reappear flicker).
+      if (_ccReplayPending && (evt.type === 'chunk' || evt.type === 'tool' || evt.type === 'tool-update' || evt.type === 'done')) {
+        segments.length = 0; // clear in place — activeTab._segments shares this ref
+        if (activeTab) activeTab._segments = segments;
+        _ccReplayPending = false;
+      }
       if (evt.type === 'chunk') {
         // evt.segmentId (from engine/llm.js) marks distinct assistant text
         // blocks; ccSegmentsApplyChunk falls back to a heuristic when it's
@@ -1450,8 +1469,12 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
         break;
       }
       reconnectAttempts++;
-      segments = [];
-      if (activeTab) activeTab._segments = segments;
+      // Don't blank the already-streamed content here. Defer clearing `segments`
+      // until the reconnect's replay actually starts delivering (see the
+      // _ccReplayPending guard in _handleEvent), so the bubble keeps showing the
+      // prior content (with the "reattaching" note below it) instead of going
+      // empty for the >1s reconnect window and then re-filling.
+      _ccReplayPending = true;
       streamStatusNote = 'Connection interrupted — reattaching to the live response...';
       updateStreamDiv();
       await new Promise(function(r) { setTimeout(r, 1000 * reconnectAttempts); });

package/dashboard/js/refresh.js

@@ -151,7 +151,9 @@ const RENDER_VERSIONS = {
   skills: 1,
   commands: 1,
   mcpServers: 1,
-  harnessDiag: 1,
+  // Bumped to 2 by W-mqptgmcn000k5c90: renderHarnessDiagnostics now stamps each
+  // <details> with a stable data-hkey and the render is gated behind _changed().
+  harnessDiag: 2,
   schedules: 1,
   watches: 3,
   meetings: 1,
@@ -875,10 +877,23 @@ function _processStatusUpdate(data, opts) {
       .then(function (r) { return r.ok ? r.json() : Promise.reject(); })
       .then(function (fresh) {
         window._lastHarnessDiag = fresh;
-        _safeRender('harnessDiag', function() { renderHarnessDiagnostics(fresh); });
+        // renderHarnessDiagnostics rewrites #harness-diag innerHTML, which
+        // destroys the native <details> open/closed state the operator just
+        // clicked. The diagnostic changes rarely, so only re-render when the
+        // freshly-fetched payload differs from the last-rendered one (mirrors
+        // the _changed() cache-bust used for mcpServers/commands). Steady-state
+        // polls bail out here and leave the user's expanded sections intact.
+        if (_changed('harnessDiag', fresh)) {
+          _safeRender('harnessDiag', function() { renderHarnessDiagnostics(fresh); });
+        }
       })
       .catch(function () {
-        if (window._lastHarnessDiag) _safeRender('harnessDiag', function() { renderHarnessDiagnostics(window._lastHarnessDiag); });
+        // Fetch failed — only paint the cached diagnostic if it has not already
+        // been rendered (first-load failure recovery). Re-painting an
+        // already-rendered payload would needlessly collapse open sections.
+        if (window._lastHarnessDiag && _changed('harnessDiag', window._lastHarnessDiag)) {
+          _safeRender('harnessDiag', function() { renderHarnessDiagnostics(window._lastHarnessDiag); });
+        }
       });
   });
   // Schedule definitions stay on /api/status (config-derived), but the

package/dashboard/js/render-other.js

@@ -663,7 +663,7 @@ function renderHarnessDiagnostics(diag) {
 
   // Per-runtime adapter rows
   for (const r of diag.runtimes || []) {
-    parts.push('<details style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Runtime: ' + escHtml(r.name) + '</summary>' +
+    parts.push('<details data-hkey="rt:' + escHtml(r.name) + '" style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Runtime: ' + escHtml(r.name) + '</summary>' +
       _harnessRowsBlock('User asset dirs (--add-dir)', r.userAssetDirs) +
       _harnessRowsBlock('Skill roots (CLI native discovery)', r.skillRoots) +
       _harnessRowsBlock('Skill write targets', r.skillWriteTargets) +
@@ -674,7 +674,7 @@ function renderHarnessDiagnostics(diag) {
 
   // --add-dir snapshot for fleet default
   const snap = diag.addDirSnapshot || [];
-  parts.push('<details open style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">--add-dir snapshot for ' + escHtml(diag.fleetDefaultCli || 'fleet default') + ' <span style="color:var(--muted);font-weight:400">(' + snap.length + ' dir' + (snap.length === 1 ? '' : 's') + ')</span></summary>' +
+  parts.push('<details data-hkey="addDirSnapshot" open style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">--add-dir snapshot for ' + escHtml(diag.fleetDefaultCli || 'fleet default') + ' <span style="color:var(--muted);font-weight:400">(' + snap.length + ' dir' + (snap.length === 1 ? '' : 's') + ')</span></summary>' +
     (snap.length === 0
       ? '<div style="font-size:var(--text-sm);color:var(--muted);margin:6px 0 0 12px"><em>(no dirs attached — engine/spawn-agent.js unavailable or adapter has no asset dirs)</em></div>'
       : snap.map(d =>
@@ -686,7 +686,7 @@ function renderHarnessDiagnostics(diag) {
   // Suppressed assets
   const suppressed = diag.suppressed || [];
   if (suppressed.length > 0) {
-    parts.push('<details open style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Suppressed assets <span style="color:var(--muted);font-weight:400">(' + suppressed.length + ')</span></summary>' +
+    parts.push('<details data-hkey="suppressed" open style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Suppressed assets <span style="color:var(--muted);font-weight:400">(' + suppressed.length + ')</span></summary>' +
       suppressed.map(s =>
         '<div style="margin:6px 0 0 12px"><code style="color:var(--orange)">' + escHtml(s.flag) + '</code> <span style="color:var(--muted);font-size:var(--text-sm)">(' + escHtml(String(s.value)) + ')</span>' +
         '<div style="font-size:var(--text-sm);color:var(--muted);margin-left:18px">' + escHtml(s.effect || '') + '</div></div>'
@@ -697,7 +697,7 @@ function renderHarnessDiagnostics(diag) {
   // Project-local-on-main footgun
   const footgun = (diag.projectLocalOnMain || []).filter(e => e && e.uncommittedAssets && e.uncommittedAssets.length > 0);
   if (footgun.length > 0) {
-    parts.push('<details open style="margin:6px 0;border:1px solid var(--orange);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer;color:var(--orange)">⚠ Project-local assets on main checkout (won\'t propagate to worktree)</summary>' +
+    parts.push('<details data-hkey="footgun" open style="margin:6px 0;border:1px solid var(--orange);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer;color:var(--orange)">⚠ Project-local assets on main checkout (won\'t propagate to worktree)</summary>' +
       footgun.map(entry =>
         '<div style="margin:8px 0 0 12px">' +
           '<div style="font-weight:600">' + escHtml(entry.project) + ' <span style="font-family:monospace;color:var(--muted);font-weight:400">' + escHtml(entry.localPath) + '</span></div>' +
@@ -713,7 +713,7 @@ function renderHarnessDiagnostics(diag) {
   // Missing dirs summary (aggregate)
   const missing = diag.missingDirs || [];
   if (missing.length > 0) {
-    parts.push('<details style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Missing on-disk dirs <span style="color:var(--muted);font-weight:400">(' + missing.length + ')</span></summary>' +
+    parts.push('<details data-hkey="missingDirs" style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Missing on-disk dirs <span style="color:var(--muted);font-weight:400">(' + missing.length + ')</span></summary>' +
       '<div style="font-size:var(--text-sm);color:var(--muted);margin:4px 0 6px 12px">Adapters declare these paths but they do not exist on this host. Warnings, not failures — create them if the runtime should look there.</div>' +
       missing.map(m =>
         '<div style="font-family:monospace;font-size:var(--text-sm);margin-left:18px"><span style="color:var(--orange)">⚠</span> ' + escHtml(m.path) + ' <span style="color:var(--muted)">[' + escHtml(m.scope) + ' · ' + escHtml(m.kind) + ' · ' + escHtml(m.runtime) + ']</span></div>'
@@ -721,8 +721,22 @@ function renderHarnessDiagnostics(diag) {
     '</details>');
   }
 
+  // Native details open/closed is DOM state, not data — a full innerHTML
+  // rewrite would reset every section the operator expanded. Snapshot the
+  // current open/closed state keyed by the stable data-hkey before the rewrite,
+  // then re-apply it afterward so a genuine content change doesn't collapse the
+  // user's expanded sections. (Steady-state no-op polls are already short-
+  // circuited upstream in refresh.js via _changed('harnessDiag', …).)
+  const prevOpen = {};
+  for (const d of el.querySelectorAll('details[data-hkey]')) {
+    prevOpen[d.getAttribute('data-hkey')] = d.open;
+  }
   // eslint-disable-next-line no-unsanitized/property -- reason: structural HTML is a string literal; all user data wrapped in escHtml() (fields: runtime name, path, scope, flag, effect, project name, localPath, file, kind)
   el.innerHTML = parts.join('');
+  for (const d of el.querySelectorAll('details[data-hkey]')) {
+    const k = d.getAttribute('data-hkey');
+    if (Object.prototype.hasOwnProperty.call(prevOpen, k)) d.open = prevOpen[k];
+  }
 }
 
 window.MinionsOther = { renderProjects, optimisticallyAddProject, projectChipRemove, renderMcpServers, renderCommands, renderHarnessDiagnostics, renderMetrics, renderLlmPerf, renderTokenUsage, _aggregateEngineUsageForTokenTile, openScanProjectsModal };

package/dashboard/js/render-plans.js

@@ -7,12 +7,14 @@ function _plansPrev() { if (_plansPage > 0) { _plansPage--; refresh(); } }
 function _plansNext() { _plansPage++; refresh(); }
 
 function openCreatePlanModal() {
-  const projOpts = (typeof cmdProjects !== 'undefined' ? cmdProjects : []).map(p =>
-    '<label style="display:flex;align-items:center;gap:6px;padding:4px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);cursor:pointer;font-size:var(--text-md);color:var(--text)">' +
-      '<input type="checkbox" class="plan-new-project-cb" value="' + escapeHtml(p) + '" onchange="_updatePlanProjectHint()">' +
-      escapeHtml(p) +
-    '</label>'
-  ).join('');
+  const projOpts = (typeof cmdProjects !== 'undefined' ? cmdProjects : []).map(p => {
+    const name = typeof p === 'object' ? p.name : p;
+    const label = (typeof p === 'object' && (p.displayName || p.name)) || name;
+    return '<label style="display:flex;align-items:center;gap:6px;padding:4px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);cursor:pointer;font-size:var(--text-md);color:var(--text)">' +
+      '<input type="checkbox" class="plan-new-project-cb" value="' + escapeHtml(name) + '" onchange="_updatePlanProjectHint()">' +
+      escapeHtml(label) +
+    '</label>';
+  }).join('');
   const inputStyle = 'display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md);font-family:inherit';
 
   document.getElementById('modal-title').textContent = 'Create Plan';

package/dashboard/js/render-work-items.js

@@ -579,9 +579,11 @@ function openCreateWorkItemModal() {
   const agentOpts = (typeof cmdAgents !== 'undefined' ? cmdAgents : []).map(a =>
     '<option value="' + escapeHtml(a.id) + '">' + escapeHtml(a.name) + '</option>'
   ).join('');
-  const projOpts = (typeof cmdProjects !== 'undefined' ? cmdProjects : []).map(p =>
-    '<option value="' + escapeHtml(p) + '">' + escapeHtml(p) + '</option>'
-  ).join('');
+  const projOpts = (typeof cmdProjects !== 'undefined' ? cmdProjects : []).map(p => {
+    const name = typeof p === 'object' ? p.name : p;
+    const label = (typeof p === 'object' && (p.displayName || p.name)) || name;
+    return '<option value="' + escapeHtml(name) + '">' + escapeHtml(label) + '</option>';
+  }).join('');
   const inputStyle = 'display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md);font-family:inherit';
 
   document.getElementById('modal-title').textContent = 'Create Work Item';

package/dashboard/js/utils.js

@@ -180,6 +180,29 @@ function pushModalFrame(frame) {
   // The current visible (if any) is snapshotted and pushed onto _modalStack as
   // a breadcrumb; scrollY is captured here so popping restores the user's
   // place in the parent view.
+  //
+  // Direct-open promotion: a modal opened by a direct row-click opener
+  // (openWorkItemDetail, openModal, openAllWorkItems, viewAgentOutput, …) paints
+  // the body and adds .open WITHOUT routing through pushModalFrame, so it sets
+  // neither _currentVisibleArtifact nor a history entry of its own. If we only
+  // snapshotted it as an opaque breadcrumb (the old `else if` path) the parent
+  // never got a baseline depth-1 history entry, so a later Back diffed straight
+  // past it to depth 0 and tore the WHOLE modal down. Fix: FIRST promote the
+  // direct-opened parent to a tracked opaque '_direct' frame and push its own
+  // baseline depth-1 history entry, THEN fall through to the normal breadcrumb
+  // snapshot + depth-2 child push below. Net history: [page] -> [parent _direct
+  // depth 1] -> [child depth 2], so Back lands on the parent (depth 1) and only
+  // a second Back closes the modal.
+  if (!_currentVisibleArtifact && _modalIsOpen()) {
+    _currentVisibleArtifact = {
+      type: '_direct',
+      id: '_direct_' + (++_legacyFrameSeq),
+      openFn: null,
+      openArgs: null,
+    };
+    _updateModalChrome();
+    _pushModalHistoryState();
+  }
   if (_currentVisibleArtifact) {
     var snap = _captureModalSnapshot();
     _modalStack.push({
@@ -191,19 +214,6 @@ function pushModalFrame(frame) {
       openFn: _currentVisibleArtifact.openFn || null,
       openArgs: _currentVisibleArtifact.openArgs || null,
     });
-  } else if (_modalIsOpen()) {
-    // Modal was direct-opened (row click) without going through openArtifact.
-    // Snapshot it as an opaque _direct breadcrumb so Back still restores it.
-    var snap2 = _captureModalSnapshot();
-    _modalStack.push({
-      type: '_direct',
-      id: '_direct_' + (++_legacyFrameSeq),
-      titleHtml: snap2.titleHtml,
-      bodyHtml: snap2.bodyHtml,
-      scrollY: snap2.scrollY,
-      openFn: null,
-      openArgs: null,
-    });
   }
   _currentVisibleArtifact = {
     type: frame.type,

package/dashboard.js

@@ -4036,7 +4036,7 @@ function buildCCStatePreamble() {
   const pending = (dq.pending || []).length;
 
   const prCount = getPullRequests().length;
-  const wiCount = getWorkItems().length;
+  const wiCount = getWorkItems(null, { enrich: false }).length;
 
   const planFiles = [...safeReadDir(PLANS_DIR), ...safeReadDir(PRD_DIR)].filter(f => f.endsWith('.md') || f.endsWith('.json'));
 
@@ -4131,7 +4131,7 @@ function buildCCStateRefresh() {
     const active = activeLines ? activeLines + overflow : '(none)';
     const pending = (dq.pending || []).length;
     const prCount = getPullRequests().length;
-    const wiCount = getWorkItems().length;
+    const wiCount = getWorkItems(null, { enrich: false }).length;
     activitySection = `
 
 **Active dispatch:**

package/docs/harness-transparency.md

@@ -127,15 +127,16 @@ evaluation pass) can see what tooling drove a dispatch:
    rely on the work-item modal surface (#3) instead — they write no inbox note
    at all (#308 removed the standalone harness-usage digest to cut note spam).
 3. **Work-item detail modal** — the dashboard work-item modal shows the
-   grounded harness list alongside the completion artifacts, with the
-   `grounded: false` entries visually distinguished (P-d5a6f7c4). On
+   harness list alongside the completion artifacts (P-d5a6f7c4). On
    completion, `engine/lifecycle.js promoteCompletionArtifacts` persists the
    grounded `structuredCompletion.harnessUsed` onto the work item as
    `_harnessUsed` (it survives the slim `/api/work-items` list payload and
    modal hydration). `dashboard/js/render-work-items.js _wiRenderDetail` renders
-   the "Repo harnesses used" section from `item._harnessUsed`: one pill per
-   skill / MCP / command / doc, with `grounded: false` entries shown on a dashed
-   yellow border and a ⚠ marker so the human can adjudicate the discrepancy.
+   the "Repo harnesses used" section from `item._harnessUsed`: one plain solid
+   pill per skill / MCP / command / doc. The grounding flag is **not** surfaced
+   in this modal — every entry renders identically (the per-pill dashed-border /
+   ⚠ marker distinction was dropped in PR #296). Grounding is surfaced only on
+   the PR-comment surface above.
 
 ## Why it matters
 

package/docs/live-checkout-mode.md

@@ -18,9 +18,9 @@ The default `worktree` mode spawns each dispatch inside its own git worktree und
 
 For these repos, the operator usually already has one canonical checkout that builds correctly. Live-checkout mode lets the agent dispatch into that checkout instead of cloning a side-by-side copy.
 
-## Contract (four guarantees)
+## Contract (five guarantees)
 
-Live mode is opinionated about what the engine will and will not do to the operator's tree. The contract has four guarantees; the engine enforces all four and fails dispatches that would violate them.
+Live mode is opinionated about what the engine will and will not do to the operator's tree. The contract has five guarantees; the engine enforces all five and fails dispatches that would violate them.
 
 ### 1. Per-project mutating-concurrency cap of 1
 
@@ -30,15 +30,19 @@ Implementation: `engine.js` builds a `liveProjectsInUse` set from the active dis
 
 ### 2. Refuse-on-dirty (engine never resets the operator tree)
 
-Before spawning, `engine/live-checkout.js#prepareLiveCheckout` runs `git status --porcelain` from `project.localPath`. Any output (staged, unstaged, untracked) refuses the dispatch immediately:
+Before spawning, `engine/live-checkout.js#prepareLiveCheckout` runs `git status --porcelain` from `project.localPath`. Any output (staged, unstaged, untracked) **returns** an explicit `{ ok:false, reason:'dirty', dirtyFiles:[…] }` result (it does NOT throw), which refuses the dispatch immediately:
 
-- Non-retryable `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (added to `engine/dispatch.js`'s `neverRetry` set so the dispatcher never re-spawns mechanically).
+- Non-retryable `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (added to `engine/dispatch.js`'s `neverRetry` set so the dispatcher never re-spawns mechanically). **Reserved for this confirmed-dirty result only** — a thrown helper/git error is `LIVE_CHECKOUT_FAILED`, see below (#305).
 - Inbox alert written via `dispatch.writeInboxAlert('live-checkout-dirty-<wi-id>', body)`. The body lists the dirty files verbatim from `git status --porcelain`.
 - Work item stamped with `_pendingReason: 'live_checkout_dirty'` so the dashboard surfaces the block.
 - Completion summary: `live-checkout refused: N dirty file(s) in <localPath>`.
 
 The engine never calls `git reset --hard`, `git clean -fd`, `git stash`, or any other state-mutating command against the operator's checkout — not at spawn, not at cleanup, not on timeout, not on engine restart. Cleanup paths (`worktreePool.returnToPool`, `worktree-gc.gcDispatchWorktreeIfOrphan`, `_quarantineDirtyWorktree`) are naturally no-ops because `worktreePath` stays `null` end-to-end (`engine.js:1219`).
 
+#### 2a. Thrown pre-spawn failures are retryable, NOT dirty (#305)
+
+A thrown error from `prepareLiveCheckout` — a required-arg/ref-validation guard, or a transient `git status`/`rev-parse`/`checkout`/`symbolic-ref` failure — is **not** proof that the operator tree is dirty. `spawnAgent`'s `catch` block therefore completes the dispatch with the **separate** `FAILURE_CLASS.LIVE_CHECKOUT_FAILED` (`'live-checkout-failed'`), which is deliberately **excluded** from `engine/dispatch.js`'s `neverRetry` set. The dispatcher auto-retries with bounded backoff up to `ENGINE_DEFAULTS.maxRetries`, so racy branch-lock handoff, a just-finished sibling dispatch, or transient git state recovers on the next attempt **without a manual `/api/work-items/retry`**. Genuinely terminal underlying reasons (auth, validation) still short-circuit via the reason-string check in `isRetryableFailureReason`. No dirty-files inbox alert is written and no `_pendingReason: 'live_checkout_dirty'` stamp is applied for this path — those belong to the confirmed-dirty result above.
+
 ### 3. No auto-pull, no `--force`, no fast-forward
 
 After the clean-tree check, `prepareLiveCheckout`:
@@ -57,6 +61,26 @@ Live mode shares one checkout per project. There is no pool to recycle, no quara
 
 Pool short-circuits live in `engine.js:1368` and `engine/cleanup.js`; both gate on `worktreePath` truthiness and `!liveMode`, so the borrow / return / orphan-GC paths execute zero git commands when the project is live.
 
+### 5. Refuse on mid-operation / detached HEAD (engine never aborts the operator's in-progress op)
+
+`prepareLiveCheckout` runs a second preflight *between* the dirty-tree check (Guarantee 2) and branch resolution (Guarantee 3). Even on a **clean** tree, the branch switch/create is refused when the operator checkout is mid-operation or sitting on a detached HEAD:
+
+- **In-progress git operation.** The git dir is resolved robustly via `git rev-parse --git-dir` (so submodule / gitdir-file / `repo`-managed trees — the setups that motivate live mode — are covered), then sentinel paths under it are probed: `MERGE_HEAD` → merge, `rebase-merge/` & `rebase-apply/` → rebase, `CHERRY_PICK_HEAD` → cherry-pick, `REVERT_HEAD` → revert. First hit returns `{ ok:false, reason:'mid-operation', op, details }`.
+- **Detached HEAD.** `git symbolic-ref -q HEAD` exiting non-zero returns `{ ok:false, reason:'detached-head', sha }` (sha from `git rev-parse HEAD`). Branching off a detached HEAD would strand the operator's anonymous commits.
+
+Either condition fails the dispatch non-retryably with `FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION` (`'live-checkout-mid-operation'`; added to `engine/dispatch.js`'s neverRetry set alongside `LIVE_CHECKOUT_DIRTY`). `spawnAgent` writes a `live-checkout-blocked-<wi-id>` inbox alert and stamps the work item `_pendingReason: 'live_checkout_mid_operation'` (or `'live_checkout_detached_head'` for the detached case). The recovery guidance tells the operator to finish or abort the in-progress op with their own commands (`git <op> --continue` / `git <op> --abort`), or checkout a branch, then re-dispatch. The engine never runs `git reset`, `git clean`, `git stash`, `git rebase --abort`, or moves HEAD on the operator's behalf.
+
+## Dispatch-end auto-restore
+
+Live-mode agents run **in-place** in the operator's checkout, so when a dispatch ends the engine switches the tree back to the ref it was on before the agent ran. This runs on **every** terminal result — success, failure, timeout, crash — and also on the engine-restart re-attach completion path (`engine/cli.js`), so a restart mid-dispatch does not strand the checkout on the agent's branch.
+
+- **Original-ref capture.** `prepareLiveCheckout` records the operator's starting ref *before* the first checkout: `git symbolic-ref --short HEAD` → `{ originalRef:<branch>, originalRefType:'branch' }`, falling back to `git rev-parse HEAD` → `{ originalRef:<sha>, originalRefType:'detached' }`. `spawnAgent` persists `originalRef` / `originalRefType` onto the dispatch record via `mutateDispatch`, so the restore survives an engine restart, where the in-memory spawn closure is gone and only the persisted record remains.
+- **AUTO-RESTORE (best-effort, never `--force`).** At dispatch-end `restoreLiveCheckoutAtDispatchEnd` issues a **plain** `git checkout <originalRef>` — no `--force`, no `-B`, no reset, no clean, no stash. It no-ops when there is nothing to restore: no captured `originalRef`, the agent branch *is* the original ref, or HEAD already sits on the original ref (matched against the branch name *or* the raw sha so the detached-HEAD case is recognized). It is strictly best-effort: every error is swallowed and logged, and a restore never alters the dispatch result.
+- **Fallback notify (only when a safe switch is impossible).** If git declines the plain checkout — most likely because the agent left uncommitted changes a checkout would overwrite — the refusal is **honored**: the tree is left exactly as the agent left it and a deduped `live-checkout-branch-<dispatchId>` inbox alert tells the operator how to switch back manually (`git -C <localPath> checkout <originalRef>`). The engine never forces the switch.
+- **Terminal-failure alert.** When the dispatch ends in a non-success terminal state, a deduped `live-checkout-failed-<dispatchId>` inbox alert is written so the operator knows a live-mode run failed inside their own checkout (where any partial work is visible). This is independent of the restore and fires even when the restore itself succeeds.
+
+The core invariant holds end-to-end through restore: **the engine only ever switches branches — it never `git reset`s, `git clean`s, or `git stash`es the operator's tree, and never passes `--force`.**
+
 ## Operator workflow
 
 ### Enabling live mode (dashboard)
@@ -127,7 +151,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 - **No per-WI subdirectory isolation.** Live mode is one-checkout-per-project by design. If you need isolation, use `checkoutMode: 'worktree'` (the default).
 - **No per-WI override.** `checkoutMode` is per-project only. There is no `meta.checkoutMode` on a work item that overrides the project setting.
 - **No auto-pull / no fast-forward on existing branches.** See Guarantee 3. If a PR branch is checked out locally at a different SHA than `origin/<branch>`, the operator resolves it manually.
-- **No special timeout / kill handling.** Live-mode dispatches are killed by PID exactly like isolated-mode dispatches (`engine/timeout.js` header comment). The engine sends SIGTERM/SIGKILL to the tracked process and never touches the working tree on kill.
+- **No special timeout / kill handling.** Live-mode dispatches are killed by PID exactly like isolated-mode dispatches (`engine/timeout.js` header comment). The engine sends SIGTERM/SIGKILL to the tracked process and never touches the working tree to deliver the kill. (Dispatch-end auto-restore still runs afterward — a plain branch switch back to the operator's original ref, never a reset/clean/stash; see [Dispatch-end auto-restore](#dispatch-end-auto-restore).)
 
 ## Related code
 
@@ -135,12 +159,18 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 |---|---|
 | `engine/shared.js` — `CHECKOUT_MODES`, `validateCheckoutMode`, `resolveCheckoutMode`, `isLiveCheckoutProject` | Enum + validator + back-compat resolver (P-a3f9b201; consolidated W-mqiaw974). |
 | `engine/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live projects (P-a3f9b202). |
-| `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, branch resolution from HEAD (no fetch, no `origin/<mainRef>` — issue #226) (P-a3f9b203). |
+| `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, mid-operation / detached-HEAD preflight, original-ref capture, branch resolution from HEAD (no fetch, no `origin/<mainRef>` — issue #226) (P-a3f9b203; preflight + capture P-b2e8d4a6). |
+| `engine/live-checkout.js` — `restoreLiveCheckoutAtDispatchEnd` | Dispatch-end auto-restore (plain `git checkout <originalRef>`, never `--force`/reset/clean/stash, best-effort) + `live-checkout-failed-<dispatchId>` terminal-failure alert + `live-checkout-branch-<dispatchId>` fallback notify (P-d9e6b2c4). |
 | `engine.js` — `spawnAgent` live-mode block | Calls `prepareLiveCheckout`, handles dirty / throw branches, gates `git worktree add` on `!liveMode` (P-a3f9b204). |
+| `engine.js` — `spawnAgent` mid-op / detached-HEAD refusal block | Emits `LIVE_CHECKOUT_MID_OPERATION`, writes `live-checkout-blocked-<wi-id>` alert, stamps `_pendingReason: 'live_checkout_mid_operation'` / `'live_checkout_detached_head'` (P-c5a1f3b8). |
+| `engine.js` — `spawnAgent` originalRef persistence | Persists `originalRef` / `originalRefType` onto the dispatch record via `mutateDispatch` so restore survives an engine restart (P-c5a1f3b8). |
+| `engine.js` — `onAgentClose` live-mode restore wiring | Calls `restoreLiveCheckoutAtDispatchEnd` on every terminal result (P-d9e6b2c4). |
+| `engine/cli.js` — orphan / reattach restore | Fires the same dispatch-end restore from the persisted record on the engine-restart completion path (P-d9e6b2c4). |
 | `engine.js` — dispatcher `liveProjectsInUse` set | Per-project mutating-concurrency cap (P-a3f9b205). |
 | `engine.js` — worktree-pool / orphan-GC short-circuits | `worktreePath===null` no-ops in live mode (P-a3f9b206). |
 | `dashboard/js/settings.js` — checkoutMode dropdown + chip | Operator-facing UI (P-a3f9b207). |
 | `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring}.test.js` | Wiring and contract tests (P-a3f9b208). |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` | Non-retryable refusal class. |
-| `engine/dispatch.js` — `isRetryableFailureReason` neverRetry | Excludes `LIVE_CHECKOUT_DIRTY` from mechanical retry. |
+| `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION` | Non-retryable refusal class for a mid-operation / detached-HEAD operator tree (in-progress merge/rebase/cherry-pick/revert or detached HEAD), distinct from the dirty-tree class. Emitted by `spawnAgent`'s mid-op / detached-HEAD refusal block (P-a7f3c1d9; wired P-c5a1f3b8). |
+| `engine/dispatch.js` — `isRetryableFailureReason` neverRetry | Excludes `LIVE_CHECKOUT_DIRTY` and `LIVE_CHECKOUT_MID_OPERATION` from mechanical retry. |
 | `engine/timeout.js` header comment | Confirms no special live-mode kill handling. |

package/engine/cli.js

@@ -895,6 +895,32 @@ const commands = {
             );
           } catch (err) { e.log('warn', `Orphan dispatch complete: ${err.message}`); }
 
+          // P-d9e6b2c4 — live-mode dispatch-end auto-restore + terminal-failure
+          // notify on the engine-restart reattach completion path. originalRef
+          // is only persisted for live-mode dispatches (P-c5a1f3b8), so its
+          // presence is the liveMode signal here — the slimmed meta.project
+          // carries no checkoutMode. Mirrors the in-process onAgentClose wiring
+          // (engine.js). Fire-and-forget + best-effort: the helper swallows its
+          // own errors and only ever issues a plain `git checkout <originalRef>`
+          // (never --force/reset/clean/stash) against the operator tree.
+          if (item.originalRef && item.meta?.branch && item.meta?.project?.localPath) {
+            try {
+              require('./live-checkout').restoreLiveCheckoutAtDispatchEnd({
+                localPath: item.meta.project.localPath,
+                branchName: item.meta.branch,
+                originalRef: item.originalRef,
+                originalRefType: item.originalRefType || 'branch',
+                dispatchId: item.id,
+                projectName: item.meta.project.name,
+                isTerminalFailure: !isSuccess,
+                resultLabel: result,
+                gitOpts: { env: shared.gitEnv(), windowsHide: true, timeout: 30000 },
+                log: (lvl, msg) => e.log(lvl, msg),
+                writeInboxAlert: dispatchModule().writeInboxAlert,
+              }).catch(() => {});
+            } catch (err) { e.log('warn', `Orphan live-checkout restore: ${err.message}`); }
+          }
+
           // Check plan completion
           if (isSuccess && item.meta?.item?.sourcePlan) {
             try { lifecycle.checkPlanCompletion(item.meta, config); } catch (err) { e.log('warn', `Orphan plan completion: ${err.message}`); }

package/engine/comment-classifier.js

@@ -64,7 +64,7 @@ const _BADGE_RE = /!\[.*\]\(https?:\/\/.*badge/i;
 const _PREVIEW_HEADING_RE =
   /^#{1,3}\s*(Firebase(?:\s+App\s+Distribution)?|Appetize|Preview|Deploy(?:ment)?|Status)\b/i;
 
-const _FIREBASE_BRAND_RE = /\bFirebase\s+App\s+Distribution\b/i;
+const _FIREBASE_BRAND_RE = /\bFirebase\s+(?:App\s+Distribution|Hosting)\b/i;
 const _FIREBASE_URL_RE = /\bappdistribution\.firebase\b/i;
 const _APPETIZE_URL_RE = /\bappetize\.io\b/i;