@yemi33/minions 0.1.2356 → 0.1.2357

package/dashboard/js/render-pipelines.js

@@ -561,7 +561,12 @@ async function _refreshPipelineDetail(id) {
       _pipelinesData = _pipelinesData.map(function(x) { return x.id === id ? fresh : x; });
       _pipelinePollHash = _computePipelineDetailHash(fresh);
       renderPipelines(_pipelinesData);
-      openPipelineDetail(id);
+      // Only refresh the detail modal when it's already open for this pipeline —
+      // callers triggered from the card list (modal closed / different id) must not
+      // pop the modal open. See same guard pattern above at :625, :640, :649.
+      if (document.getElementById('modal')?.classList?.contains('open') && _pipelinePollId === id) {
+        openPipelineDetail(id);
+      }
     }
   } catch (e) { /* silent — next poll will catch up */ }
 }
@@ -569,12 +574,16 @@ async function _refreshPipelineDetail(id) {
 async function _triggerPipeline(id, btn) {
   if (btn) { btn.textContent = 'Starting...'; btn.style.pointerEvents = 'none'; btn.style.opacity = '0.6'; }
   showToast('cmd-toast', 'Pipeline triggered', true);
-  // Optimistic: inject a running state so the UI updates immediately
+  // Optimistic: inject a running state so the card list updates immediately.
+  // Do NOT open the modal here — this function is shared by the CARD's Run Now
+  // button (modal must stay closed) and the modal's own Run Now button (the
+  // modal, if open for this id, is refreshed exactly once below via the
+  // guarded _refreshPipelineDetail() call once the trigger POST resolves).
   var p = _pipelinesData.find(function(x) { return x.id === id; });
   if (p) {
     if (!p.runs) p.runs = [];
     p.runs.push({ status: 'running', startedAt: new Date().toISOString(), stages: {} });
-    openPipelineDetail(id);
+    renderPipelines(_pipelinesData);
   }
   try {
     var res = await fetch('/api/pipelines/trigger', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: id }) });

package/dashboard/js/render-prs.js

@@ -225,6 +225,26 @@ function prRow(pr) {
       + 'onclick="event.stopPropagation();resumeBuildFixIneffective(this)">'
       + '⏸ infra issue suspected ▶</button>';
   }
+  // Issue #764 — worktree-held-externally chip. pr._worktreeHeldPaused is set
+  // when a PR-driven review/fix dispatch hit WORKTREE_PREFLIGHT because this
+  // PR's branch is checked out at the project root or in an external
+  // worktree the engine can't reach (see engine/lifecycle.js
+  // recordWorktreeHeldPause). engine.js auto-clears this pause once it
+  // detects the holder no longer holds the branch; this chip lets an
+  // operator force-clear it immediately via
+  // /api/pull-requests/clear-worktree-held-pause (resumeWorktreeHeldPause
+  // below) without waiting for the next PR poll tick.
+  var worktreeHeldPaused = pr._worktreeHeldPaused;
+  if (worktreeHeldPaused && typeof worktreeHeldPaused === 'object') {
+    var whpTitle = (worktreeHeldPaused.reason || 'Branch is held externally; PR automation paused')
+      + '. Auto-clears once the holder releases the branch, or click to resume now.';
+    pausedChips += ' <button class="pr-badge rejected pr-worktree-held-chip" '
+      + 'style="font-size:var(--text-xs);cursor:pointer;border:none" '
+      + 'title="' + escapeHtml(whpTitle) + '" '
+      + 'data-pr-id="' + escapeHtml(String(pr.id || '')) + '" '
+      + 'onclick="event.stopPropagation();resumeWorktreeHeldPause(this)">'
+      + '⏸ branch held externally ▶</button>';
+  }
   const titleText = pr.title || 'Untitled';
   // Polish (W-mqv5ccn7): flatten Markdown in the body so the preview shows
   // plain text instead of raw `##` / `**…**` / backtick source.
@@ -791,4 +811,38 @@ async function resumeBuildFixIneffective(btn) {
   }
 }
 
-window.MinionsPrs = { prRow, prTableHtml, renderPrs, prPrev, prNext, openAllPrs, openModal, openAddPrModal, openPrDetail, unlinkPr, togglePrObserve, resumePausedCause, resumeBuildFixIneffective };
+// Issue #764 — resume a paused worktree-held-externally pause. Mirrors
+// resumeBuildFixIneffective above but targets the holder-path-keyed
+// _worktreeHeldPaused record via its own endpoint. engine.js already
+// auto-clears this pause the next time it detects the holder released the
+// branch; this handler exists for operators who don't want to wait for the
+// next PR poll tick.
+async function resumeWorktreeHeldPause(btn) {
+  if (!btn || btn.disabled) return;
+  const prId = btn.dataset.prId;
+  if (!prId) return;
+  if (!confirm('Resume PR automation on ' + prId + '?\n\nThis clears the "branch held externally" pause so the engine can re-dispatch review/fix work on the next discovery pass.')) return;
+  btn.disabled = true;
+  const prevDisplay = btn.style.display;
+  btn.style.display = 'none';
+  showToast('pr-toast', 'Resumed PR automation on ' + prId, true);
+  try {
+    const res = await fetch('/api/pull-requests/clear-worktree-held-pause', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ prId })
+    });
+    if (!res.ok) {
+      const d = await res.json().catch(() => ({}));
+      btn.style.display = prevDisplay;
+      btn.disabled = false;
+      showToast('pr-toast', 'Failed: ' + (d.error || 'unknown'), false);
+      return;
+    }
+  } catch (e) {
+    btn.style.display = prevDisplay;
+    btn.disabled = false;
+    showToast('pr-toast', 'Error: ' + e.message, false);
+  }
+}
+
+window.MinionsPrs = { prRow, prTableHtml, renderPrs, prPrev, prNext, openAllPrs, openModal, openAddPrModal, openPrDetail, unlinkPr, togglePrObserve, resumePausedCause, resumeBuildFixIneffective, resumeWorktreeHeldPause };

package/dashboard.js

@@ -6434,6 +6434,14 @@ const server = http.createServer(async (req, res) => {
         found = true;
         item.status = WI_STATUS.PENDING;
         item._retryCount = 0; // Reset retry counter on manual retry
+        // W-mrcqzuxy000w676e — quarantineRecoveryCount is a lifetime cumulative
+        // counter (engine.js discoverWork auto-recovery loop), so unrelated prior
+        // quarantine noise can permanently give up on a WI even when a later
+        // attempt would recover cleanly. A manual retry is an explicit human
+        // signal to try again — reset the counter/give-up flag so it isn't
+        // punished by history.
+        delete item._quarantineRecoveryCount;
+        delete item._quarantineRecoveryGaveUp;
         delete item.dispatched_at;
         delete item.dispatched_to;
         delete item.failReason;
@@ -7097,6 +7105,16 @@ const server = http.createServer(async (req, res) => {
           // committed. Compensate by removing the item from the target
           // store again, so the item ends up in exactly one store (its
           // original) instead of duplicated across two.
+          //
+          // W-mrciooy1000e2ac3 — the compensating rollback write can ITSELF
+          // fail (double-failure: destination insert succeeded, source
+          // splice failed, and the compensating removal from destination
+          // also failed). Swallowing that second error and unconditionally
+          // reporting "move was rolled back" is a lie: the item is still
+          // duplicated in both stores. Track the rollback outcome and
+          // surface the double-failure distinctly so the caller/UI never
+          // believes a rollback happened when it didn't.
+          let rollbackErr = null;
           try {
             mutateJsonFileLocked(projectMove.wiPath, (targetItems) => {
               if (!Array.isArray(targetItems)) targetItems = [];
@@ -7104,7 +7122,30 @@ const server = http.createServer(async (req, res) => {
               if (ti !== -1) targetItems.splice(ti, 1);
               return targetItems;
             });
-          } catch { /* best-effort rollback; surfaced via the 500 below regardless */ }
+          } catch (rbErr) { rollbackErr = rbErr; }
+
+          if (rollbackErr) {
+            console.error(
+              `[work-items/update] DOUBLE FAILURE on cross-project move of ${id}: ` +
+              `source-splice failed (${spliceErr.message}) AND compensating rollback ` +
+              `from target store also failed (${rollbackErr.message}). Item may now be ` +
+              `duplicated across source (${wiPath}) and target (${projectMove.wiPath}) ` +
+              `— manual reconciliation required.`
+            );
+            return jsonReply(res, 500, {
+              error: `project move failed while removing from source store, and the compensating rollback also failed: ${rollbackErr.message}. ` +
+                `Item may be duplicated across both stores — manual reconciliation required.`,
+              reconciliation: {
+                required: true,
+                id,
+                sourceStore: wiPath,
+                targetStore: projectMove.wiPath,
+                spliceError: spliceErr.message,
+                rollbackError: rollbackErr.message,
+              },
+            });
+          }
+
           return jsonReply(res, 500, {
             error: `project move failed while removing from source store; move was rolled back: ${spliceErr.message}`,
           });
@@ -14167,6 +14208,42 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       return jsonReply(res, 200, { ok: true, cleared: 'build-fix-ineffective', prId });
     }},
 
+    // Issue #764 — sibling to the two clear endpoints above, for the
+    // holder-path-keyed `_worktreeHeldPaused` circuit breaker (see
+    // engine/lifecycle.js#recordWorktreeHeldPause / engine.js's
+    // isWorktreeHeldPauseSuppressed). engine.js already auto-clears this the
+    // next time it detects the holder no longer holds the branch, but this
+    // endpoint lets an operator force a clear immediately (e.g. they just
+    // released the branch and don't want to wait for the next PR poll tick).
+    { method: 'POST', path: '/api/pull-requests/clear-worktree-held-pause', desc: 'Resume a paused worktree-held-externally pause (issue #764) — clears _worktreeHeldPaused so PR-driven review/fix auto-dispatch can resume', params: 'prId (canonical host:slug#number)', handler: async (req, res) => {
+      const body = await readBody(req);
+      const prId = typeof body?.prId === 'string' ? body.prId.trim() : '';
+      if (!prId) return jsonReply(res, 400, { error: 'prId required' });
+      reloadConfig();
+      const lifecycle = require('./engine/lifecycle');
+      const prPaths = [
+        ...shared.getProjects(CONFIG).map(p => shared.projectPrPath(p)),
+        shared.centralPullRequestsPath(MINIONS_DIR),
+      ];
+      let prFound = false;
+      let recordCleared = false;
+      for (const prPath of prPaths) {
+        if (recordCleared) break;
+        shared.mutatePullRequests(prPath, (prs) => {
+          if (!Array.isArray(prs)) return prs;
+          const target = prs.find(p => p && p.id === prId);
+          if (!target) return prs;
+          prFound = true;
+          recordCleared = lifecycle.clearWorktreeHeldPause(target);
+          return prs;
+        });
+      }
+      if (!prFound) return jsonReply(res, 404, { error: `PR ${prId} not found` });
+      if (!recordCleared) return jsonReply(res, 400, { error: `PR ${prId} has no tracked worktree-held pause` });
+      invalidateStatusCache();
+      return jsonReply(res, 200, { ok: true, cleared: 'worktree-held-pause', prId });
+    }},
+
     // ─── P-f3c9d0e7: convenience pause/resume endpoints ─────────────────────
     // Single-call wrappers over `POST /api/settings { engine: { <flag>: bool } }`
     // for the two operator kill-switches:

package/docs/README.md

@@ -31,6 +31,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [harness-propagation.md](harness-propagation.md) — How user-level and project-local harness assets (skills, slash-commands, MCP config, `CLAUDE.md` / `AGENTS.md`) propagate into an agent's worktree via `--add-dir`, the `harnessPropagateProjectLocal` flag, and the project-local-on-main worktree-visibility footgun.
 - [harness-transparency.md](harness-transparency.md) — The `harnessUsed` self-report contract: capture (agent reports the skills / MCPs / commands / docs it used) → ground (engine cross-checks against `_harnessPropagated` and annotates `grounded:true\|false`, never dropping) → surface (PR comment, final agent note, work-item modal).
 - [kb-dedup-duplicate-pair-investigation.md](kb-dedup-duplicate-pair-investigation.md) — Investigation-only pass diffing suspected duplicate KB filename groups (content-hash dedup for agent-authored reviews/build-reports) to confirm true full-body duplication before any fix is proposed.
+- [kb-pr3223-cascade-archiving.md](kb-pr3223-cascade-archiving.md) — Findings from PR #3223: cascade-archiving PRDs when their linked markdown plan is archived, including the per-concern try/catch pattern and `source_plan` basename-matching invariant in `handlePlansArchive` (`dashboard.js`).
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
 - [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
 - [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `checkoutMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.

package/docs/live-checkout-mode.md

@@ -30,6 +30,10 @@ Implementation: `engine.js` builds a `liveProjectsInUse` set from the active dis
 
 ### 2. Refuse-on-dirty (engine never resets the operator tree)
 
+**W-mrcifup2000c218a — detected at ALLOCATION time first.** Before a live-mode work item is even dispatched, `engine.js`'s dispatch-existing-pending loop calls `engine/live-checkout.js#checkLiveCheckoutDirty` (a cheap, read-only, non-mutating `git status --porcelain=v1 -b` probe — same command, same auto-cleanable-artifact allowance as the in-spawn check below) in the same pass that already gates on `live_checkout_busy`. A dirty hit stamps `_pendingReason: 'live_checkout_dirty'` on the pending item and `continue`s — **no dispatch attempt, no retry consumed, no failure recorded** — exactly like the busy gate. The item is re-checked every tick and dispatches normally the moment the tree is clean. A `live-checkout-dirty-<wi-id>` inbox alert is written (deduped per day, same as the in-spawn alert below) so a persistent dirty condition is still surfaced to a human even though the WI itself stays pending.
+
+The in-spawn check below remains as a **defense-in-depth fallback** for the race window between the allocation-time probe and the actual git operations inside `spawnAgent` (e.g. the tree goes dirty in the few seconds between the pre-check and the spawn) — it is now the *exception* path, not the common path.
+
 Before spawning, `engine/live-checkout.js#prepareLiveCheckout` runs `git status --porcelain` from `project.localPath`. Any output (staged, unstaged, untracked) **returns** an explicit `{ ok:false, reason:'dirty', dirtyFiles:[…] }` result (it does NOT throw), which refuses the dispatch immediately:
 
 - Non-retryable `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (added to `engine/dispatch.js`'s `neverRetry` set so the dispatcher never re-spawns mechanically). **Reserved for this confirmed-dirty result only** — a thrown helper/git error is `LIVE_CHECKOUT_FAILED`, see below (#305). **Auto-cleanup exception (W-mqzmkoqt000hbca2, #582):** when `liveCheckoutAutoReset` or `liveCheckoutAutoStash` is enabled (per-project or fleet-wide), `spawnAgent` treats the dirty refusal as retryable instead — the engine re-cleans the tree on every attempt, so the two-strike cap below is skipped and the dispatch keeps retrying up to the normal `maxRetries` cap. The `dispatch.js` `neverRetry` entry is kept only as a defensive fallback for callers that omit the explicit `agentRetryable` override.
@@ -129,6 +133,8 @@ Either condition fails the dispatch non-retryably with `FAILURE_CLASS.LIVE_CHECK
 
 ### 6. STALE-BASE GUARD — refuse to fork off a diverged local base (W-mr98op8w000ma4ad)
 
+**W-mrcifup2000c218a — detected at ALLOCATION time first.** Same as Guarantee 2, the stale-base condition is now checked BEFORE dispatch by `engine/live-checkout.js#checkLiveCheckoutStaleBase` (a cheap, read-only, fetch-free `git rev-list --count origin/<mainRef>..<mainRef>` probe, mirroring the in-spawn check below) in the dispatch-existing-pending loop. A stale hit stamps `_pendingReason: 'live_checkout_stale_base'` and leaves the item pending — no retry consumed, no terminal failure — re-checked every tick, instead of the pre-fix behavior of failing non-retryably on the very first hit. A `live-checkout-stale-base-<wi-id>` inbox alert is written (deduped per day) so the condition is still surfaced to a human. The in-spawn refusal documented below is now a defense-in-depth fallback for the race window between the pre-check and the actual `git checkout -b`, not the common path — it still fails non-retryably when it fires, because a stale base found there is still deterministic and un-recoverable by a bare retry.
+
 A **clean** tree can still hide **committed** contamination. When `prepareLiveCheckout` is about to create a **new** branch (`git checkout -b <branch>`) off the operator's current HEAD, and HEAD is sitting on the project base ref (`mainRef`, the common case), the local `mainRef` branch may carry commits that were never pushed to `origin/<mainRef>` — e.g. leftover in-progress work from a prior dispatch on a live-mode project (capped to one mutating dispatch, but shared across many sequential dispatches), an interrupted process, or a bad rebase. Forking a new branch off that base silently inherits those commits into the branch **and its PR**. This is exactly the scope-contamination class first seen on ADO PR 5411214 and recurring on AB#12016662 / ADO PR 5419146 (~20 unrelated OCM files baked into an otherwise-clean 2-file a11y fix).
 
 It survives the dirty check (Guarantee 2) because the contamination is **committed**, not uncommitted, and it cannot be caught by a "HEAD is on the wrong branch" check because here HEAD **is** on `mainRef`.

package/docs/worktree-lifecycle.md

@@ -84,6 +84,47 @@ recreate a clean worktree. Six layered defenses cover the Windows EBUSY
 race when git status descendants still hold packfile handles
 (W-mq5n1zx5000hcfb5; PR #3156).
 
+### Uncommitted-work preservation (W-mrcqzuxy000w676e)
+
+The committed-HEAD backup ref (`refs/minions/quarantine/<sanitized-branch>/<ts>`,
+written near the end of `_quarantineDirtyWorktreeCore`) only ever captured
+`git rev-parse HEAD` — it never covered **uncommitted** modified/untracked
+files. A prior incident (W-mrciooy1000e2ac3) lost a real, on-task fix + a new
+regression test that a previous agent had written but not committed: the
+worktree was quarantined cleanly, but the uncommitted edits were gone the
+moment the dir was renamed away.
+
+`_quarantineDirtyWorktreeCore` now runs a **separate, best-effort WIP-snapshot
+step** immediately after the live-dispatch guard and before any destructive
+work (holder-reap / rename / force-remove):
+
+1. Probe `git status --porcelain` in the worktree.
+2. If it reports any entries, run `git add -A && git commit --no-verify -m
+   "quarantine: uncommitted WIP snapshot (<dispatchId>)"` in the worktree
+   (captures both modified tracked files and new untracked files), then
+   `git update-ref refs/minions/quarantine-wip/<sanitized-branch>/<ts> <sha>`
+   in the shared repo to pin the WIP commit under its own ref — independent of
+   the plain `refs/minions/quarantine/...` backup ref.
+3. Never blocks the quarantine: any failure at any point (status probe, add,
+   commit, update-ref) is caught, logged, and the quarantine proceeds
+   regardless.
+
+The result object carries this as `result.wipRef` (the ref path, or `null`)
+and `result.wipOutcome`, one of exactly three values so a "did we lose
+anything?" question always has an unambiguous, logged answer:
+
+- `'clean'` — no uncommitted changes existed; nothing to preserve.
+- `'preserved'` — uncommitted changes were committed and backed up to `wipRef`.
+- `'failed'` — uncommitted changes existed (or status was undeterminable) but
+  the snapshot attempt itself failed; check the engine log for the specific
+  git error.
+
+The quarantine inbox note (`notes/inbox/engine-worktree-quarantine-*.md`) always
+includes a `wipOutcome`-specific recovery line — the `wipRef` cherry-pick/show
+command when `preserved`, a `⚠️` warning when `failed`, or an explicit "nothing
+to preserve" note when `clean` — so a human never has to guess which bucket a
+given quarantine landed in.
+
 ### Layer 1b — `--no-optional-locks` on every status probe (load-bearing)
 
 `_statusPorcelainCmd()` emits `git --no-optional-locks status …`. Skips
@@ -105,6 +146,33 @@ budget explicitly. Toggles:
 `ENGINE_DEFAULTS.quarantineRenameRetryAttempts` (6),
 `quarantineRenameRetryBaseMs` (250).
 
+### Layer 1a′ — concurrent-quarantine race guard (W-mrcllbrx000oec11)
+
+Two overlapping recovery attempts against the SAME dirty worktree path can
+both reach the rename step (observed ~96ms apart in production — see
+W-mrciooy1000e2ac3, 12 recovery cycles burned before the WI was wrongly
+marked terminally failed even though the tree was already clean). ENOENT is
+non-retryable in `_retryFsOp`, so the loser's rename throws immediately once
+the winner has already moved the source dir aside. Two layers address this:
+
+1. **In-process serialization.** `engine.js#_quarantineDirtyWorktree` is now a
+   thin wrapper that runs the real implementation
+   (`_quarantineDirtyWorktreeCore`) through `_withPathLock`, keyed by
+   `worktreePath`. Overlapping calls for the SAME path queue and run their
+   destructive steps (holder-reap, rename, force-remove) strictly one at a
+   time; calls for different paths are unaffected.
+2. **ENOENT idempotency check.** If the rename still fails with `ENOENT` AND
+   `worktreePath` no longer exists on disk, the source was already renamed
+   away by a concurrent/prior attempt — this is quarantine having *already
+   succeeded*, not an environment block. `_quarantineDirtyWorktreeCore` best-
+   effort locates the sibling `<worktreePath>-quarantine-*` dir the winning
+   attempt created (used for `result.quarantinedPath`), sets
+   `result.alreadyQuarantinedConcurrently = true`, clears the rename error,
+   and proceeds through the normal success path (backup-ref, `git worktree
+   prune`, inbox note) instead of falling into the force-remove fallback or
+   the `WORKTREE_QUARANTINE_ENV_BLOCKED` total-failure branch. Counter:
+   `metrics._engine.worktreeQuarantineOutcomes.alreadyQuarantinedConcurrent`.
+
 ### Layer 2a — `_killGitDescendantsForWorktree` (Windows-only)
 
 PowerShell sweep, 2 s timeout. Shell-out built via single-quoted literal
@@ -128,10 +196,18 @@ the new class via both enum check and regex on legacy `failReason`
 strings, then re-queues under the existing
 `ENGINE_DEFAULTS.quarantineAutoRecoveryMax` (default 2) cap.
 
+`_quarantineRecoveryCount` is a **lifetime cumulative** counter — it is never
+reset by a clean recovery, only by a manual retry. `POST /api/work-items/retry`
+(`dashboard.js#handleWorkItemsRetry`) deletes both `_quarantineRecoveryCount`
+and `_quarantineRecoveryGaveUp` on every manual retry (W-mrcqzuxy000w676e), so
+an explicit human "try again" isn't punished by unrelated prior quarantine
+noise that would otherwise leave `_quarantineRecoveryGaveUp: true` permanently
+set even after a later attempt recovers cleanly.
+
 ### Layer 3a/3b — metrics + inbox alert
 
 Counters at
-`metrics._engine.worktreeQuarantineOutcomes.{attempts, success, successAfterRetry, fallbackForceRemove, totalFailure}`.
+`metrics._engine.worktreeQuarantineOutcomes.{attempts, success, successAfterRetry, fallbackForceRemove, totalFailure, alreadyQuarantinedConcurrent}`.
 Total-failure path writes a structured inbox alert with the exact
 PowerShell/POSIX recovery commands and `git worktree prune` instructions.
 

package/engine/ado.js

@@ -279,7 +279,7 @@ function repairAdoProjectConfig(project, purpose, prs = null) {
   const missingBefore = getMissingAdoProjectConfigFields(project);
   if (missingBefore.length === 0) return false;
 
-  const trackedPrs = prs || shared.safeJson(shared.projectPrPath(project)) || [];
+  const trackedPrs = prs || shared.safeJsonArr(shared.projectPrPath(project));
   for (const candidate of collectAdoRepairCandidates(project, trackedPrs)) {
     const repairs = {};
     if (!project.adoOrg && candidate.adoOrg) repairs.adoOrg = candidate.adoOrg;

package/engine/cleanup.js

@@ -9,7 +9,7 @@ const shared = require('./shared');
 const queries = require('./queries');
 
 const { exec, execAsync, execSilent, log, ts, ENGINE_DEFAULTS } = shared;
-const { safeJson, safeJsonNoRestore, safeWrite, safeReadDir, mutateCooldowns, mutateWorkItems, mutateJsonFileLocked, getProjects, projectWorkItemsPath, projectPrPath,
+const { safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, safeReadDir, mutateCooldowns, mutateWorkItems, mutateJsonFileLocked, getProjects, projectWorkItemsPath, projectPrPath,
   sanitizeBranch, KB_CATEGORIES } = shared;
 const { getDispatch, getAgentStatus } = queries;
 
@@ -98,7 +98,7 @@ function localBranchWorktreeInUse(root, branch) {
 function collectPhantomBranchesForProject(project) {
   const branches = new Set();
   try {
-    const items = safeJson(projectWorkItemsPath(project)) || [];
+    const items = safeJsonArr(projectWorkItemsPath(project));
     if (!Array.isArray(items)) return branches;
     for (const w of items) {
       if (w && w._phantomCompletion === true && w._phantomBranch) {
@@ -1427,11 +1427,11 @@ async function runCleanup(config, verbose = false) {
   try {
     const wiIds = new Set();
     for (const project of projects) {
-      const items = safeJson(projectWorkItemsPath(project)) || [];
+      const items = safeJsonArr(projectWorkItemsPath(project));
       for (const wi of items) { if (wi?.id) wiIds.add(wi.id); }
     }
     try {
-      const centralWi = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
+      const centralWi = safeJsonArr(path.join(MINIONS_DIR, 'work-items.json'));
       for (const wi of centralWi) { if (wi?.id) wiIds.add(wi.id); }
     } catch { /* optional */ }
 

package/engine/lifecycle.js

@@ -3054,6 +3054,71 @@ function clearBuildFixIneffective(target) {
   return true;
 }
 
+// #764 — PR-level circuit breaker for the WORKTREE_PREFLIGHT
+// branch-held-externally failure class (engine.js `_failBranchHeldByExternalWorktree`).
+// That failure already stamps the WI `agentRetryable: false`, which stops the
+// immediate quarantine-recovery-loop storm for that one dispatch instance, but
+// it carries no memory at the PR level — the human-feedback / review / build /
+// conflict fix dispatch pollers see the PR is still `pendingFix` (or has
+// coalesced feedback) and re-dispatch a brand-new work item next cooldown
+// window, forever, until a human manually releases the branch. Mirrors the
+// `_buildFixIneffective` shape (see `recordBuildFixIneffective` above) so the
+// dashboard/pause-inspection conventions stay consistent, but is keyed on the
+// holder path + branch rather than a head SHA — the signal that should clear
+// this pause is "the holder no longer holds the branch", not "a new commit
+// landed" (see `engine.js#isWorktreeHeldPauseSuppressed`, which performs that
+// live re-check and calls `clearWorktreeHeldPause` when the holder has moved
+// on).
+function recordWorktreeHeldPause(target, { holderPath, isProjectRoot, branch, dispatchItem } = {}) {
+  if (!target) return null;
+  const now = ts();
+  const prior = target._worktreeHeldPaused && typeof target._worktreeHeldPaused === 'object'
+    ? target._worktreeHeldPaused : null;
+  target._worktreeHeldPaused = {
+    holderPath: holderPath || null,
+    isProjectRoot: !!isProjectRoot,
+    branch: branch || null,
+    since: prior?.since || now,
+    lastAt: now,
+    dispatchId: dispatchItem?.id || null,
+    reason: isProjectRoot
+      ? `Branch ${branch || '(unknown)'} is held by the project root (${holderPath}). PR-driven review/fix automation is paused until the root releases the branch.`
+      : `Branch ${branch || '(unknown)'} is held by an external worktree at ${holderPath} the engine can't reach. PR-driven review/fix automation is paused until that worktree releases the branch.`,
+  };
+  if (!prior) {
+    try {
+      const prNumber = target.prNumber || shared.getPrNumber(target) || target.id || 'unknown';
+      const noteBody = `# Worktree-held pause — PR automation stopped: ${target.id || prNumber}\n\n`
+        + `**PR:** ${target.url || target.id || '(unknown)'}\n`
+        + `**Branch:** ${branch || target.branch || '(unknown)'}\n`
+        + `**Holder:** ${holderPath || '(unknown)'}${isProjectRoot ? ' (project root)' : ' (external worktree)'}\n\n`
+        + `A WORKTREE_PREFLIGHT dispatch failed because this branch is checked out ${isProjectRoot ? 'at the project root' : 'in an external worktree'} the engine can't reach. `
+        + `Review/human-feedback/build-fix/merge-conflict automation for this PR is now paused so the poller stops re-dispatching against the same unresolved cause every cooldown window (issue #764).\n\n`
+        + `**Recovery:** ${isProjectRoot ? `\`git -C ${holderPath} checkout <mainBranch>\` to release the branch` : 'finish or remove the external worktree holding this branch'} — the engine auto-clears this pause the next time it detects the holder no longer holds the branch.\n`;
+      shared.writeToInbox(
+        'engine',
+        `worktree-held-paused-${prNumber}`,
+        noteBody,
+        null,
+        { wi: dispatchItem?.meta?.item?.id || null, pr: target.id || null },
+      );
+    } catch (err) {
+      log('warn', `worktree-held-paused inbox alert for ${target.id || '(unknown)'}: ${err.message}`);
+    }
+  }
+  return target._worktreeHeldPaused;
+}
+
+// Clears the `_worktreeHeldPaused` circuit breaker (issue #764) so PR-driven
+// review/fix dispatch can resume. Returns true when a record was actually
+// removed so callers (the dashboard resume endpoint, engine.js's live
+// re-check) can distinguish "cleared" from "nothing to clear".
+function clearWorktreeHeldPause(target) {
+  if (!target?._worktreeHeldPaused) return false;
+  delete target._worktreeHeldPaused;
+  return true;
+}
+
 function clearPrNoOpFixAttempt(target, cause) {
   if (!target?._noOpFixes || !target._noOpFixes[cause]) return;
   delete target._noOpFixes[cause];
@@ -7011,6 +7076,13 @@ module.exports = {
   // Issue #671 — exported so dashboard.js can clear the build-fix-ineffective
   // ("infra issue suspected") pause from the resume endpoint.
   clearBuildFixIneffective,
+  // Issue #764 — PR-level circuit breaker for WORKTREE_PREFLIGHT
+  // branch-held-externally failures. Exported so engine.js can stamp the
+  // pause at dispatch-failure time and auto-clear it via the live re-check,
+  // and so dashboard.js can expose a manual clear endpoint + unit tests can
+  // exercise both paths directly.
+  recordWorktreeHeldPause,
+  clearWorktreeHeldPause,
   // W-mpx44p05000ze8d8 — exported so engine/ado.js + engine/github.js can
   // drop stale `_noOpFixes` records during their PR status poll, and so
   // unit tests can exercise the sweep helper directly.

package/engine/live-checkout.js

@@ -128,6 +128,21 @@
  * (signature `(absPath:string) => boolean`, defaulting to fs.existsSync).
  * Production callers omit both and the helper falls back to
  * `require('./shared').shellSafeGit` and `fs.existsSync` respectively.
+ *
+ * `checkLiveCheckoutDirty` / `checkLiveCheckoutStaleBase` (W-mrcifup2000c218a):
+ * ALLOCATION-TIME pre-dispatch counterparts to the dirty / stale-base checks
+ * above. Both are cheap, read-only, non-mutating probes engine.js calls
+ * BEFORE a live-mode work item is dispatched (in the same allocation loop
+ * that already gates on `live_checkout_busy`), so a dirty tree or a
+ * contaminated local base leaves the item pending
+ * (`_pendingReason: 'live_checkout_dirty'` / `'live_checkout_stale_base'`)
+ * instead of burning a retry (dirty, pre-fix behavior) or failing
+ * non-retryably on the first hit (stale-base, pre-fix behavior). The
+ * in-spawn guards documented above (inside `prepareLiveCheckout`, surfaced by
+ * spawnAgent) remain in place as a defense-in-depth fallback for the race
+ * window between this probe and the actual git operations inside spawnAgent
+ * — they should now fire rarely, as the exception path rather than the
+ * common path.
  */
 
 'use strict';
@@ -1205,6 +1220,130 @@ async function prepareLiveCheckout(opts = {}) {
   return { ok: true, branch: branchName, created: true, originalRef, originalRefType };
 }
 
+/**
+ * checkLiveCheckoutDirty — W-mrcifup2000c218a
+ *
+ * Cheap, read-only, NON-MUTATING pre-dispatch probe for a dirty live-checkout
+ * working tree. Mirrors prepareLiveCheckout's Step 1 dirty check (same
+ * `git status --porcelain=v1 -b` command, same porcelain parsing, same
+ * auto-cleanable-artifact allowance) but never deletes anything and never
+ * throws on a git failure — callers use this at ALLOCATION time (before a WI
+ * is dispatched) to decide whether to leave the item pending
+ * (`_pendingReason: 'live_checkout_dirty'`) instead of spawning it only to
+ * have prepareLiveCheckout refuse it after the fact.
+ *
+ * Intentionally permissive on ambiguity: if the `git status` probe itself
+ * fails (transient error), or every dirty entry is an auto-cleanable build
+ * artifact (which prepareLiveCheckout's spawn-time auto-clean step will
+ * delete before it ever re-checks dirtiness), this reports `dirty:false` so
+ * allocation does not block on a condition that resolves itself inside the
+ * spawn path. The in-spawn guard (engine.js ~line 2617) remains the
+ * authoritative check for the race window between this probe and the actual
+ * git operations inside spawnAgent.
+ *
+ * @param {object} opts
+ * @param {string} opts.localPath        operator checkout root (git cwd)
+ * @param {object} [opts.gitOpts]        extra execFile opts merged into cwd
+ * @param {boolean} [opts.skipDirtyCheck] #522: opt out entirely (GVFS repos)
+ * @param {function} [opts._git]         test seam; defaults to shellSafeGit
+ * @returns {Promise<{dirty:boolean, dirtyFiles?:string[], branchInfo?:string, autoCleanable?:boolean, error?:string}>}
+ */
+async function checkLiveCheckoutDirty(opts = {}) {
+  const { localPath, gitOpts, skipDirtyCheck, _git } = opts;
+  if (skipDirtyCheck) return { dirty: false };
+  if (!localPath || typeof localPath !== 'string') return { dirty: false };
+  const git = (typeof _git === 'function') ? _git : shared.shellSafeGit;
+  const baseOpts = { cwd: localPath, maxBuffer: LIVE_CHECKOUT_GIT_MAX_BUFFER, ...(gitOpts || {}) };
+  let statusRaw;
+  try {
+    statusRaw = await git(['status', '--porcelain=v1', '-b'], baseOpts);
+  } catch (e) {
+    // A probe failure is not proof of a dirty tree — don't block allocation
+    // on it. spawnAgent's own dirty check (with its LIVE_CHECKOUT_FAILED
+    // classification) is the authoritative fallback for a real git failure.
+    return { dirty: false, error: e.message };
+  }
+  const lines = (typeof statusRaw === 'string' ? statusRaw : '')
+    .split(/\r?\n/)
+    .map((line) => line.replace(/\s+$/, ''))
+    .filter((line) => line.length > 0);
+  const branchInfo = lines.find((line) => line.startsWith('## ')) || '';
+  const dirtyFiles = lines.filter((line) => !line.startsWith('## '));
+  if (dirtyFiles.length === 0) return { dirty: false, branchInfo };
+  const cleanablePaths = _collectAutoCleanablePaths(dirtyFiles);
+  if (cleanablePaths) return { dirty: false, branchInfo, autoCleanable: true };
+  return { dirty: true, dirtyFiles, branchInfo };
+}
+
+/**
+ * checkLiveCheckoutStaleBase — W-mrcifup2000c218a
+ *
+ * Cheap, read-only, NON-MUTATING, fetch-free pre-dispatch probe for the
+ * STALE-BASE GUARD condition (W-mr98op8w000ma4ad). Mirrors prepareLiveCheckout's
+ * Step 4d divergence check (same `git rev-list --count origin/<mainRef>..<mainRef>`
+ * comparison) so allocation-time callers can detect a contaminated local base
+ * BEFORE dispatching, instead of burning a non-retryable terminal failure after
+ * the fact. Never fetches, never resets, never mutates anything.
+ *
+ * Scope mirrors prepareLiveCheckout exactly: only relevant when a NEW branch
+ * would be forked (an existing local `branchName` checkout is unaffected by
+ * this class of contamination), when HEAD sits on `mainRef` itself, and when
+ * `origin/<mainRef>` is present locally to compare against. `allowNonMainBase`
+ * (PR-targeted / shared-branch continuations) short-circuits to `stale:false`
+ * — those dispatches intentionally build on a non-main branch and opt out of
+ * this guard, same as prepareLiveCheckout.
+ *
+ * @param {object} opts
+ * @param {string} opts.localPath          operator checkout root (git cwd)
+ * @param {string} opts.mainRef            project base branch name
+ * @param {object} [opts.gitOpts]          extra execFile opts merged into cwd
+ * @param {boolean} [opts.allowNonMainBase] opt out (PR-targeted/shared-branch)
+ * @param {function} [opts._git]           test seam; defaults to shellSafeGit
+ * @returns {Promise<{stale:boolean, ahead?:number, mainRef?:string, localMainSha?:string, originMainSha?:string}>}
+ */
+async function checkLiveCheckoutStaleBase(opts = {}) {
+  const { localPath, mainRef, gitOpts, allowNonMainBase, _git } = opts;
+  if (allowNonMainBase) return { stale: false };
+  if (!localPath || typeof localPath !== 'string') return { stale: false };
+  if (!mainRef || typeof mainRef !== 'string') return { stale: false };
+  const git = (typeof _git === 'function') ? _git : shared.shellSafeGit;
+  const baseOpts = { cwd: localPath, maxBuffer: LIVE_CHECKOUT_GIT_MAX_BUFFER, ...(gitOpts || {}) };
+  let curBranch = '';
+  try {
+    const raw = await git(['symbolic-ref', '-q', '--short', 'HEAD'], baseOpts);
+    curBranch = (typeof raw === 'string' ? raw : '').trim();
+  } catch {
+    // Detached HEAD or probe error — out of scope for this guard (the
+    // mid-operation/detached-HEAD preflight is a separate concern, still
+    // handled in-spawn only).
+    return { stale: false };
+  }
+  if (!curBranch || curBranch !== mainRef) return { stale: false };
+  let originMainSha = '';
+  try {
+    const originRaw = await git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${mainRef}`], baseOpts);
+    originMainSha = (typeof originRaw === 'string' ? originRaw : '').trim();
+  } catch {
+    return { stale: false }; // no remote-tracking ref → ambiguous, skip (local-only/no-remote repo)
+  }
+  if (!originMainSha) return { stale: false };
+  let aheadCount = -1;
+  try {
+    const cntRaw = await git(['rev-list', '--count', `refs/remotes/origin/${mainRef}..${mainRef}`], baseOpts);
+    aheadCount = parseInt((typeof cntRaw === 'string' ? cntRaw : '').trim(), 10);
+    if (Number.isNaN(aheadCount)) aheadCount = -1;
+  } catch {
+    aheadCount = -1; // rev-list failed → transient/ambiguous; don't block on it
+  }
+  if (aheadCount <= 0) return { stale: false };
+  let localMainSha = '';
+  try {
+    const localRaw = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${mainRef}`], baseOpts);
+    localMainSha = (typeof localRaw === 'string' ? localRaw : '').trim();
+  } catch { /* best-effort — informational only */ }
+  return { stale: true, ahead: aheadCount, mainRef, localMainSha, originMainSha };
+}
+
 /**
  * restoreLiveCheckoutAtDispatchEnd — P-d9e6b2c4
  *
@@ -1723,6 +1862,8 @@ async function maybeRestoreLiveCheckoutFromRecord(opts = {}) {
 
 module.exports = {
   prepareLiveCheckout,
+  checkLiveCheckoutDirty,
+  checkLiveCheckoutStaleBase,
   restoreLiveCheckoutAtDispatchEnd,
   resolveLiveCheckoutAutoStash,
   performLiveCheckoutAutoStash,