@yemi33/minions 0.1.2272 → 0.1.2273

package/docs/live-checkout-mode.md

@@ -37,7 +37,7 @@ Before spawning, `engine/live-checkout.js#prepareLiveCheckout` runs `git status
 - 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`).
+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. The dispatch-scoped cleanup paths (`worktreePool.returnToPool`, `worktree-gc.gcDispatchWorktreeIfOrphan`, `_quarantineDirtyWorktree`) are naturally no-ops because `worktreePath` stays `null` end-to-end (`engine.js:1219`). The **periodic** worktree GC, however, is NOT `worktreePath`-gated — it derives its targets from `git worktree list --porcelain`, which for a live project returns the operator's *own* primary checkout. So `engine/cleanup.js#runPeriodicWorktreeSweep` now **filters out live-checkout projects entirely** (`shared.isLiveCheckoutProject`) before handing the list to the three pruners (PL-live-checkout-reliability-hardening), keeping the operator's real checkout out of the GC decision surface rather than relying only on the pruners' path-equality + ownership-marker gates.
 
 #### 2a. Thrown pre-spawn failures are retryable, NOT dirty (#305)
 
@@ -55,6 +55,16 @@ After the clean-tree check, `prepareLiveCheckout`:
 
 PR-source live dispatches (`meta.branch` set) and shared-branch live dispatches (`meta.branchStrategy === 'shared-branch'`) flow through the same code path with no special case. If the operator already has a PR branch checked out at a different SHA than `origin/<branch>`, the engine will not fast-forward it — that is the intended contract (see Open Q5 in the source PRD). Resolve manually with `git pull --ff-only` or commit the local divergence first.
 
+#### 3a. Partial-clone (GVFS) reliability hardening (PL-live-checkout-reliability-hardening)
+
+Issue #226 only de-risked the *new-branch* path. The *existing-branch* `git checkout <branch>` was still a bare checkout, and on a blobless Scalar/GVFS clone, switching onto a branch whose tree differs from HEAD must hydrate the changed paths' blobs through the same auth-less GVFS cache server — so it **fails deterministically headless**. Three changes make this reliable:
+
+- **Already-on-target-branch fast path.** Before any checkout, `prepareLiveCheckout` reads the current branch (`git rev-parse --abbrev-ref HEAD`); if HEAD already points at the target branch it returns success with `alreadyOnBranch: true` and issues **no** checkout. This eliminates the most common blob-fetch trigger — a re-dispatch onto a branch the agent is already on.
+- **No half-switch.** `originalRef` is captured *before* the checkout, and on any existing-branch checkout failure the helper best-effort switches HEAD back to it (plain checkout, never `--force` — the tree was verified clean at the dirty gate, so nothing of the operator's can be lost). The tree is never stranded half-populated on the agent branch.
+- **Deterministic blob-fetch failures are non-retryable.** A GVFS / missing-object checkout failure is returned as `{ ok:false, reason:'blob-fetch' }` and completed with the dedicated **`FAILURE_CLASS.LIVE_CHECKOUT_BLOB_FETCH`** (`'live-checkout-blob-fetch'`; in `dispatch.js`'s `neverRetry` set) plus an operator-actionable `live-checkout-blocked-<wi-id>` inbox alert and a `_pendingReason: 'live_checkout_blob_fetch'` stamp — instead of being classified `LIVE_CHECKOUT_FAILED` (retryable) and retry-storming an identical structural failure to `maxRetries`. Recovery: the operator hydrates the branch once with their own credentials (`git checkout <branch>` interactively, or `scalar prefetch` / `git fetch origin <branch>`), then re-dispatches — or switches the project to `checkoutMode: "worktree"`, which fetches against the authenticated git remote.
+
+**Branch existence is checked against `refs/heads/<branch>` specifically** (not a bare `rev-parse --verify <branch>`, which DWIM-resolves a same-named tag or remote ref and would silently detach HEAD).
+
 ### 4. No worktree pool, no per-WI subdirectory isolation
 
 Live mode shares one checkout per project. There is no pool to recycle, no quarantine directory, no per-WI subdirectory under the project root. The mutating-concurrency cap (Guarantee 1) is the only isolation mechanism: agents take turns in the same directory.
@@ -65,21 +75,22 @@ Pool short-circuits live in `engine.js:1368` and `engine/cleanup.js`; both gate
 
 `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.
+- **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; a *failure* to resolve the git dir now throws → retryable `LIVE_CHECKOUT_FAILED` rather than silently probing a fabricated `<localPath>/.git` and missing the operation). Sentinel paths under it are probed: `MERGE_HEAD` → merge, `rebase-merge/` & `rebase-apply/` → rebase, `CHERRY_PICK_HEAD` → cherry-pick, `REVERT_HEAD` → revert, **`BISECT_LOG` → bisect**. First hit returns `{ ok:false, reason:'mid-operation', op, details }`.
+- **Detached HEAD.** `git symbolic-ref -q HEAD` exiting with **code 1** 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. A *transient* `symbolic-ref` failure (spawn error / timeout, no exit-1) is **not** treated as a detached HEAD — it rethrows → retryable `LIVE_CHECKOUT_FAILED` — so an on-a-branch tree that hit a hiccup is never permanently refused.
 
 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.
+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 **every restart-recovery reaping path**: the engine-restart re-attach orphan-completion path (`engine/cli.js`) AND the `engine/timeout.js` paths that reap a dispatch the engine lost the process handle for (`completeFromOutput` + the orphan sweep). All three route through the shared `maybeRestoreLiveCheckoutFromRecord(item, …)` helper (which fires from the *persisted* dispatch record — `originalRef`'s presence is the live-mode signal), so a live agent that spans an engine restart and finishes afterward never strands the checkout on the agent's branch. (Previously the timeout.js reaping paths had **no** restore wiring, which is exactly how a restart-spanning live dispatch left the operator stuck on `work/W-…`.)
 
 - **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.
+- **Self-healing dirty recovery (PL-live-checkout-reliability-hardening).** Before the plain checkout, if the tree is **dirty AND HEAD is on the agent branch** (and that branch differs from `originalRef`), the dirt is provably **agent-authored** — the engine created that branch and verified the tree clean before switching to it. The leftovers are committed onto the **agent branch** (`git add -A` + `git commit --no-verify -m "minions: auto-save agent WIP (dispatch …)"`), so the plain `git checkout <originalRef>` then succeeds and the operator tree returns clean. This is the fix for the *"no recovery from dirty checkout"* deadlock, where an agent's crash-leftover WIP refused the restore, stranded the tree dirty on the agent branch, and then made **every future WI** for that project fail `LIVE_CHECKOUT_DIRTY` until a human cleaned it. It only ever mutates the engine-created branch, never the operator's branch, never discards (the WIP lands as a visible, revertable commit / on its PR), and gitignored artifacts are never staged (so a tree dirty only with ignored build output never reaches here). Best-effort: a failed auto-commit falls through to the manual-recovery alert below.
 - **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.
+- **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. An **unexpected** restore error (git missing, repo corruption, a GVFS blob fetch on the switch-back) now also writes this alert, so a non-refusal failure never silently strands the tree.
 - **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`.**
+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`.** The one addition — the self-healing auto-commit — only ever runs `git add`/`git commit` on the engine's *own* agent branch, never on operator refs, and never discards.
 
 ## Operator workflow
 
@@ -159,18 +170,24 @@ 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, 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/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, mid-operation / detached-HEAD preflight (incl. `BISECT_LOG`; throw-on-git-dir-failure; exit-1-only detached), original-ref capture, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch` classification** for partial-clone hydration failures (P-a3f9b203; preflight + capture P-b2e8d4a6; hardening PL-live-checkout-reliability-hardening). |
+| `engine/live-checkout.js` — `restoreLiveCheckoutAtDispatchEnd` | Dispatch-end auto-restore (plain `git checkout <originalRef>`, never `--force`/reset/clean/stash, best-effort) + **self-healing dirty recovery** (auto-commit agent WIP onto the agent branch) + `live-checkout-failed-<dispatchId>` terminal-failure alert + `live-checkout-branch-<dispatchId>` fallback notify (now also on unexpected restore errors) (P-d9e6b2c4; self-heal PL-live-checkout-reliability-hardening). |
+| `engine/live-checkout.js` — `maybeRestoreLiveCheckoutFromRecord` | Shared wrapper that fires the dispatch-end restore from a persisted dispatch record; used by `cli.js` + both `timeout.js` reaping paths so a restart-spanning live dispatch is never stranded (PL-live-checkout-reliability-hardening). |
 | `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/cli.js` — orphan / reattach restore | Fires the dispatch-end restore (via `maybeRestoreLiveCheckoutFromRecord`) from the persisted record on the engine-restart completion path (P-d9e6b2c4; unified PL-live-checkout-reliability-hardening). |
+| `engine/timeout.js` — `completeFromOutput` + orphan-sweep restore | Fires `maybeRestoreLiveCheckoutFromRecord` when a re-attached live dispatch is reaped post-restart — closes the gap where these paths had no restore wiring (PL-live-checkout-reliability-hardening). |
 | `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). |
+| `engine/cleanup.js` — `runPeriodicWorktreeSweep` live filter | Excludes live-checkout projects from the registry-derived periodic worktree GC so the operator's primary checkout never enters the GC decision surface (PL-live-checkout-reliability-hardening). |
+| `engine/create-pr-worktree.js` — `prepareCreatePrWorktree` step-4 restore | `reset --hard HEAD` (not the index-leaking `checkout -- .`) + retried untracked removal + `liveTreeDirty` surfaced + `shared.removeWorktree` teardown (PL-live-checkout-reliability-hardening). |
 | `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/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/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/bisect 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/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_BLOB_FETCH` | Non-retryable refusal class for an existing-branch checkout that could not hydrate the tree on a blobless GVFS partial clone (auth-less cache fetch, headless) — deterministic, so excluded from mechanical retry (PL-live-checkout-reliability-hardening). |
+| `engine.js` — `_liveCheckoutDirtyAttempts` counter | Dedicated two-strike dirty memory (survives the discovery + retry `_pendingReason` scrubs that defeated #434); first dirty failure retries once, second fails non-retryably (PL-live-checkout-reliability-hardening). |
+| `engine/dispatch.js` — `isRetryableFailureReason` neverRetry | Excludes `LIVE_CHECKOUT_DIRTY`, `LIVE_CHECKOUT_MID_OPERATION`, and `LIVE_CHECKOUT_BLOB_FETCH` from mechanical retry. |
 | `engine/timeout.js` header comment | Confirms no special live-mode kill handling. |

package/engine/ado.js

@@ -432,7 +432,7 @@ function classifyBuildStatus(prBuilds) {
   const allDone = prBuilds.every(b => b.status === 'completed');
   const allPassed = prBuilds.every(b => b.result === 'succeeded' || b.result === 'partiallySucceeded');
   const hasRunning = prBuilds.some(b => b.status === 'inProgress' || b.status === 'notStarted');
-  if (hasFailed && allDone) return BUILD_STATUS.FAILING;
+  if (hasFailed) return BUILD_STATUS.FAILING;
   if (allDone && allPassed) return BUILD_STATUS.PASSING;
   if (hasRunning) return BUILD_STATUS.RUNNING;
   return BUILD_STATUS.NONE;

package/engine/cleanup.js

@@ -1629,9 +1629,25 @@ function scrubStaleMetrics() {
  */
 function runPeriodicWorktreeSweep(config) {
   const worktreeGc = require('./worktree-gc');
-  const projects = getProjects(config);
+  const allProjects = getProjects(config);
+  // PL-live-checkout-reliability-hardening — EXCLUDE live-checkout projects from
+  // the worktree GC entirely. The three pruners derive their targets from
+  // `git worktree list --porcelain`, which for a live project returns the
+  // OPERATOR'S OWN primary checkout (and any secondary operator worktrees). The
+  // engine never creates a managed worktree in live mode, so there is nothing
+  // here to GC — and the worktree-gc module is otherwise live-mode-blind,
+  // protected only by a path-equality skip + ownership marker (a thin, untested
+  // gate-stack whose regression could target the operator's real repo). Filtering
+  // here keeps the operator's checkout out of the GC decision surface completely.
+  // (docs/live-checkout-mode.md's "naturally no-ops because worktreePath stays
+  // null" claim is true for the dispatch-end GC but NOT for this registry-derived
+  // periodic sweep.)
+  const projects = allProjects.filter(p => {
+    try { return !shared.isLiveCheckoutProject(p); } catch { return true; }
+  });
+  const liveSkipped = allProjects.length - projects.length;
   if (projects.length === 0) {
-    return { scanned: 0, kept: 0, evicted: 0, failed: 0, outOfRootEvicted: 0, prunedRegistry: 0, missingDirReclaimed: 0, missingDirSkippedLive: 0 };
+    return { scanned: 0, kept: 0, evicted: 0, failed: 0, outOfRootEvicted: 0, prunedRegistry: 0, missingDirReclaimed: 0, missingDirSkippedLive: 0, liveProjectsSkipped: liveSkipped };
   }
   const dispatchSnap = getDispatch();
   const worktreeRootRel = config?.engine?.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot;
@@ -1705,7 +1721,7 @@ function runPeriodicWorktreeSweep(config) {
     failed += r3.failed || 0;
   } catch (e) { log('warn', `worktree-gc periodic missing-dir reclaim: ${e.message}`); }
 
-  return { scanned, kept, evicted, failed, outOfRootEvicted, prunedRegistry, missingDirReclaimed, missingDirSkippedLive };
+  return { scanned, kept, evicted, failed, outOfRootEvicted, prunedRegistry, missingDirReclaimed, missingDirSkippedLive, liveProjectsSkipped: liveSkipped };
 }
 
 // ─── Exports ─────────────────────────────────────────────────────────────────

package/engine/cli.js

@@ -868,16 +868,10 @@ const commands = {
           // (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,
+              require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
+                item,
                 isTerminalFailure: !isSuccess,
                 resultLabel: result,
-                gitOpts: { env: shared.gitEnv(), windowsHide: true, timeout: 30000 },
                 log: (lvl, msg) => e.log(lvl, msg),
                 writeInboxAlert: dispatchModule().writeInboxAlert,
               }).catch(() => {});

package/engine/create-pr-worktree.js

@@ -110,7 +110,10 @@ async function prepareCreatePrWorktree({
       _copyRecursive(fsm, src, dst);
     }
   } catch (e) {
-    try { await git(['-C', localPath, 'worktree', 'remove', '--force', wtPath]); } catch { /* leak rather than throw a second error */ }
+    // Tear the worktree down via shared.removeWorktree (EPERM/EBUSY retry +
+    // escalation + real-repo refusal — CLAUDE.md footgun #6). The live checkout
+    // has NOT been touched yet at this point, so the operator keeps their work.
+    try { shared.removeWorktree(wtPath, projectRoot, worktreesBase); } catch { /* leak rather than throw a second error */ }
     throw new Error(
       `prepareCreatePrWorktree: failed to stage changes into the worktree — ${e.message}. ` +
       'The live checkout was left untouched.',
@@ -118,20 +121,54 @@ async function prepareCreatePrWorktree({
   }
 
   // 4. The worktree now holds the changes — restore the live checkout clean.
+  //    The captured edits are SAFE in the worktree (step 3 verified), so the
+  //    documented job here is to return the live checkout to a clean HEAD.
+  //    Use `git reset --hard HEAD` (NOT `git checkout -- .`): the old
+  //    working-tree-only revert left the STAGED INDEX intact, so any change CC
+  //    had `git add`-ed stayed staged → the live checkout was reported "restored"
+  //    while still dirty, wedging the next Create-PR / live dispatch (the
+  //    operator's "no recovery from dirty checkout"). `reset --hard` reverts
+  //    staged + unstaged tracked changes in one shot; untracked entries are
+  //    removed surgically below (only the ones we captured — never ignored or
+  //    pre-existing untracked files, which `git clean` would wrongly nuke).
+  //    This `reset --hard` is intentional and scoped to THIS Create-PR-worktree
+  //    staging flow whose explicit contract is to restore the live checkout
+  //    clean — it is NOT the live-checkout DISPATCH mode (which never resets).
+  const residualUntracked = [];
   try {
-    await git(['-C', localPath, 'checkout', '--', '.']);
+    await git(['-C', localPath, 'reset', '--hard', 'HEAD']);
     for (const rel of untracked) {
-      try { fsm.rmSync(path.join(localPath, rel.replace(/\/$/, '')), { recursive: true, force: true }); } catch (rmErr) { log('warn', `[cc-create-pr] could not remove untracked ${rel} from live checkout (will remain dirty): ${rmErr.message}`); }
+      const target = path.join(localPath, rel.replace(/\/$/, ''));
+      try {
+        // Retry transient Windows file locks (EBUSY/EPERM/ENOTEMPTY) before
+        // giving up — a single failed unlink is what left the tree dirty. A few
+        // quick retries ride out a transient AV/indexer lock without a long stall.
+        shared._retryFsOp(() => fsm.rmSync(target, { recursive: true, force: true }), `cc-create-pr rm ${rel}`, { attempts: 4, baseMs: 100 });
+      } catch (rmErr) {
+        residualUntracked.push(rel);
+        log('warn', `[cc-create-pr] could not remove untracked ${rel} from live checkout after retries: ${rmErr.message}`);
+      }
     }
   } catch (e) {
-    try { await git(['-C', localPath, 'worktree', 'remove', '--force', wtPath]); } catch { /* leak rather than double-throw */ }
+    // shared.removeWorktree carries the EPERM/EBUSY retry + escalation +
+    // real-repo refusal (CLAUDE.md footgun #6 — don't hand-roll force-remove).
+    try { shared.removeWorktree(wtPath, projectRoot, worktreesBase); } catch { /* leak rather than double-throw */ }
     throw new Error(
       `prepareCreatePrWorktree: failed to restore live checkout — ${e.message}. ` +
       `Worktree at ${wtPath} may need manual cleanup.`,
     );
   }
 
-  log('info', `[cc-create-pr] staged ${project.name} changes into isolated worktree ${wtPath} on branch ${branchName} (live checkout restored)`);
+  // If untracked removal could not fully clean the live tree, surface it in the
+  // return (liveTreeDirty) instead of silently reporting success — the caller
+  // can warn CC / the operator rather than letting the residue wedge the next
+  // dispatch with a phantom "dirty" refusal.
+  const liveTreeDirty = residualUntracked.length > 0;
+  if (liveTreeDirty) {
+    log('warn', `[cc-create-pr] live checkout ${localPath} left with ${residualUntracked.length} residual untracked path(s) after staging; surfacing liveTreeDirty`);
+  } else {
+    log('info', `[cc-create-pr] staged ${project.name} changes into isolated worktree ${wtPath} on branch ${branchName} (live checkout restored)`);
+  }
   return {
     ok: true,
     worktreePath: wtPath,
@@ -140,6 +177,8 @@ async function prepareCreatePrWorktree({
     baseSha,
     trackedChanged: hasTracked,
     untrackedCount: untracked.length,
+    liveTreeDirty,
+    residualUntracked,
   };
 }
 

package/engine/dispatch.js

@@ -534,6 +534,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       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.LIVE_CHECKOUT_BLOB_FETCH, // PL-live-checkout-reliability-hardening — live-checkout `git checkout <existing-branch>` failed hydrating the tree through the auth-less GVFS cache server (blobless partial clone, headless); deterministic, so mechanical retry just reproduces it (operator must hydrate the branch with their own creds, then re-dispatch)
       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

@@ -1031,13 +1031,13 @@ async function pollPrStatus(config) {
         let buildFailureSignature = '';
 
         if (runs.length > 0) {
-          const hasFailed = runs.some(r => r.conclusion === 'failure' || r.conclusion === 'timed_out');
+          const hasFailed = runs.some(r => r.conclusion === 'failure' || r.conclusion === 'timed_out' || r.conclusion === 'startup_failure');
           const allDone = runs.every(r => r.status === 'completed');
           const allPassed = runs.every(r => r.conclusion === 'success' || r.conclusion === 'skipped' || r.conclusion === 'neutral');
 
           if (hasFailed) {
             buildStatus = BUILD_STATUS.FAILING;
-            const failed = runs.find(r => r.conclusion === 'failure' || r.conclusion === 'timed_out');
+            const failed = runs.find(r => r.conclusion === 'failure' || r.conclusion === 'timed_out' || r.conclusion === 'startup_failure');
             buildFailReason = failed?.name || 'Check failed';
             buildFailureSignature = shared.safeSlugComponent([
               failed?.name,
@@ -1735,7 +1735,7 @@ async function checkLiveBuildAndConflict(pr, project) {
           if (runs.length === 0) {
             buildStatus = BUILD_STATUS.NONE;
           } else {
-            const hasFailed = runs.some(r => r.conclusion === 'failure' || r.conclusion === 'timed_out');
+            const hasFailed = runs.some(r => r.conclusion === 'failure' || r.conclusion === 'timed_out' || r.conclusion === 'startup_failure');
             const allDone = runs.every(r => r.status === 'completed');
             const allPassed = runs.every(r => r.conclusion === 'success' || r.conclusion === 'skipped' || r.conclusion === 'neutral');
             if (hasFailed) buildStatus = BUILD_STATUS.FAILING;

package/engine/live-checkout.js

@@ -86,6 +86,37 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 
+// PL-live-checkout-reliability-hardening — partial-clone / GVFS blob-fetch
+// signature match. On a Scalar/GVFS-managed ADO repo (blobless partial clone),
+// switching the working tree onto a branch whose tree differs from HEAD must
+// materialize the changed paths' blobs on demand. That hydration goes through
+// the GVFS cache server (`*.gvfscache.dev.azure.com`) via gvfs-helper /
+// credential.helper — a DIFFERENT endpoint than the main git HTTP remote, and
+// one that receives NO auth in the headless engine shell (GIT_TERMINAL_PROMPT=0,
+// credential.helper disabled). So the checkout fails DETERMINISTICALLY headless.
+// Issue #226 only removed the new-branch-from-`origin/<mainRef>` fetch; the
+// EXISTING-branch `git checkout <branch>` was never carved out. We can't make
+// the auth-less fetch succeed here, but we CAN stop treating its deterministic
+// failure as a transient retryable error (which retry-storms to the cap), and
+// instead surface it once as an operator-actionable refusal. This matcher is
+// deliberately conservative — it keys on partial-clone / object-hydration
+// phrasing, not on generic git failures.
+function _isPartialCloneBlobError(message = '') {
+  const m = String(message || '').toLowerCase();
+  return (
+    m.includes('gvfs') ||
+    m.includes('partial clone') ||
+    m.includes('missing object') ||
+    m.includes('missing blob') ||
+    m.includes('fetch-pack') ||
+    m.includes('could not read from remote') ||
+    /unable to read (tree|sha1|object|blob)/.test(m) ||
+    /could not read[^\n]*(object|blob)/.test(m) ||
+    /failed to (fetch|download)[^\n]*(object|blob|pack)/.test(m) ||
+    (m.includes('remote') && m.includes('access denied'))
+  );
+}
+
 async function prepareLiveCheckout(opts = {}) {
   const {
     localPath,
@@ -149,28 +180,37 @@ async function prepareLiveCheckout(opts = {}) {
   // ── 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');
+  // gitdir-file / repo-managed trees resolve correctly. A FAILURE here is a
+  // real git-health problem (and on the very submodule / gitdir-file /
+  // repo-managed trees live mode targets, <localPath>/.git is NOT a directory,
+  // so the old fabricated-path fallback made every sentinel probe miss and
+  // silently skipped mid-operation detection). Throw so the caller classifies
+  // it as a retryable LIVE_CHECKOUT_FAILED instead of barging into a branch
+  // switch on top of a half-finished operation we couldn't see.
+  let gitDir;
   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);
+    if (!gitDirStr) {
+      throw new Error('git rev-parse --git-dir returned empty output');
     }
-  } catch {
-    // keep the <localPath>/.git fallback
+    gitDir = path.isAbsolute(gitDirStr) ? gitDirStr : path.join(localPath, gitDirStr);
+  } catch (e) {
+    throw new Error('prepareLiveCheckout: could not resolve git dir for ' + localPath + ' — ' + (e && e.message));
   }
 
   // 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.
+  // rebase-apply/ (am-based rebase) both mean a rebase is underway. BISECT_LOG
+  // covers an in-progress `git bisect` (bisect state is HEAD-keyed, so a branch
+  // switch would silently destroy it — the doc + header imply bisect coverage).
   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' },
+    { name: 'BISECT_LOG', op: 'bisect' },
   ];
   for (const sentinel of MID_OP_SENTINELS) {
     const sentinelPath = path.join(gitDir, sentinel.name);
@@ -179,14 +219,22 @@ async function prepareLiveCheckout(opts = {}) {
     }
   }
 
-  // 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.
+  // Detached HEAD: `git symbolic-ref -q HEAD` exits 1 when HEAD does not point
+  // at a branch. Branching off a detached HEAD would strand the operator's
+  // anonymous commits, so refuse. But distinguish a REAL detachment (git ran
+  // and returned exit code 1) from a TRANSIENT failure (spawn error / timeout /
+  // ENOENT) — the latter is not proof of detachment and must NOT permanently
+  // refuse an on-a-branch tree; rethrow so it becomes a retryable
+  // LIVE_CHECKOUT_FAILED instead.
   let detached = false;
   try {
     await git(['symbolic-ref', '-q', 'HEAD'], baseOpts);
-  } catch {
-    detached = true;
+  } catch (symErr) {
+    if (symErr && symErr.code === 1) {
+      detached = true; // git ran, HEAD is not a symbolic ref → genuinely detached
+    } else {
+      throw symErr; // spawn failure / timeout / other → transient, not detachment
+    }
   }
   if (detached) {
     let sha = '';
@@ -223,17 +271,78 @@ async function prepareLiveCheckout(opts = {}) {
   // 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).
+
+  // (4a) Already-on-target-branch fast path. On a re-dispatch the tree is
+  // usually ALREADY on the agent branch, and a redundant `git checkout <branch>`
+  // would still force on-demand blob hydration on a partial clone (the GVFS
+  // failure mode below). If HEAD already points at the target branch there is
+  // nothing to switch — return success without touching the working tree. This
+  // mirrors the no-op logic the restore helper already has.
+  let curBranch = '';
+  try {
+    const curRaw = await git(['rev-parse', '--abbrev-ref', 'HEAD'], baseOpts);
+    curBranch = (typeof curRaw === 'string' ? curRaw : '').trim();
+  } catch { /* best-effort; fall through to full resolution */ }
+  if (curBranch && curBranch === branchName) {
+    return { ok: true, branch: branchName, created: false, alreadyOnBranch: true, originalRef, originalRefType };
+  }
+
+  // (4b) Branch existence — check `refs/heads/<branch>` SPECIFICALLY. A bare
+  // `rev-parse --verify <branch>` DWIM-resolves a same-named tag or
+  // remote-tracking ref, which would make the plain `git checkout <branch>`
+  // below land on a NON-branch ref → a silent detached HEAD on the operator
+  // tree (exactly what the Step-2 preflight refuses). Verifying the fully
+  // qualified branch ref avoids that ambiguity.
   let branchExists = false;
   try {
-    await git(['rev-parse', '--verify', branchName], baseOpts);
+    await git(['rev-parse', '--verify', '--quiet', `refs/heads/${branchName}`], baseOpts);
     branchExists = true;
   } catch {
     branchExists = false;
   }
 
+  // (4c) Checkout with NO half-switch + partial-clone-aware failure surfacing.
+  // A `git checkout` can move HEAD and THEN fail materializing the tree (the
+  // GVFS auth-less blob-fetch case). If that happens on the EXISTING-branch
+  // path we best-effort switch HEAD back to the captured originalRef (PLAIN
+  // checkout, never --force — the tree was verified clean at Step 1, so there
+  // is nothing of the operator's to overwrite) so the operator tree is never
+  // stranded half-populated on the agent branch. A partial-clone/blob-fetch
+  // failure is returned as a typed { ok:false, reason:'blob-fetch' } result so
+  // the caller can refuse NON-retryably with operator-actionable guidance
+  // instead of retry-storming an identical structural failure; any OTHER error
+  // is rethrown (→ retryable LIVE_CHECKOUT_FAILED) since it may be transient.
+  const runCheckout = async (args, { creating }) => {
+    try {
+      await git(args, baseOpts);
+      return null; // success
+    } catch (checkoutErr) {
+      const msg = String((checkoutErr && checkoutErr.message) || '');
+      if (!creating && originalRef) {
+        // Undo any partial switch on the existing-branch path. (Creating a new
+        // branch off HEAD doesn't change the tree, so there's nothing to undo.)
+        try { await git(['checkout', originalRef], baseOpts); }
+        catch { /* best-effort — classification below still applies */ }
+      }
+      if (_isPartialCloneBlobError(msg)) {
+        return {
+          ok: false,
+          reason: 'blob-fetch',
+          op: creating ? 'create' : 'checkout',
+          branch: branchName,
+          message: msg.slice(0, 500),
+          originalRef,
+          originalRefType,
+        };
+      }
+      throw checkoutErr; // transient → caller retries (LIVE_CHECKOUT_FAILED)
+    }
+  };
+
   if (branchExists) {
     // Plain checkout — NO --force, NO -B, NO pull. Operator owns local commits.
-    await git(['checkout', branchName], baseOpts);
+    const failed = await runCheckout(['checkout', branchName], { creating: false });
+    if (failed) return failed;
     return { ok: true, branch: branchName, created: false, originalRef, originalRefType };
   }
 
@@ -241,7 +350,8 @@ async function prepareLiveCheckout(opts = {}) {
   // origin/<mainRef>: in live mode the operator's HEAD is the baseline, and
   // 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);
+  const failedCreate = await runCheckout(['checkout', '-b', branchName], { creating: true });
+  if (failedCreate) return failedCreate;
   return { ok: true, branch: branchName, created: true, originalRef, originalRefType };
 }
 
@@ -375,6 +485,52 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
       return result;
     }
 
+    // ── Self-healing dirty recovery (PL-live-checkout-reliability-hardening).
+    // If the tree is dirty AND HEAD is on the AGENT branch (branchName) AND that
+    // branch differs from originalRef, the dirt is provably AGENT-authored: the
+    // engine CREATED this branch and prepareLiveCheckout VERIFIED the tree clean
+    // before switching to it, so anything uncommitted here was produced by the
+    // agent (a crash mid-edit, an incomplete commit, untracked output). Commit
+    // it onto the AGENT branch so the plain `git checkout <originalRef>` below
+    // succeeds and the NEXT dispatch isn't wedged forever by LIVE_CHECKOUT_DIRTY
+    // (the operator's "no recovery from dirty checkout"). This NEVER touches the
+    // operator's branch, NEVER discards work (`git add -A` + commit is additive
+    // and fully recoverable — the WIP lands as a visible commit on the agent
+    // branch / its PR), NEVER resets/cleans/stashes, and is gated hard so it can
+    // only ever mutate the engine-created branch. Gitignored artifacts are not
+    // staged by `git add -A`, so a tree dirty only with ignored build output
+    // never reaches here (git status is empty → not dirty). Best-effort: a
+    // failed commit falls through to the plain checkout, which refuses and
+    // writes the existing manual-recovery alert — no worse than before.
+    if (branchName && branchName !== originalRef) {
+      let dirty = false;
+      try {
+        const statusRaw = await git(['status', '--porcelain'], baseOpts);
+        dirty = !!String(typeof statusRaw === 'string' ? statusRaw : '').trim();
+      } catch { /* best-effort — if we can't read status, skip the self-heal */ }
+      if (dirty) {
+        let onAgentBranch = false;
+        try {
+          const curRaw = await git(['rev-parse', '--abbrev-ref', 'HEAD'], baseOpts);
+          const cur = (typeof curRaw === 'string' ? curRaw : '').trim();
+          onAgentBranch = cur && cur === branchName;
+        } catch { /* best-effort */ }
+        if (onAgentBranch) {
+          try {
+            await git(['add', '-A'], baseOpts);
+            // --no-verify: skip operator commit hooks that may fail headless.
+            await git(['commit', '--no-verify', '-m', `minions: auto-save agent WIP (dispatch ${did})`], baseOpts);
+            result.autoCommitted = true;
+            logFn('info', `live-checkout: auto-committed agent WIP onto ${branchName} before restore (dispatch ${did})`);
+          } catch (commitErr) {
+            // Leave the tree as-is; the plain checkout below will refuse and the
+            // fallback alert fires. Never force, never discard.
+            logFn('warn', `live-checkout: could not auto-save agent WIP onto ${branchName} for ${did}: ${commitErr && commitErr.message}`);
+          }
+        }
+      }
+    }
+
     // PLAIN checkout — NO --force. git refuses if uncommitted changes would be
     // overwritten; that refusal is honored rather than clobbering the tree.
     try {
@@ -413,10 +569,100 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
     }
   } catch (restoreErr) {
     // Strictly best-effort — swallow so restore never alters the dispatch result.
+    // But unlike the inner `checkout-refused` path (which alerts), a failure
+    // HERE (git binary missing, repo corruption, a GVFS blob-fetch on the
+    // switch back, an unexpected throw) would otherwise leave the operator
+    // stranded on the agent branch with ZERO notification. Write the same
+    // deduped manual-recovery alert so the operator is never silently stranded.
     result.reason = 'error';
     logFn('warn', `live-checkout: restore hiccup for ${did}: ${restoreErr && restoreErr.message}`);
+    try {
+      const body = [
+        `Could not automatically switch ${proj} back to "${originalRef}" after a live-checkout`,
+        `dispatch — the restore hit an unexpected error (not a normal uncommitted-changes`,
+        `refusal). On a Scalar/GVFS partial clone this is often an auth-less blob fetch on`,
+        `the branch switch; your own (authenticated) checkout will succeed.`,
+        ``,
+        `Dispatch: ${did}`,
+        `Current branch: ${branchName}`,
+        `Working tree: ${localPath}`,
+        `Error: ${restoreErr && restoreErr.message}`,
+        ``,
+        `Your tree was left untouched (no force, no reset, no clean, no stash). Switch back`,
+        `manually when ready:`,
+        ``,
+        `    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-error alert for ${did}: ${e && e.message}`);
+    }
     return result;
   }
 }
 
-module.exports = { prepareLiveCheckout, restoreLiveCheckoutAtDispatchEnd };
+/**
+ * maybeRestoreLiveCheckoutFromRecord — PL-live-checkout-reliability-hardening
+ *
+ * Thin shared wrapper that fires restoreLiveCheckoutAtDispatchEnd from a
+ * persisted DISPATCH RECORD (not the in-memory spawn closure). A live-mode
+ * dispatch only ever persists `originalRef` (engine.js, P-c5a1f3b8), so its
+ * presence — together with `meta.branch` + `meta.project.localPath` — is the
+ * live-mode signal on every restart/reaping path where the slim persisted
+ * record is all that survives.
+ *
+ * This exists because the dispatch-end restore was originally wired in only TWO
+ * places: the in-memory `onAgentClose` closure (fresh spawns only) and the
+ * engine-restart orphan-COMPLETION path in cli.js (agent finished WHILE the
+ * engine was down). A live agent that SURVIVES a restart and exits LATER is
+ * re-attached with no `onAgentClose` closure and is reaped by `timeout.js`
+ * (completeFromOutput / orphan sweep) — which had NO restore wiring — so the
+ * operator's checkout was silently stranded on the agent branch. Routing all
+ * three reaping paths through this one helper closes that gap without forking a
+ * third inline copy.
+ *
+ * Best-effort and never throws: returns a result object, swallows the restore's
+ * own (already-swallowed) errors, and a no-op `{ skipped:true }` when the record
+ * isn't a live-mode dispatch. Callers should treat it as fire-and-forget.
+ *
+ * @param {object} opts
+ * @param {object} opts.item                 persisted dispatch record (has id, originalRef, meta.branch, meta.project.{localPath,name})
+ * @param {boolean} [opts.isTerminalFailure]  true on error/timeout/crash
+ * @param {string}  [opts.resultLabel]        short status word for the alert body
+ * @param {function} [opts.log]               (level, msg) => void
+ * @param {function} opts.writeInboxAlert     (slug, body) => any
+ * @param {object}  [opts.gitOpts]            execFile opts; defaults to gitEnv() + 30s timeout
+ * @param {function} [opts._git]              test seam forwarded to restoreLiveCheckoutAtDispatchEnd
+ * @returns {Promise<object>} restore result (or { skipped:true } for a non-live record)
+ */
+async function maybeRestoreLiveCheckoutFromRecord(opts = {}) {
+  const { item, isTerminalFailure, resultLabel, log, writeInboxAlert, gitOpts, _git } = opts;
+  if (!item || !item.originalRef || !item.meta?.branch || !item.meta?.project?.localPath) {
+    return { restored: false, reason: 'not-live-record', skipped: true };
+  }
+  try {
+    return await 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: !!isTerminalFailure,
+      resultLabel,
+      gitOpts: gitOpts || { env: shared.gitEnv(), windowsHide: true, timeout: 30000 },
+      log,
+      writeInboxAlert,
+      _git,
+    });
+  } catch (err) {
+    // restoreLiveCheckoutAtDispatchEnd already swallows its own errors; this is
+    // belt-and-suspenders so a require()/argument hiccup can never break the
+    // reaping path that called us.
+    if (typeof log === 'function') log('warn', `live-checkout: maybeRestoreLiveCheckoutFromRecord threw for ${item.id}: ${err && err.message}`);
+    return { restored: false, reason: 'error', skipped: false };
+  }
+}
+
+module.exports = { prepareLiveCheckout, restoreLiveCheckoutAtDispatchEnd, maybeRestoreLiveCheckoutFromRecord, _isPartialCloneBlobError };

package/engine/shared.js

@@ -2669,6 +2669,11 @@ const ENGINE_DEFAULTS = {
   agentTimeout: 18000000,  // 5h
   heartbeatTimeout: 300000, // 5min — stale-orphan grace after process tracking is lost
   resumeHeartbeatTimeout: 300000, // 5min — max wait for a resumed runtime to emit its first output
+  // M004 — minimum time a dispatch must have been alive before it can be declared
+  // orphaned. Prevents false-positive orphan declarations for short-duration agents
+  // (e.g. verify agents that complete naturally within ~18-19s before the engine's
+  // process tracking catches up). Configurable via config.engine.minAliveBeforeOrphanMs.
+  minAliveBeforeOrphanMs: 30000, // 30s
   // Per-type stale-orphan overrides (merged with config.engine.heartbeatTimeouts at runtime — see timeout.js).
   // Heavy work types (multi-file edits, builds, test suites, full verify cycles) routinely go quiet for
   // longer than the 5-min default when the engine has lost their tracked handle (e.g. across an engine
@@ -4335,6 +4340,7 @@ const FAILURE_CLASS = {
   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.
+  LIVE_CHECKOUT_BLOB_FETCH: 'live-checkout-blob-fetch', // PL-live-checkout-reliability-hardening (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because the tree could not be materialized — on a Scalar/GVFS-managed ADO partial (blobless) clone, switching onto a branch whose tree differs from HEAD hydrates the changed paths' blobs through the GVFS cache server (`*.gvfscache.dev.azure.com`), a different endpoint than the main git remote that receives NO auth in the headless engine shell, so the fetch fails DETERMINISTICALLY. Distinct from LIVE_CHECKOUT_FAILED (transient) because retrying reproduces it identically — surfaced once as an operator-actionable refusal instead of retry-storming to the cap. Non-retryable — the operator hydrates the branch once with their own credentials (`git checkout <branch>` interactively, or `scalar prefetch` / `git -C <repo> fetch`), then re-dispatches. The engine NEVER forces, resets, cleans, or stashes the operator tree, and best-effort switches HEAD back to the original ref so the tree is not stranded half-populated.
   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

@@ -607,6 +607,7 @@ function checkTimeouts(config) {
   const timeout = config.engine?.agentTimeout || ENGINE_DEFAULTS.agentTimeout;
   const defaultStaleOrphanTimeout = config.engine?.heartbeatTimeout || ENGINE_DEFAULTS.heartbeatTimeout;
   const runtimeResumeHeartbeatTimeout = config.engine?.resumeHeartbeatTimeout || ENGINE_DEFAULTS.resumeHeartbeatTimeout || defaultStaleOrphanTimeout;
+  const minAliveBeforeOrphanMs = config.engine?.minAliveBeforeOrphanMs ?? ENGINE_DEFAULTS.minAliveBeforeOrphanMs;
 
   // Optional per-type stale-orphan timeouts: merge ENGINE_DEFAULTS ← config overrides.
   const perTypeStaleOrphanTimeouts = { ...ENGINE_DEFAULTS.heartbeatTimeouts, ...(config.engine?.heartbeatTimeouts || {}) };
@@ -659,11 +660,30 @@ function checkTimeouts(config) {
         : null;
     } catch (e) { log('warn', 'completion summary gate: ' + e.message); }
 
+    const _completedAsError = completionDetection || !isSuccess;
     completeDispatch(item.id, completionDetection ? DISPATCH_RESULT.ERROR : (isSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR),
       completionDetection ? completionDetection.reason : (isSuccess ? 'Completed (detected from output)' : `Exited with code ${processExitCode} (detected from output)`),
       outputResultSummary,
       completionDetection ? { processWorkItemFailure: false } : {});
 
+    // PL-live-checkout-reliability-hardening — restore the operator's checkout
+    // for a live-mode dispatch that finished AFTER an engine restart. This path
+    // (output-detected completion of a re-attached process) has no in-memory
+    // onAgentClose closure, so without this the tree is stranded on the agent
+    // branch. originalRef's presence is the live-mode signal; the helper no-ops
+    // for non-live records. Fire-and-forget + best-effort.
+    if (item.originalRef && item.meta?.branch && item.meta?.project?.localPath) {
+      try {
+        require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
+          item,
+          isTerminalFailure: _completedAsError,
+          resultLabel: _completedAsError ? 'error' : 'success',
+          log: (lvl, msg) => log(lvl, msg),
+          writeInboxAlert: dispatch().writeInboxAlert,
+        }).catch(() => {});
+      } catch (e) { log('warn', 'live-checkout restore (output completion): ' + e.message); }
+    }
+
     // Run post-completion hooks via shared helper (async — fire and forget in timeout context).
     // Pass the actual exit code so autoRecovery (PR-created-but-failed) still works correctly.
     // detectPhantom: true mirrors the line 310 detectNonTerminalResultSummary call —
@@ -834,6 +854,17 @@ function checkTimeouts(config) {
     const confirmedDeadAtRestart = engineRestartGraceExempt?.has(item.id);
     const reattachedProcessEnded = !!procInfo?.reattached && !processAlive;
     const canReapDeadProcess = confirmedDeadAtRestart || reattachedProcessEnded;
+
+    // M004 — skip orphan declaration if the dispatch has not been alive long enough.
+    // Prevents false-positive orphans for short-duration agents (e.g. verify agents
+    // that complete naturally within ~18-19s before process tracking catches up).
+    // canReapDeadProcess (confirmed-dead at restart) bypasses this guard — those
+    // PIDs were explicitly verified dead at engine startup.
+    if (!canReapDeadProcess) {
+      const aliveMs = Date.now() - (item.started_at ? new Date(item.started_at).getTime() : 0);
+      if (aliveMs < minAliveBeforeOrphanMs) continue;
+    }
+
     if (!processAlive && (canReapDeadProcess || silentMs > staleOrphanTimeout) && (Date.now() > engineRestartGraceUntil || canReapDeadProcess)) {
       // Last-resort PID check: lost tracked handle but OS process may still be alive.
       if (isOsPidAliveForDispatch(item.id)) {
@@ -883,6 +914,21 @@ function checkTimeouts(config) {
   // Clean up dead items
   for (const { item, reason, failureClass } of deadItems) {
     completeDispatch(item.id, DISPATCH_RESULT.ERROR, reason, '', failureClass ? { failureClass } : {});
+    // PL-live-checkout-reliability-hardening — a live-mode dispatch declared an
+    // orphan (lost process handle, e.g. across an engine restart) leaves the
+    // operator checkout on the agent branch. Restore it from the persisted
+    // record (originalRef present ⇒ live mode). Always a terminal failure here.
+    if (item.originalRef && item.meta?.branch && item.meta?.project?.localPath) {
+      try {
+        require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
+          item,
+          isTerminalFailure: true,
+          resultLabel: 'orphaned',
+          log: (lvl, msg) => log(lvl, msg),
+          writeInboxAlert: dispatch().writeInboxAlert,
+        }).catch(() => {});
+      } catch (e) { log('warn', 'live-checkout restore (orphan): ' + e.message); }
+    }
   }
 
   // Clear legacy blocking-tool annotations; process liveness no longer depends on tool parsing.

package/engine.js

@@ -2382,13 +2382,22 @@ async function spawnAgent(dispatchItem, config) {
     if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'dirty') {
       const _dirtyFiles = Array.isArray(_liveResult.dirtyFiles) ? _liveResult.dirtyFiles : [];
       const _branchInfo = typeof _liveResult.branchInfo === 'string' ? _liveResult.branchInfo : '';
-      // #329: Check if this is a retry after a prior dirty failure. If the WI
-      // already carries `_pendingReason:'live_checkout_dirty'` from a previous
-      // dispatch, the dirty state is persistent (user-owned) and we mark it
-      // non-retryable. First-attempt dirty failures are retried once so a
-      // transient or engine-owned dirty state can clear before permanently
-      // failing the plan item.
-      const _alreadyDirtyFailed = dispatchItem.meta?.item?._pendingReason === 'live_checkout_dirty';
+      // #329 + PL-live-checkout-reliability-hardening: two-strike dirty guard.
+      // First dirty failure is retried once (a transient or engine-owned dirty
+      // state — e.g. an agent's own leftover WIP, which dispatch-end restore now
+      // auto-commits onto the agent branch — can clear before the next attempt);
+      // a SECOND consecutive dirty failure is persistent (operator-owned) and
+      // fails non-retryably. The strike memory lives on a DEDICATED counter
+      // `_liveCheckoutDirtyAttempts`, NOT on `_pendingReason`: `_pendingReason`
+      // is scrubbed both by the dispatch.js retry re-queue (partially fixed by
+      // #434) AND unconditionally by discovery (`delete item._pendingReason`
+      // before building the dispatch), so reading the strike count off it was
+      // always falsy on the retry → the guard never fired and dirty trees
+      // burned all maxRetries. The dedicated counter is touched ONLY here (on a
+      // dirty failure) and cleared on a successful prepareLiveCheckout below;
+      // neither discovery nor the retry re-queue clears it.
+      const _priorDirtyAttempts = Number(dispatchItem.meta?.item?._liveCheckoutDirtyAttempts) || 0;
+      const _alreadyDirtyFailed = _priorDirtyAttempts >= 1;
       const _alertBody = [
         '# Live-checkout refused: dirty worktree',
         '',
@@ -2419,7 +2428,11 @@ async function spawnAgent(dispatchItem, config) {
           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 = 'live_checkout_dirty';
+            if (wi) {
+              wi._pendingReason = 'live_checkout_dirty';
+              // Dedicated two-strike counter (survives discovery + retry scrubs).
+              wi._liveCheckoutDirtyAttempts = _priorDirtyAttempts + 1;
+            }
             return data;
           });
         }
@@ -2507,7 +2520,82 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // PL-live-checkout-reliability-hardening: partial-clone / GVFS blob-fetch
+    // refusal. The existing-branch `git checkout` could not materialize the tree
+    // because the operator's checkout is a Scalar/GVFS blobless partial clone and
+    // the on-demand blob hydration goes through the auth-less GVFS cache server
+    // (headless → denied). This is DETERMINISTIC (not transient), so it gets its
+    // own non-retryable FAILURE_CLASS instead of LIVE_CHECKOUT_FAILED's bounded
+    // retry-storm. prepareLiveCheckout already best-effort switched HEAD back to
+    // the operator's original ref, so the tree is not stranded half-populated.
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'blob-fetch') {
+      const _blobMsg = typeof _liveResult.message === 'string' ? _liveResult.message : '';
+      const _alertBody = [
+        '# Live-checkout blocked: could not hydrate branch (partial clone)',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**Branch:** ${branchName}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        `The engine could not switch \`${cwd}\` onto \`${branchName}\` because the working tree could not be materialized. On a Scalar/GVFS-managed ADO repo (blobless partial clone), switching onto a branch whose tree differs from HEAD hydrates the changed files' blobs through the GVFS cache server, which receives no credentials in the headless engine — so the checkout fails. Your tree was left on its original ref (the engine never forces, resets, or cleans it).`,
+        ...(_blobMsg ? ['', '```', _blobMsg, '```'] : []),
+        '',
+        '## Recovery',
+        '',
+        `Hydrate the branch once with your own credentials, then re-dispatch:`,
+        '',
+        '```',
+        `git -C "${cwd}" checkout ${branchName}   # or: scalar prefetch / git -C "${cwd}" fetch origin ${branchName}`,
+        `git -C "${cwd}" checkout -               # switch back`,
+        '```',
+        '',
+        'Alternatively, switch this project to `checkoutMode: "worktree"` (the default), which fetches against the authenticated git remote instead of relying on in-place GVFS hydration.',
+      ].join('\n');
+      try { writeInboxAlert(`live-checkout-blocked-${_wiIdForAlert}`, _alertBody); }
+      catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
+      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 = 'live_checkout_blob_fetch';
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      const _shortMsg = `live-checkout blocked: could not hydrate ${branchName} in ${cwd} (partial-clone blob fetch)`;
+      log('error', `spawnAgent: ${_shortMsg}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        _shortMsg.slice(0, 800),
+        'Live-checkout could not materialize the branch tree on a blobless partial clone (auth-less GVFS cache fetch, headless). Deterministic — operator must hydrate the branch with their own credentials (or use worktree mode), then re-dispatch.',
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_BLOB_FETCH, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
     log('info', `live-checkout: ${_liveResult.created ? 'created' : 'switched to'} branch ${branchName} in ${cwd} (in-place; no worktree)`);
+    // PL-live-checkout-reliability-hardening: a clean spawn clears the two-strike
+    // dirty counter so a project that was transiently dirty once isn't treated as
+    // second-strike on its next dirty encounter. Only write when the stamp is set.
+    if (dispatchItem.meta?.item?._liveCheckoutDirtyAttempts) {
+      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) delete wi._liveCheckoutDirtyAttempts;
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to clear dirty-attempt counter for ${id}: ${e.message}`); }
+    }
     // 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

package/package.json

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