@yemi33/minions 0.1.2341 → 0.1.2343

package/dashboard/js/settings.js

@@ -1112,6 +1112,7 @@ async function saveSettings() {
       autoReapOrphanWorktreeHolders: !!document.getElementById('set-autoReapOrphanWorktreeHolders')?.checked,
       liveCheckoutAutoStash: !!document.getElementById('set-liveCheckoutAutoStash')?.checked,
       liveCheckoutAutoReset: !!document.getElementById('set-liveCheckoutAutoReset')?.checked,
+      liveCheckoutAutoBaseRepair: !!document.getElementById('set-liveCheckoutAutoBaseRepair')?.checked,
       orphanHolderScanTimeoutMs: document.getElementById('set-orphanHolderScanTimeoutMs')?.value,
       statusProbeKillTimeoutMs: document.getElementById('set-statusProbeKillTimeoutMs')?.value,
       adoPollEnabled: document.getElementById('set-adoPollEnabled').checked,

package/docs/live-checkout-mode.md

@@ -125,6 +125,36 @@ Pool short-circuits live in `engine.js:1368` and `engine/cleanup.js`; both gate
 
 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.
 
+### 6. Refuse on stale non-main base when forking a new branch (W-mr3lunnq000o9f41)
+
+When a live-checkout dispatch needs a **new** branch, `git checkout -b <branch>` seeds it from the operator's **current HEAD** (issue #226 — live mode never fetches `origin/<mainRef>` to avoid auth-less GVFS blob fetches). That is safe only when HEAD is already on the project's base branch. If a human — or a prior dispatch — left the operator checkout sitting on some unrelated topic/feature branch, the new branch (and therefore its PR) would silently inherit **every commit already on that topic branch**. This is scope contamination baked into git history, not a stray uncommitted diff, so it survives the dirty-tree (Guarantee 2) and mid-operation (Guarantee 5) preflights, which only check for uncommitted changes / in-progress ops, never *"is HEAD on the expected base?"*. The motivating incident is ADO PR `!5411214`, which silently carried ~22 unrelated OCM files the PR author disavowed.
+
+Immediately before the new-branch `git checkout -b`, `prepareLiveCheckout` compares HEAD's branch against the intended base:
+
+- **The base is per-project, NOT a hardcoded `'main'`.** `spawnAgent` resolves `mainRef` via `shared.resolveMainBranch(cwd, project.mainBranch)` (`engine.js`), which honors the project's configured `mainBranch`, else auto-detects `refs/remotes/origin/HEAD`, else falls back to `main`. Repos whose default branch is **not** `main` — e.g. Office Android development, whose harness (`claude.md`) documents a `lkg/main/android` base — are handled by setting `project.mainBranch: "lkg/main/android"` (or by having `origin/HEAD` point at it); the guard then keys on that branch. The word "main" in this guarantee is shorthand for *"the project's resolved base branch,"* never the literal string.
+- **HEAD already on `mainRef`** → forks normally; the guard never probes the base ref.
+- **HEAD off-base, local `refs/heads/<mainRef>` exists** → PLAIN `git checkout <mainRef>` (no fetch, no reset, no `--force` — the tree was verified clean at Guarantee 2), then forks off it. No auth-less GVFS blob fetch is forced in the common case.
+- **HEAD off-base, no usable local `mainRef`** (fresh-clone edge case) — or the local checkout itself fails — → **fail closed** with `{ ok:false, reason:'wrong-base' }` **unless auto-base-repair is enabled (see §6a).** The caller refuses **non-retryably** with `FAILURE_CLASS.LIVE_CHECKOUT_WRONG_BASE` (`'live-checkout-wrong-base'`; added to `engine/dispatch.js`'s neverRetry set), writes an inbox alert naming the off-base HEAD, the expected base, and the exact `git checkout <mainRef>` recovery command, and stamps the work item `_pendingReason`. This mirrors the dirty / mid-operation philosophy of refusing on ambiguous operator state rather than silently forking off the wrong base.
+
+#### 6a. Opt-in auto-base-repair (`liveCheckoutAutoBaseRepair`, W-mr3lunnq000o9f41)
+
+The fail-closed refusal above is safe but forces a manual `git checkout <mainRef>` before every re-dispatch. Enabling **`liveCheckoutAutoBaseRepair`** (per-project `project.liveCheckoutAutoBaseRepair` > fleet-wide `engine.liveCheckoutAutoBaseRepair` > **`false`**, resolved by `shared.resolveLiveCheckoutAutoBaseRepair`) lets the engine self-heal the *missing-local-base* case:
+
+- When HEAD is off-base **and** there is no local `refs/heads/<mainRef>` **but** a `refs/remotes/origin/<mainRef>` remote-tracking ref exists, the guard materializes a local base branch from it — `git branch --no-track <mainRef> refs/remotes/origin/<mainRef>` — then proceeds exactly like the local-base path (plain `git checkout <mainRef>`, then fork).
+- **Issue #226 is preserved:** `origin/<mainRef>` is consumed as a **local ref** — there is **no `git fetch`**. `origin/<mainRef>` is the *correct* project base, so there is **no scope-contamination risk** (the entire point of Guarantee 6 survives — it never forks off the stale topic HEAD).
+- **Bounded, degrades safely:** the subsequent `git checkout <mainRef>` may hydrate blobs on a partial clone (the one operation issue #226 flagged as hang-prone in headless sessions). It is bounded by the git-wrapper timeout; on failure/hang it falls through to the **same** fail-closed `wrong-base` refusal — strictly no worse than the non-repair path.
+- **Still fail-closed** when neither a local base nor an `origin/<mainRef>` tracking ref exists, or when the base checkout itself fails. Default **OFF**.
+
+Enable it fleet-wide via **Settings → "Live-checkout auto-base-repair (fleet-wide)"**, or in `config.json`:
+
+```jsonc
+{ "engine": { "liveCheckoutAutoBaseRepair": true } }        // fleet-wide
+// or per-project (wins over fleet-wide):
+{ "projects": [ { "name": "office", "checkoutMode": "live", "liveCheckoutAutoBaseRepair": true } ] }
+```
+
+**Legitimate continuations are exempt.** PR-targeted fixes and shared-branch plans intentionally continue a non-base branch. `spawnAgent` passes `allowNonMainBase` (derived from `meta.useExistingBranch || meta.branchStrategy === 'shared-branch'` — the same signal it already uses to distinguish fresh forks from continuations), which bypasses the guard entirely. The existing-branch path is also untouched: continuing existing work is still a plain checkout with no rebase/pull.
+
 ## 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 **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-…`.)

package/engine/ado.js

@@ -1584,7 +1584,12 @@ async function pollPrStatus(config) {
       newReviewStatus = REVIEW_STATUS.APPROVED;
       // Re-approve: ADO resets votes when target branch (master) advances, even though
       // the source branch is unchanged. Re-apply the approval vote via API.
-      if (!votes.some(v => v >= 5) && sourceCommit && pr._adoSourceCommit === sourceCommit) {
+      // Gated by autoApplyReviewVote (default OFF): re-casting a +10 vote is a
+      // POSITIVE platform mutation, so when the operator has "Auto-apply review
+      // vote to PR" disabled the engine must NOT touch the platform vote — the
+      // local reviewStatus stays 'approved' (informational) but no +10 is PUT.
+      const autoApplyReviewVote = config?.engine?.autoApplyReviewVote ?? shared.ENGINE_DEFAULTS.autoApplyReviewVote;
+      if (autoApplyReviewVote && !votes.some(v => v >= 5) && sourceCommit && pr._adoSourceCommit === sourceCommit) {
         try {
           const identityData = await adoFetch(`${orgBase}/_apis/connectionData?api-version=7.1`, token).catch(() => null);
           const myId = identityData?.authenticatedUser?.id;

package/engine/dispatch.js

@@ -749,6 +749,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       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.LIVE_CHECKOUT_WORKTREE_CONFLICT, // W-mr28h2j2000y0de1 — live-checkout `git checkout <existing-branch>` failed because that branch is already checked out in another worktree; structural conflict, so mechanical retry just reproduces it (operator must `git worktree remove` the other tree or finish its WIP, then re-dispatch)
+      FAILURE_CLASS.LIVE_CHECKOUT_WRONG_BASE, // W-mr3lunnq000o9f41 — live-checkout refused to fork a new branch because the operator HEAD is on an unrelated branch (not the project base) and no local base ref was usable; forking off it would bake that branch's commits into the new PR (scope contamination). Deterministic — mechanical retry reproduces it (operator must `git checkout <mainRef>`, 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/lifecycle.js

@@ -2410,19 +2410,20 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
   // never claim approved if some OTHER reviewer (human, different minion
   // account) still has a negative vote/review on the PR.
   //
-  // P-f7splitgate — split the gate into two predicates:
-  //   * canDismissOwnPriorNegative: dismissal of the engine's own previously-posted
-  //     REQUEST_CHANGES on a verdict flip to APPROVE runs UNCONDITIONALLY. This is
-  //     correctness (cleaning up our own stale state), not policy, so it must NOT
-  //     be gated by autoApplyReviewVote.
-  //   * autoApplyVote: continues to gate POSITIVE auto-actions — mirroring the
-  //     live platform status into local reviewStatus below (which can promote the
-  //     PR to 'approved' based on platform-side votes).
+  // P-f7splitgate / W-mpea9fyb0010febf — autoApplyReviewVote gates ALL engine
+  // platform vote mutations. When the operator has "Auto-apply review vote to
+  // PR" disabled (default), the engine records the verdict in local reviewStatus
+  // (informational) but MUST NOT touch the platform vote/review in any way —
+  // neither the POSITIVE mirror below (promoting local status from live votes)
+  // NOR the negative-correction reconcile here (dismissing the engine's own
+  // prior REQUEST_CHANGES / re-casting an ADO +10 on a verdict flip to APPROVE).
+  // Re-casting/clearing a platform vote is exactly the "casting votes
+  // unexpectedly" behavior the gate exists to suppress, so it is now gated too.
   const prevReviewStatus = reviewPr?.reviewStatus || '';
   const wasNegative = prevReviewStatus === REVIEW_STATUS.CHANGES_REQUESTED || prevReviewStatus === REVIEW_STATUS.WAITING
     || liveStatus === REVIEW_STATUS.CHANGES_REQUESTED || liveStatus === REVIEW_STATUS.WAITING;
   const autoApplyVote = config?.engine?.autoApplyReviewVote ?? ENGINE_DEFAULTS.autoApplyReviewVote;
-  const canDismissOwnPriorNegative = verdictRaw === REVIEW_STATUS.APPROVED && !isSelfReview && wasNegative && projectObjForChecks;
+  const canDismissOwnPriorNegative = autoApplyVote && verdictRaw === REVIEW_STATUS.APPROVED && !isSelfReview && wasNegative && projectObjForChecks;
   if (canDismissOwnPriorNegative) {
     try {
       const reconcileFn = hostForChecks === 'github'
@@ -2471,8 +2472,69 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
     }
   }
 
+  // W-mr9sy3j700076967 — a review dispatch can report success (type:"result",
+  // no crash) yet never actually post a VERDICT: comment on the PR (silent
+  // early-exit, budget exhaustion, model refusal, etc.). Before this guard,
+  // the code below unconditionally stamped `lastReviewedAt` + `minionsReview`
+  // as if the review were resolved. `lastReviewedAt` feeds the `alreadyReviewed`
+  // gate in engine.js (`pr.lastPushedAt <= pr.lastReviewedAt`), so that phantom
+  // stamp permanently blocked the engine from ever re-dispatching a review —
+  // reviewStatus stayed "pending" forever with no path back to a real review.
+  // Detect that case and (a) do NOT set lastReviewedAt so the existing
+  // needsReview gate naturally re-fires a fresh review next tick (bounded by
+  // maxReviewVerdictMissingRetries below), and (b) flag the PR + fire an inbox
+  // alert instead of silently recording minionsReview as if it succeeded.
+  const bailoutOutput = isReviewBailout(resultSummary);
+  const verdictMissing = !postReviewStatus && !verdictRaw && !bailoutOutput;
+
   let updatedTarget = null;
   const reviewNote = String(resultSummary || '').trim();
+
+  if (verdictMissing) {
+    const maxMissingRetries = config?.engine?.maxReviewVerdictMissingRetries ?? ENGINE_DEFAULTS.maxReviewVerdictMissingRetries;
+    let missingCount = 0;
+    let retriesExhausted = false;
+    shared.mutateJsonFileLocked(prPath, (prs) => {
+      if (!Array.isArray(prs)) return prs;
+      const target = shared.findPrRecord(prs, reviewPr, reviewProject);
+      if (!target) return prs;
+      missingCount = (target._reviewVerdictMissingCount || 0) + 1;
+      retriesExhausted = missingCount >= maxMissingRetries;
+      target._reviewVerdictMissingCount = missingCount;
+      target._reviewVerdictMissing = true;
+      target._reviewVerdictMissingAt = ts();
+      target._lastReviewAttempt = {
+        reviewer: reviewerName,
+        attemptedAt: ts(),
+        dispatchId: dispatchItem?.id || structuredCompletion?.dispatchId || null,
+        note: reviewNote,
+      };
+      // Only lock the PR out of re-review (via lastReviewedAt) once the bounded
+      // retry budget is exhausted — otherwise leave it unset so the engine's
+      // normal needsReview gate re-dispatches a fresh review next tick.
+      if (retriesExhausted) target.lastReviewedAt = ts();
+      return prs;
+    }, { defaultValue: [] });
+
+    const reason = `Review dispatch for ${reviewPr.id} completed without posting a VERDICT: comment ` +
+      `(reviewer: ${reviewerName}, dispatch: ${dispatchItem?.id || structuredCompletion?.dispatchId || '(unknown)'}). ` +
+      `reviewStatus left at "pending" instead of being silently recorded as resolved. ` +
+      `Attempt ${missingCount}/${maxMissingRetries}` +
+      (retriesExhausted
+        ? ' — retry budget exhausted; PR flagged (_reviewVerdictMissing) for human follow-up.'
+        : ' — the engine will re-dispatch a fresh review on the next eligible tick.');
+    log('warn', reason);
+    shared.writeToInbox('engine', `review-verdict-missing-${reviewPr.id}`,
+      `# Review completed without a verdict: ${reviewPr.id}\n\n` +
+      `**Reviewer:** ${reviewerName}\n` +
+      `**PR:** ${reviewPr.id}\n\n` +
+      `${reason}\n` +
+      (reviewNote ? `\n## Agent summary\n${reviewNote}\n` : ''),
+      null,
+      { sourceItem: reviewPr.id, reason: 'review-verdict-missing' });
+    return;
+  }
+
   shared.mutateJsonFileLocked(prPath, (prs) => {
     if (!Array.isArray(prs)) return prs;
     const target = shared.findPrRecord(prs, reviewPr, reviewProject);
@@ -2486,6 +2548,11 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
       }
     }
     target.lastReviewedAt = ts();
+    // A verdict landed cleanly this time — clear any stale missing-verdict flag.
+    delete target._reviewVerdictMissing;
+    delete target._reviewVerdictMissingCount;
+    delete target._reviewVerdictMissingAt;
+    delete target._lastReviewAttempt;
     // W-mpg58wv3 — best-effort capture of thread ids the review cited. Used
     // downstream by buildPrDispatch when spawning the review-feedback fix WI
     // (meta.addresses_threads) so the closure-loop reaper can correlate. Accept
@@ -6691,10 +6758,26 @@ function collapseAllDuplicatePrRecords(config) {
 // meta.liveValidationFor === codingWiId AND meta.liveValidationType === type
 // blocks a second dispatch of that specific type, so multiple configured
 // types don't collide or skip each other.
+//
+// W-mr9u39az000db5c2 — guard against a self-referential recursive cascade.
+// When liveValidation.type overlaps with a coding WI's own type set (e.g.
+// ["test","verify","setup"] configured on a project that ALSO dispatches
+// "setup"/"test"/"fix" coding work), a completed validation WI (type
+// "setup") is itself a WI whose type is in liveValidation.type. The old
+// item.type-only filter let that validation WI's own completion re-trigger
+// this hook and spawn ANOTHER validation WI (title-prefixed "Validate:
+// Validate: ..."), repeating indefinitely. Any WI that was itself created
+// as a liveValidation follow-up (tagged via meta.liveValidationFor at
+// creation, below) must never re-trigger this hook, regardless of its type.
 function autoDispatchLiveValidationWi(meta, config) {
   const item = meta?.item;
   if (!item?.id || !item?.type) return;
 
+  // Never re-trigger off the completion of a WI that was itself auto-created
+  // as a live-validation follow-up — that's what causes the infinite
+  // "Validate: Validate: ..." cascade (W-mr9u39az000db5c2 / issue #708).
+  if (item.meta && item.meta.liveValidationFor) return;
+
   const projectName = meta?.project?.name;
   if (!projectName) return;
 
@@ -6752,9 +6835,19 @@ function autoDispatchLiveValidationWi(meta, config) {
           continue;
         }
 
+        const proposedTitle = 'Validate: ' + (item.title || codingWiId);
+        // Defense-in-depth (belt-and-suspenders alongside the meta.liveValidationFor
+        // guard above): never create a doubly-nested "Validate: Validate: ..."
+        // title even if some future caller manages to invoke this function
+        // directly on an already-validation-tagged item.
+        if (/^Validate:\s*Validate:/.test(proposedTitle)) {
+          log('warn', `liveValidation: refusing to create nested "Validate: Validate:" WI for ${codingWiId} (type=${validationType})`);
+          continue;
+        }
+
         const validationWi = {
           id: 'W-' + shared.uid(),
-          title: 'Validate: ' + (item.title || codingWiId),
+          title: proposedTitle,
           type: validationType,
           status: WI_STATUS.PENDING,
           depends_on: [codingWiId],

package/engine/live-checkout.js

@@ -39,13 +39,25 @@
  *           NO fast-forward, NO reset). The operator owns the checkout
  *           state per the live-checkout contract; the engine never
  *           overwrites local commits.
- *        b. rev-parse fails → branch is new → `git checkout -b <branchName>`
- *           created from the CURRENT HEAD (NOT origin/<mainRef>). In live
- *           mode the operator's checked-out HEAD IS the baseline; branching
- *           off origin/<mainRef> forces on-demand blob fetching on blobless
- *           partial clones (Scalar/GVFS-managed ADO repos), which fails in
- *           headless mode because the GVFS cache server receives no auth and
- *           credential.helper is disabled. See issue #226.
+ *        b. rev-parse fails → branch is new → fork it. STALE-BASE GUARD
+ *           (W-mr3lunnq000o9f41) runs first, UNLESS `allowNonMainBase` is set
+ *           (PR-targeted fixes / shared-branch continuations opt out — they
+ *           intend to keep building on a non-main branch): if HEAD's branch is
+ *           NOT the project base (`mainRef`), forking off it would silently bake
+ *           every commit already on that branch into the new branch and its PR
+ *           (the ADO PR 5411214 scope-contamination incident — survives the
+ *           dirty/mid-operation preflights because it is committed history, not
+ *           an uncommitted diff). Recovery is LOCAL-ONLY (preserves issue #226's
+ *           no-forced-fetch guarantee): if `refs/heads/<mainRef>` exists locally,
+ *           PLAIN-checkout it (no fetch/reset/--force) and fork off it; else
+ *           FAIL CLOSED with { ok:false, reason:'wrong-base' }. When HEAD is
+ *           already on `mainRef` (or the guard is bypassed) →
+ *           `git checkout -b <branchName>` from the CURRENT HEAD (NOT
+ *           origin/<mainRef>). In live mode the operator's checked-out HEAD IS
+ *           the baseline; branching off origin/<mainRef> forces on-demand blob
+ *           fetching on blobless partial clones (Scalar/GVFS-managed ADO repos),
+ *           which fails in headless mode because the GVFS cache server receives
+ *           no auth and credential.helper is disabled. See issue #226.
  *   5. Returns { ok:true, branch, created:boolean, originalRef, originalRefType }.
  *
  * RETURN SHAPES:
@@ -53,6 +65,16 @@
  *   { ok:false, reason:'dirty',         dirtyFiles:[…] }
  *   { ok:false, reason:'mid-operation', op:'merge'|'rebase'|'cherry-pick'|'revert', details }
  *   { ok:false, reason:'detached-head', sha }
+ *   { ok:false, reason:'wrong-base',    headBranch, expectedBase, localMainExists, [switchError], originalRef, originalRefType }
+ *     (W-mr3lunnq000o9f41) — a NEW-branch fork was requested but the operator's
+ *     HEAD is on `headBranch`, not the project base `expectedBase` (=mainRef),
+ *     and no local base ref could be switched to (localMainExists:false → no
+ *     `refs/heads/<mainRef>`; or localMainExists:true + `switchError` → the local
+ *     checkout itself failed). Non-retryable at the caller — a human must
+ *     `git checkout <expectedBase>` before re-dispatch so the new branch forks
+ *     off the intended baseline instead of inheriting `headBranch`'s commits.
+ *     Suppressed entirely when the caller passes `allowNonMainBase:true`
+ *     (PR-targeted / shared-branch continuations).
  *   { ok:false, reason:'blob-fetch',        op, branch, message, originalRef, originalRefType }
  *   { ok:false, reason:'worktree-conflict', op, branch, conflictingWorktreePath, message, originalRef, originalRefType }
  *     (W-mr28h2j2000y0de1) — the target branch is already checked out in another
@@ -320,6 +342,26 @@ function _defaultResolveAutoReset(localPath) {
   }
 }
 
+// W-mr3lunnq000o9f41 — production default for resolving the live-checkout
+// auto-base-repair decision when the caller (engine.js spawnAgent) does not pass
+// an explicit `autoBaseRepair` boolean. Mirrors `_defaultResolveAutoReset`:
+// self-resolve from config.json by matching the project on `localPath`, defer to
+// `shared.resolveLiveCheckoutAutoBaseRepair`. Runs only on the wrong-base recovery
+// path (cold, not hot). Fails CLOSED — any config read error returns false so a
+// glitch can never silently widen the base-recovery surface.
+function _defaultResolveAutoBaseRepair(localPath) {
+  try {
+    const config = shared.safeJson(path.join(shared.MINIONS_DIR, 'config.json')) || {};
+    const projects = shared.getProjects(config);
+    const norm = (p) => path.resolve(String(p || '')).replace(/\\/g, '/').toLowerCase();
+    const target = norm(localPath);
+    const project = projects.find((p) => p && p.localPath && norm(p.localPath) === target) || null;
+    return shared.resolveLiveCheckoutAutoBaseRepair(project, config.engine);
+  } catch {
+    return false;
+  }
+}
+
 // W-mqvejug6000eeb20 — production default inbox-note writer for the auto-reset
 // audit trail. Lazily required to avoid a load-order cycle (dispatch.js does not
 // require live-checkout.js, but the lazy require keeps this module importable in
@@ -338,14 +380,25 @@ async function prepareLiveCheckout(opts = {}) {
     dispatchId, // accepted for caller bookkeeping; not used by the helper
     wiId,       // accepted for caller bookkeeping; used in the auto-reset note slug
     skipDirtyCheck,  // #522: opt-out for GVFS repos where git status output exceeds maxBuffer
+    allowNonMainBase, // W-mr3lunnq000o9f41: opt a dispatch OUT of the stale-base
+                      // guard below. PR-targeted fixes and shared-branch
+                      // continuations INTEND to keep building on a non-main
+                      // branch; the caller (spawnAgent) sets this true for them.
+                      // Undefined/false → the fresh-branch base guard is active.
     log,
     autoReset,  // W-mqvejug6000eeb20: tri-state. `true`/`false` short-circuits the
                 // config-based resolution; `undefined` (the engine.js call shape)
                 // defers to `_resolveAutoReset`.
+    autoBaseRepair,  // W-mr3lunnq000o9f41: tri-state. `true`/`false` short-circuits
+                     // config resolution; `undefined` (the engine.js call shape)
+                     // defers to `_resolveAutoBaseRepair`. When enabled, the
+                     // wrong-base recovery may materialize a local base branch from
+                     // `refs/remotes/origin/<mainRef>` (no fetch) instead of failing.
     _git,       // private injection for testing — defaults to shared.shellSafeGit
     _exists,    // private injection for testing — defaults to fs.existsSync
     _rm,        // private injection for testing — defaults to fs.rmSync (recursive, force)
     _resolveAutoReset, // private injection for testing — defaults to config-based resolver
+    _resolveAutoBaseRepair, // private injection for testing — defaults to config-based resolver
     _writeInboxNote,   // private injection for testing — defaults to dispatch.writeInboxAlert
     _sleep,            // private injection for testing — defaults to a real setTimeout-based sleep
   } = opts;
@@ -755,10 +808,151 @@ async function prepareLiveCheckout(opts = {}) {
     return { ok: true, branch: branchName, created: false, originalRef, originalRefType };
   }
 
-  // New branch — create from the current HEAD (issue #226). NOT
-  // 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.
+  // New branch — but FIRST guard against forking off a STALE non-main HEAD.
+  //
+  // ── (4d) STALE-BASE GUARD (W-mr3lunnq000o9f41). ───────────────────────
+  // The branch does not exist locally, so we are about to FORK A NEW branch.
+  // `git checkout -b <branch>` seeds it from the CURRENT HEAD (issue #226 — we
+  // never fetch origin/<mainRef> in live mode). That is safe ONLY when HEAD is
+  // already on the project's base branch. If a human (or a prior dispatch) left
+  // the operator checkout sitting on some unrelated topic/feature branch, the
+  // new branch — and therefore its PR — would SILENTLY inherit every commit
+  // already on that topic branch. That is scope contamination baked into git
+  // history, not a stray uncommitted diff, so it survives the dirty-tree and
+  // mid-operation preflights above (which only check for uncommitted changes and
+  // in-progress operations, never "is HEAD on the expected base?"). This is a
+  // real, observed incident: ADO PR 5411214 silently carried ~22 unrelated OCM
+  // files that the PR author disavowed.
+  //
+  // `allowNonMainBase` opts a dispatch OUT of the guard: PR-targeted fixes and
+  // shared-branch continuations INTEND to keep building on a non-main branch, so
+  // the caller passes it for those legitimate continuations. For a plain
+  // fresh-branch dispatch the guard is active.
+  //
+  // Recovery is LOCAL-ONLY to preserve issue #226's no-forced-fetch guarantee:
+  // if a local `refs/heads/<mainRef>` already exists we PLAIN-checkout it (no
+  // fetch, no reset, no --force — the tree was verified clean at Step 1) and
+  // fork off it. If no local mainRef ref is resolvable we normally FAIL CLOSED
+  // with { ok:false, reason:'wrong-base' } — mirroring the dirty/mid-operation
+  // philosophy of refusing on ambiguous operator state rather than silently
+  // forking off the wrong base.
+  //
+  // ── (4d-repair) OPT-IN AUTO-BASE-REPAIR (W-mr3lunnq000o9f41). ──────────
+  // When `autoBaseRepair` is enabled AND no local base branch exists, we fall
+  // back to the `refs/remotes/origin/<mainRef>` remote-tracking ref — a purely
+  // LOCAL ref (NO `git fetch`, so issue #226 is preserved) that points at the
+  // CORRECT project base. We materialize a local `<mainRef>` from it (a plain
+  // ref op) and proceed exactly like the local-main path. origin/<mainRef> IS
+  // the base, so there is NO scope contamination (the whole point of this guard
+  // survives). The subsequent `git checkout <mainRef>` may hydrate blobs on a
+  // partial clone; that is bounded by the git wrapper timeout and, on failure,
+  // falls through to the SAME fail-closed wrong-base refusal (strictly no worse
+  // than the non-repair path). Opt-in because the checkout hydration is the one
+  // operation issue #226 flagged as hang-prone in headless sessions.
+  if (!allowNonMainBase) {
+    // HEAD's branch — captured at Step 3 as originalRef (symbolic-ref --short
+    // HEAD) when originalRefType is 'branch'; fall back to the abbrev-ref read
+    // at Step 4a. Detached HEAD was already refused at Step 2, so on this path
+    // originalRefType is normally 'branch'.
+    const headBranch = (originalRefType === 'branch' && originalRef)
+      ? originalRef
+      : (curBranch || '');
+    if (headBranch !== mainRef) {
+      let localMainExists = false;
+      try {
+        await git(['rev-parse', '--verify', '--quiet', `refs/heads/${mainRef}`], baseOpts);
+        localMainExists = true;
+      } catch {
+        localMainExists = false;
+      }
+
+      if (!localMainExists) {
+        // Resolve the opt-in auto-base-repair decision (explicit boolean wins;
+        // else config-based resolver; else fail closed as before).
+        let wantBaseRepair = false;
+        if (typeof autoBaseRepair === 'boolean') {
+          wantBaseRepair = autoBaseRepair;
+        } else {
+          const resolver = (typeof _resolveAutoBaseRepair === 'function') ? _resolveAutoBaseRepair : _defaultResolveAutoBaseRepair;
+          try { wantBaseRepair = !!resolver(localPath); } catch { wantBaseRepair = false; }
+        }
+
+        let originMainExists = false;
+        if (wantBaseRepair) {
+          try {
+            await git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${mainRef}`], baseOpts);
+            originMainExists = true;
+          } catch {
+            originMainExists = false;
+          }
+        }
+
+        if (!wantBaseRepair || !originMainExists) {
+          return {
+            ok: false,
+            reason: 'wrong-base',
+            headBranch,
+            expectedBase: mainRef,
+            localMainExists: false,
+            autoBaseRepair: !!wantBaseRepair,
+            originMainExists,
+            originalRef,
+            originalRefType,
+          };
+        }
+
+        // Materialize a local <mainRef> from the remote-tracking ref. This is a
+        // pure ref op (NO fetch, NO checkout, NO hydration). --no-track keeps it
+        // a plain local branch. localMainExists then flows into the shared
+        // checkout below, so the hydration cost is identical to the ordinary
+        // local-main path.
+        try {
+          await git(['branch', '--no-track', mainRef, `refs/remotes/origin/${mainRef}`], baseOpts);
+          localMainExists = true;
+          logFn('info',
+            `live-checkout auto-base-repair: no local '${mainRef}' — created it from 'origin/${mainRef}' (no fetch, issue #226 preserved) to recover base for forking '${branchName}'`);
+        } catch (repairErr) {
+          return {
+            ok: false,
+            reason: 'wrong-base',
+            headBranch,
+            expectedBase: mainRef,
+            localMainExists: false,
+            autoBaseRepair: true,
+            originMainExists: true,
+            baseRepairError: String((repairErr && repairErr.message) || '').slice(0, 500),
+            originalRef,
+            originalRefType,
+          };
+        }
+      }
+
+      // Local mainRef ref now exists (either originally, or just materialized
+      // from origin/<mainRef> by auto-base-repair) — switch to it using purely
+      // LOCAL refs (NO fetch, NO --force), then fork the new branch off it below.
+      try {
+        await git(['checkout', mainRef], baseOpts);
+      } catch (switchErr) {
+        return {
+          ok: false,
+          reason: 'wrong-base',
+          headBranch,
+          expectedBase: mainRef,
+          localMainExists: true,
+          switchError: String((switchErr && switchErr.message) || '').slice(0, 500),
+          originalRef,
+          originalRefType,
+        };
+      }
+      logFn('info',
+        `live-checkout: HEAD was on '${headBranch}' (not base '${mainRef}') — switched to local '${mainRef}' before forking '${branchName}' (no fetch, issue #226 preserved)`);
+    }
+  }
+
+  // Create from HEAD — now guaranteed to be the project base branch unless
+  // allowNonMainBase bypassed the guard. NOT 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.
   const failedCreate = await runCheckout(['checkout', '-b', branchName], { creating: true });
   if (failedCreate) return failedCreate;
   return { ok: true, branch: branchName, created: true, originalRef, originalRefType };

package/engine/playbook.js

@@ -110,7 +110,7 @@ function getPrFetchInstructions(project) {
     `If \`az\` is unavailable, fall back to the ADO REST API: get a token with \`az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv\` and \`GET .../_apis/git/repositories/<repoId>/pullrequests/<number>?api-version=7.1\` (Bearer auth). Do not use \`gh\` for Azure DevOps repositories.`;
 }
 
-function getPrVoteInstructions(project) {
+function getPrVoteInstructions(project, config) {
   const host = getRepoHost(project);
   const repoId = project?.repositoryId || '';
   if (host === 'github') {
@@ -131,7 +131,20 @@ function getPrVoteInstructions(project) {
       `When you author the summary body, append the collapsible **"Harnesses used"** \`<details>\` section described in the shared rules (mirror of your \`harnessUsed\` completion field) so reviewers see which skills / MCPs / docs informed the change; omit it when you used none.\n\n` +
       `**Brand link:** whenever the body names "Minions" (e.g. the \`Reviewed by Minions (…)\` sign-off), render it as \`[Minions](${MINIONS_BRAND_URL})\` per the shared rules. On the GitHub path the engine also auto-links the first bare \`… by Minions\` trailer as a backstop (\`engine/comment-format.js#linkifyBrandTrailer\`), but write the link yourself so the first occurrence is correct.`;
   }
-  // Azure DevOps — prefer `az` CLI first, ADO REST API as fallback
+  // Azure DevOps — prefer `az` CLI first, ADO REST API as fallback.
+  // The platform reviewer vote is a POSITIVE mutation gated by autoApplyReviewVote
+  // ("Auto-apply review vote to PR", default OFF). When disabled, agents must NOT
+  // cast a platform vote — they post the verdict as a comment only (parity with
+  // GitHub, where self-approval is blocked). This is what keeps the toggle in
+  // full control of whether Minions ever cast votes on PRs.
+  const autoApplyReviewVote = config?.engine?.autoApplyReviewVote ?? ENGINE_DEFAULTS.autoApplyReviewVote;
+  if (!autoApplyReviewVote) {
+    return `**Do NOT cast a platform reviewer vote.** The operator has "Auto-apply review vote to PR" disabled, so Minions record verdicts as comments only — the human casts the final vote. Do NOT run \`az repos pr set-vote\` or PUT a reviewer vote via the REST API.\n\n` +
+      `Post your verdict as a thread comment. **Preferred:** \`minions pr comment <number> --host ado --ado-org ${getProjectOrg(project)} --ado-project ${project?.adoProject || '<ado-project>'} --repo-id ${repoId || '<repo-id>'} --agent <your-agent-id> --kind review-decision [--wi <work-item-id>] --body-file <verdict.md>\` (applies the marker + harness section + brand link for you). Fallback: \`az repos pr comment create --pull-request-id <number> --content @<verdict.md>\`\n\n` +
+      `The verdict body file's first non-marker line MUST be \`VERDICT: APPROVE\` or \`VERDICT: REQUEST_CHANGES\` — the engine parses this to record your verdict in local state.\n\n` +
+      `When you author the comment body, append the collapsible **"Harnesses used"** \`<details>\` section described in the shared rules (mirror of your \`harnessUsed\` completion field); omit it when you used none.\n\n` +
+      `**Brand link:** whenever the body names "Minions" (e.g. the \`Reviewed by Minions (…)\` sign-off), render it as \`Reviewed by [Minions](${MINIONS_BRAND_URL}) (…)\` per the shared rules. \`minions pr comment --host ado\` auto-links the first bare \`… by Minions\` trailer for you; the raw \`az repos pr comment\` fallback does NOT, so if you use it you MUST link it yourself.`;
+  }
   return `For Azure DevOps, use the \`az\` CLI first to set your reviewer vote:\n` +
     `- \`az repos pr set-vote --id <number> --vote {approve | approve-with-suggestions | reject | reset | wait-for-author}\`\n` +
     `- Pair the vote with a thread comment. **Preferred:** \`minions pr comment <number> --host ado --ado-org ${getProjectOrg(project)} --ado-project ${project?.adoProject || '<ado-project>'} --repo-id ${repoId || '<repo-id>'} --agent <your-agent-id> --kind review-decision [--wi <work-item-id>] --body-file <verdict.md>\` (applies the marker + harness section + brand link for you). Fallback: \`az repos pr comment create --pull-request-id <number> --content @<verdict.md>\`\n\n` +
@@ -149,7 +162,7 @@ function getRepoHostLabel(project) {
 function getRepoHostToolRule(project) {
   const host = getRepoHost(project);
   if (host === 'github') return 'Use GitHub MCP tools or `gh` CLI for PR operations';
-  return 'For Azure DevOps, use the `az` CLI for PR operations (e.g. `az repos pr create`, `az repos pr show`, `az repos pr comment`, `az repos pr set-vote`); if `az` is unavailable or insufficient, fall back to the ADO REST API (`_apis/git/...`) with a token from `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798`. Do not use `gh` for Azure DevOps repositories.';
+  return 'For Azure DevOps, use the `az` CLI for PR operations (e.g. `az repos pr create`, `az repos pr show`, `az repos pr comment`); if `az` is unavailable or insufficient, fall back to the ADO REST API (`_apis/git/...`) with a token from `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798`. Do not use `gh` for Azure DevOps repositories. Whether to cast a reviewer vote (`az repos pr set-vote`) is governed separately by the PR vote instructions — do not vote unless they tell you to.';
 }
 
 // ─── Task Context Resolution ────────────────────────────────────────────────
@@ -967,7 +980,7 @@ function renderPlaybook(type, vars) {
     pr_create_instructions: getPrCreateInstructions(renderProject),
     pr_comment_instructions: getPrCommentInstructions(renderProject),
     pr_fetch_instructions: getPrFetchInstructions(renderProject),
-    pr_vote_instructions: getPrVoteInstructions(renderProject),
+    pr_vote_instructions: getPrVoteInstructions(renderProject, config),
     repo_host_label: getRepoHostLabel(renderProject),
   };
   const allVars = { ...projectVars, ...vars };

package/engine/shared.js

@@ -2963,6 +2963,25 @@ function resolveLiveCheckoutAutoReset(project, engine) {
   return false;
 }
 
+// W-mr3lunnq000o9f41 (companion to the stale-base guard) — resolve the
+// live-checkout auto-base-repair decision. Per-project `liveCheckoutAutoBaseRepair`
+// wins, else fleet-wide `engine.liveCheckoutAutoBaseRepair`, else false (opt-in).
+// When ON, prepareLiveCheckout's wrong-base recovery may materialize a local base
+// branch from the `refs/remotes/origin/<mainRef>` remote-tracking ref (a LOCAL ref
+// — no `git fetch`, so issue #226's no-forced-fetch guarantee is preserved) when
+// no local `refs/heads/<mainRef>` exists, instead of failing closed with
+// LIVE_CHECKOUT_WRONG_BASE. origin/<mainRef> IS the project base, so there is no
+// scope-contamination risk (unlike forking off the stale topic HEAD). Default OFF.
+function resolveLiveCheckoutAutoBaseRepair(project, engine) {
+  if (project && typeof project === 'object' && typeof project.liveCheckoutAutoBaseRepair === 'boolean') {
+    return project.liveCheckoutAutoBaseRepair;
+  }
+  if (engine && typeof engine === 'object' && typeof engine.liveCheckoutAutoBaseRepair === 'boolean') {
+    return engine.liveCheckoutAutoBaseRepair;
+  }
+  return false;
+}
+
 function validateCheckoutMode(value) {
   if (value === undefined || value === null || value === '') return undefined;
   if (typeof value !== 'string') {
@@ -3262,6 +3281,7 @@ const ENGINE_DEFAULTS = {
   maxRetries: 3, // max dispatch retries before marking work item as failed
   maxRetriesPerAgent: 2, // W-mpmwxn1j — per-agent retry cap. When the SAME agent fails the same WI this many times, the next retry MUST reassign to a different eligible agent (consults routing.md + agent availability). Falls back to the same agent only when no alternate is available. Counted separately from `maxRetries` (which caps total retries across all agents) and tracked on the WI as `_retriesByAgent: { agentId: count }`. Hard-pinned agents bypass reassignment (operator intent wins).
   maxPhantomRetries: 3, // max retries for "phantom completion" (runtime crashed before emitting type:"result"); tracked separately from _retryCount so phantom retries don't pollute the normal PR-attachment retry budget. See engine/lifecycle.markMissingPrAttachment + detectNonTerminalResultSummary.
+  maxReviewVerdictMissingRetries: 2, // W-mr9sy3j700076967 — bounded retry budget for a review dispatch that completes ("success") without posting a VERDICT: comment. Below the budget, engine/lifecycle.updatePrAfterReview leaves `lastReviewedAt` unset so the normal needsReview gate re-dispatches a fresh review; at/above budget it stamps `lastReviewedAt` (stops auto-retry) but keeps `_reviewVerdictMissing: true` so the PR is dashboard-flagged for a human instead of looking like an ordinary still-pending review.
   minRetryGapMs: 120000, // 2min — minimum gap between retry dispatches for the same work item; prevents tight retry loops when an idempotent agent (e.g. review bailing out on a duplicate) cannot produce the expected output (#1770)
   pipelineApiRetries: 2, // max attempts for pipeline API calls
   pipelineApiRetryDelay: 2000, // ms delay between pipeline API retries
@@ -3421,7 +3441,7 @@ const ENGINE_DEFAULTS = {
   // stale PRD reopen can't smuggle in unvetted items.
   preDispatchEvalSkipPrdSourced: true,
   completionNonceRequired: false, // P-d2a8f6c1 (agent trust boundary F8): when true, a missing `nonce` field in the completion JSON hard-fails the dispatch with failure_class:'completion-nonce-mismatch'. Default false for one release so older agents/runtime caches that haven't picked up the prompt change degrade with a warning instead of breaking. Mismatched nonces hard-fail regardless of this flag. See docs/completion-reports.md → "Trust boundary".
-  autoApplyReviewVote: false, // W-mpea9fyb0010febf / P-f7splitgate: gates POSITIVE auto-actions only — when true, the engine mirrors live platform vote state into local pull-requests.json reviewStatus (so platform-side approves auto-promote local status). When false (default), the verdict is recorded in pull-requests.json reviewStatus from the agent's completion only — informational. NEGATIVE-correction (dismissing the engine's own prior REQUEST_CHANGES / resetting its own prior negative ADO vote on a verdict flip to APPROVE) is correctness and runs UNCONDITIONALLY regardless of this flag.
+  autoApplyReviewVote: false, // W-mpea9fyb0010febf / P-f7splitgate: master gate for ALL engine platform vote mutations. When true, the engine (a) mirrors live platform vote state into local pull-requests.json reviewStatus, (b) re-applies its own ADO +10 approval when ADO resets votes on target-branch advance (pollPrStatus), (c) reconciles its own prior negative on a verdict flip to APPROVE (ADO resetReviewerNegativeVote / GitHub dismissPriorViewerChangesRequestedReviews), and (d) instructs ADO review agents to cast `az repos pr set-vote`. When false (default), the verdict is recorded in pull-requests.json reviewStatus from the agent's completion ONLY — informational — and Minions never cast, re-cast, or clear a platform vote/review (ADO agents post the verdict as a comment only, parity with GitHub self-approval block).
 
   // ── Runtime fleet (P-3b8e5f1d) ──────────────────────────────────────────────
   // Single source of truth for which CLI runtime + model every spawn uses.
@@ -4854,6 +4874,7 @@ const FAILURE_CLASS = {
   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.
   LIVE_CHECKOUT_WORKTREE_CONFLICT: 'live-checkout-worktree-conflict', // W-mr28h2j2000y0de1 (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because that exact branch is ALSO checked out in a SECOND worktree elsewhere (a leftover from a prior isolated-worktree dispatch, a manually-created worktree, or a stale worktree left by a checkoutMode change). git refuses deterministically with `fatal: '<branch>' is already used by worktree at '<path>'`. Distinct from LIVE_CHECKOUT_FAILED (transient) because this is a STRUCTURAL conflict — it does NOT clear on retry, ever, until a human or the engine removes/reassigns the other worktree; retrying just reproduces it identically and burns maxRetries. Non-retryable — the operator either `git worktree remove <path>` (freeing the branch) if that worktree is stale, or finishes/commits/pushes from it directly if it holds real WIP. 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.
+  LIVE_CHECKOUT_WRONG_BASE: 'live-checkout-wrong-base', // W-mr3lunnq000o9f41 (live-checkout dispatch mode): a NEW-branch fork was requested but the operator's checkout HEAD is on an unrelated topic/feature branch, NOT the project base (mainRef), and prepareLiveCheckout could not switch to a LOCAL base ref (no `refs/heads/<mainRef>`, or the local checkout itself failed). Forking off the stale HEAD would silently bake every commit already on that branch into the new branch AND its PR — committed-history scope contamination that survives the dirty/mid-operation preflights (the ADO PR 5411214 incident: ~22 unrelated OCM files, author-disavowed). The engine never fetches origin/<mainRef> in live mode (issue #226) so it cannot self-heal a missing local base. Non-retryable — the operator must `git checkout <mainRef>` in the operator checkout before re-dispatch. Does NOT fire for PR-targeted fixes or shared-branch continuations (those pass allowNonMainBase, intentionally continuing a non-main branch), nor when HEAD is already on mainRef, nor when a local mainRef ref exists (the guard switches to it and forks cleanly). OPT-IN AUTO-RECOVERY (`liveCheckoutAutoBaseRepair`, per-project > fleet-wide, default OFF): when enabled AND a `refs/remotes/origin/<mainRef>` remote-tracking ref exists, the guard materializes a local `<mainRef>` branch from it (a LOCAL ref op — still no `git fetch`, issue #226 preserved; origin/<mainRef> IS the base so no contamination) and forks cleanly instead of failing — eliminating the manual `git checkout <mainRef>` step. Still fails closed when neither a local base nor an origin-tracking base ref exists, or when the base checkout itself fails/hangs.
   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.
@@ -9726,6 +9747,7 @@ module.exports = {
   resolveCheckoutMode,
   isLiveCheckoutProject,
   resolveLiveCheckoutAutoReset,
+  resolveLiveCheckoutAutoBaseRepair,
   validatePid,
   PR_FIX_CAUSE,
   getPrFixAutomationCause,

package/engine.js

@@ -2451,6 +2451,13 @@ async function spawnAgent(dispatchItem, config) {
   }
   if (liveMode && branchName && !READ_ONLY_ROOT_TASK_TYPES.has(type)) {
     const _liveMainRef = sanitizeBranch(shared.resolveMainBranch(cwd, project.mainBranch));
+    // W-mr3lunnq000o9f41: PR-targeted fixes and shared-branch continuations
+    // intentionally keep building on a non-main branch, so they opt OUT of the
+    // stale-base guard in prepareLiveCheckout. `meta.useExistingBranch` is set
+    // true for every PR-targeted WI and for shared-branch WIs (engine.js
+    // dispatch meta), so it is the exact "this is a continuation, not a fresh
+    // fork off baseline" signal.
+    const _liveAllowNonMainBase = !!(meta?.useExistingBranch || meta?.branchStrategy === 'shared-branch');
     const _wiIdForAlert = meta?.item?.id || id;
     const _liveCheckout = require('./engine/live-checkout');
     let _liveResult;
@@ -2463,6 +2470,7 @@ async function spawnAgent(dispatchItem, config) {
         dispatchId: id,
         wiId: _wiIdForAlert,
         skipDirtyCheck: !!project.skipLiveCheckoutDirtyCheck,
+        allowNonMainBase: _liveAllowNonMainBase,
         log: (msg, lvl) => log(lvl || 'info', msg),
       });
     } catch (liveErr) {
@@ -2694,6 +2702,75 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // W-mr3lunnq000o9f41: stale non-main base refusal. A NEW-branch fork was
+    // requested but the operator's checkout HEAD is on an unrelated branch, not
+    // the project base (mainRef), and prepareLiveCheckout could not switch to a
+    // LOCAL base ref (issue #226 forbids fetching origin/<mainRef> in live mode,
+    // so the engine cannot self-heal a missing local base). Forking off the
+    // stale HEAD would silently inherit every commit already on that branch into
+    // the new branch and its PR (committed-history scope contamination — the ADO
+    // PR 5411214 incident, which survived the dirty/mid-operation preflights).
+    // Fail closed with a distinct non-retryable FAILURE_CLASS and operator-
+    // actionable guidance; the engine never moves the operator's HEAD for them
+    // beyond the local-only base switch the helper already attempted.
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'wrong-base') {
+      const _headBranch = typeof _liveResult.headBranch === 'string' && _liveResult.headBranch
+        ? _liveResult.headBranch
+        : '(unknown)';
+      const _expectedBase = typeof _liveResult.expectedBase === 'string' && _liveResult.expectedBase
+        ? _liveResult.expectedBase
+        : _liveMainRef;
+      const _switchErr = typeof _liveResult.switchError === 'string' ? _liveResult.switchError : '';
+      const _alertBody = [
+        '# Live-checkout blocked: HEAD is on the wrong base branch',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**New branch (requested):** ${branchName}`,
+        `**HEAD is on:** ${_headBranch}`,
+        `**Expected base:** ${_expectedBase}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        `The engine refused to spawn the agent because \`${cwd}\` is checked out on \`${_headBranch}\`, not the project base \`${_expectedBase}\`. Forking the new branch \`${branchName}\` off \`${_headBranch}\` would silently inherit **every commit already on that branch** into the new branch — and into its PR — as committed history (this is exactly how ADO PR 5411214 picked up ~22 unrelated files). Live-checkout never fetches \`origin/${_expectedBase}\` for you (issue #226), and no local \`${_expectedBase}\` ref was usable, so the engine cannot safely establish the base itself.`,
+        ...(_switchErr ? ['', 'The local base checkout failed with:', '', '```', _switchErr, '```'] : []),
+        '',
+        '## Recovery',
+        '',
+        `Switch the operator checkout back to the base branch, then re-dispatch the work item:`,
+        '',
+        '```',
+        `git -C "${cwd}" checkout ${_expectedBase}`,
+        '```',
+        '',
+        `If you deliberately want to stack this work on \`${_headBranch}\`, dispatch it as a PR-targeted or shared-branch work item instead — those intentionally continue a non-main branch and are exempt from this guard.`,
+      ].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_wrong_base';
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      const _shortMsg = `live-checkout blocked: HEAD on '${_headBranch}' (not base '${_expectedBase}') in ${cwd} — refusing to fork ${branchName} off a stale base`;
+      log('error', `spawnAgent: ${_shortMsg}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        _shortMsg.slice(0, 800),
+        `Live-checkout refused to fork a new branch off '${_headBranch}' because it is not the project base '${_expectedBase}' — doing so would bake that branch's commits into the new PR (scope contamination). The engine never fetches origin in live mode (issue #226) and found no usable local base ref. Operator must \`git checkout ${_expectedBase}\` before re-dispatch. Retrying without moving HEAD is provably useless.`,
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_WRONG_BASE, agentRetryable: false },
+      );
+      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
@@ -2786,6 +2863,7 @@ async function spawnAgent(dispatchItem, config) {
               dispatchId: id,
               wiId: _wiIdForAlert,
               skipDirtyCheck: !!project.skipLiveCheckoutDirtyCheck,
+              allowNonMainBase: _liveAllowNonMainBase,
               log: (msg, lvl) => log(lvl || 'info', msg),
             });
           } catch (retryErr) {

package/package.json

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