@yemi33/minions 0.1.2355 → 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/settings.js

@@ -342,17 +342,31 @@ async function openSettings() {
           '<option value="off"' + (autoStashRaw === 'off' ? ' selected' : '') + '>Off — fail on dirty tree</option>' +
         '</select>' +
         '<div style="font-size:var(--text-xs);color:var(--muted);margin-top:2px;line-height:1.4">Live mode only. On = `git stash push --include-untracked` a dirty tree before dispatch instead of failing; the engine never pops the stash (run `git stash pop` manually). Overrides the fleet-wide setting under Worktrees.</div>' +
-      '</div>';
+        '</div>';
+    // W-mrchrfe100067d3a — per-project explicit allowlist of secondary repo
+    // scopes this project's checkout is also allowed to track PRs for (e.g.
+    // minions-opg's checkout has both an `origin` remote → opg-microsoft/minions
+    // and a `yemi33` remote → yemi33/minions for backport work — see
+    // CLAUDE.md "Remotes"). Comma-separated canonical scope strings
+    // (`github:owner/repo` or `ado:org/project/repo`); parsed + validated
+    // server-side by shared.validateAdditionalRepoScopes on save.
+    var additionalScopesSearch = 'additional repo scopes multi-scope dual-remote backport yemi33';
+    var additionalScopesBlock = '<div data-search="' + escHtml(additionalScopesSearch) + '" style="margin-bottom:6px">' +
+        settingsField('Additional repo scopes (secondary remotes)', 'set-additionalRepoScopes-' + p.name,
+          (Array.isArray(p.additionalRepoScopes) ? p.additionalRepoScopes : []).join(', '), '',
+          'Comma-separated canonical scopes this project\'s PRs may ALSO belong to (e.g. "github:yemi33/minions"). Explicit opt-in allowlist only — PRs matching one of these scopes are treated as compatible for auto-review/auto-fix without being flagged pr_scope_mismatch. Leave empty for single-scope projects.') +
+        '</div>';
     return '<div data-settings-project="' + escHtml(p.name) + '" data-search="project ' + escHtml(p.name.toLowerCase()) + '" style="border:1px solid var(--border);border-radius:6px;padding:10px 12px;margin-bottom:12px">' +
-      '<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:8px">' +
-        '<div style="font-size:var(--text-md);font-weight:600">' + escHtml(p.name) + '</div>' +
-        '<button onclick="MinionsSettings.removeProject(\'' + escHtml(p.name) + '\')" style="font-size:var(--text-xs);padding:2px 8px;background:transparent;color:var(--red);border:1px solid var(--red);border-radius:3px;cursor:pointer">Remove</button>' +
-      '</div>' +
-      pathRow +
-      branchGrid +
-      worktreeModeBlock +
-      autoStashBlock +
-      driftNote +
+        '<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:8px">' +
+          '<div style="font-size:var(--text-md);font-weight:600">' + escHtml(p.name) + '</div>' +
+          '<button onclick="MinionsSettings.removeProject(\'' + escHtml(p.name) + '\')" style="font-size:var(--text-xs);padding:2px 8px;background:transparent;color:var(--red);border:1px solid var(--red);border-radius:3px;cursor:pointer">Remove</button>' +
+        '</div>' +
+        pathRow +
+        branchGrid +
+        worktreeModeBlock +
+        autoStashBlock +
+        additionalScopesBlock +
+        driftNote +
       '<div style="display:flex;flex-direction:column;gap:6px;margin-top:8px">' +
       settingsToggle('Discover from PRs', 'set-ws-prs-' + p.name, p.workSources.pullRequests.enabled, 'Discovery gate: scan repo for open PRs and surface them as review tasks. Independent of ADO/GitHub polling — does not affect already-tracked PRs.') +
       settingsToggle('Discover from Work Items', 'set-ws-wi-' + p.name, p.workSources.workItems.enabled, 'Auto-discover work from ADO/GitHub work items') +
@@ -1257,12 +1271,18 @@ async function saveSettings() {
       const autoStashInput = document.getElementById('set-liveCheckoutAutoStash-' + p.name);
       const autoStashRaw = autoStashInput ? autoStashInput.value : '';
       const autoStashValue = autoStashRaw === 'on' ? true : autoStashRaw === 'off' ? false : null;
+      // W-mrchrfe100067d3a — parse the comma-separated scope list back into an
+      // array; empty string → null (clears the override server-side).
+      const additionalScopesInput = document.getElementById('set-additionalRepoScopes-' + p.name);
+      const additionalScopesRaw = additionalScopesInput ? additionalScopesInput.value : '';
+      const additionalRepoScopes = additionalScopesRaw.split(',').map(function(s) { return s.trim(); }).filter(Boolean);
       return {
         name: p.name,
         mainBranch: mainBranchValue || null,
         checkoutMode: checkoutMode,
         liveValidation: liveValidation,
         liveCheckoutAutoStash: autoStashValue,
+        additionalRepoScopes: additionalRepoScopes.length > 0 ? additionalRepoScopes : null,
         workSources: {
           pullRequests: { enabled: document.getElementById('set-ws-prs-' + p.name)?.checked ?? true },
           workItems: { enabled: document.getElementById('set-ws-wi-' + p.name)?.checked ?? true }

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}`,
           });
@@ -11184,6 +11225,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // tri-state dropdown. Undefined means "use fleet default"
           // (engine.liveCheckoutAutoStash); only an explicit boolean overrides.
           liveCheckoutAutoStash: (typeof p.liveCheckoutAutoStash === 'boolean') ? p.liveCheckoutAutoStash : undefined,
+          // W-mrchrfe100067d3a — surface the per-project secondary-repo
+          // allowlist so the Settings → Projects UI can pre-fill / edit it.
+          // Empty array when unset (never null) so the UI can render a
+          // simple add/remove list without an extra null-check.
+          additionalRepoScopes: shared.getProjectAdditionalPrScopes(p),
           workSources: {
             pullRequests: { enabled: p.workSources?.pullRequests?.enabled !== false, cooldownMinutes: p.workSources?.pullRequests?.cooldownMinutes ?? 30 },
             workItems: { enabled: p.workSources?.workItems?.enabled !== false, cooldownMinutes: p.workSources?.workItems?.cooldownMinutes ?? 0 }
@@ -11668,6 +11714,24 @@ What would you like to discuss or change? When you're happy, say "approve" and I
               proj.liveCheckoutAutoStash = !!rawStash;
             }
           }
+          // W-mrchrfe100067d3a — per-project explicit allowlist of secondary
+          // repo scopes (e.g. minions-opg's checkout also legitimately opens
+          // PRs against yemi33/minions for backport work — see CLAUDE.md
+          // "Remotes"). Empty array / null / '' clears the override (falls
+          // back to single-scope matching); any other value flows through
+          // shared.validateAdditionalRepoScopes, which throws HTTP 400 on a
+          // non-array or malformed scope string (errors propagate to the
+          // outer catch below via e.statusCode/e.message).
+          if (Object.prototype.hasOwnProperty.call(update, 'additionalRepoScopes')) {
+            const rawScopes = update.additionalRepoScopes;
+            if (rawScopes === '' || rawScopes === null || (Array.isArray(rawScopes) && rawScopes.length === 0)) {
+              delete proj.additionalRepoScopes;
+            } else {
+              const validatedScopes = shared.validateAdditionalRepoScopes(rawScopes);
+              if (validatedScopes === undefined) delete proj.additionalRepoScopes;
+              else proj.additionalRepoScopes = validatedScopes;
+            }
+          }
         }
       }
 
@@ -14144,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:
@@ -14707,7 +14807,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Settings
     { method: 'GET', path: '/api/settings', desc: 'Return current engine + claude + routing config', handler: handleSettingsRead },
-    { method: 'POST', path: '/api/settings', desc: 'Update engine + claude + agent + projects config', params: 'engine?, claude?, agents?, projects? (per-project: checkoutMode, liveValidation, mainBranch, workSources)', handler: handleSettingsUpdate },
+    { method: 'POST', path: '/api/settings', desc: 'Update engine + claude + agent + projects config', params: 'engine?, claude?, agents?, projects? (per-project: checkoutMode, liveValidation, mainBranch, workSources, additionalRepoScopes)', handler: handleSettingsUpdate },
     { method: 'POST', path: '/api/settings/routing', desc: 'Update routing.md', params: 'content', handler: handleSettingsRouting },
     { method: 'POST', path: '/api/settings/reset', desc: 'Reset engine + claude + agent settings to defaults', handler: handleSettingsReset },
 

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/db/migrations/016-pr-mirror-hash.js

@@ -0,0 +1,31 @@
+// engine/db/migrations/016-pr-mirror-hash.js
+//
+// Fix for opg-microsoft/minions#759: pull-requests-store.js tracked its
+// JSON-mirror "last known hash" per scope in an in-memory-only Map
+// (`_lastMirrorHashByScope`). That state resets to empty on every engine
+// restart, so the very first touch of a scope after a restart has no way to
+// tell "SQL and JSON already agree" from "JSON just changed out from under
+// us" — it falls back to a lastHash==null heuristic that only partially
+// covers the case. Combined with a restart landing mid-flight of another
+// process's mirror write, a stale JSON snapshot could get treated as
+// canonical and used to rebuild (blindly DELETE + reinsert) the SQL table
+// for that scope, permanently dropping any rows not present in the stale
+// file.
+//
+// This table makes the mirror-hash durable across restarts: it is now the
+// single, persisted cross-process source of truth for "what mirror state
+// did the store last agree with", instead of a per-process cache that goes
+// blank on every restart.
+module.exports = {
+  version: 16,
+  description: 'pr_mirror_hashes — persist pull-requests.json mirror-hash across restarts (#759)',
+  up(db) {
+    db.exec(`
+      CREATE TABLE pr_mirror_hashes (
+        scope       TEXT PRIMARY KEY,
+        hash        TEXT NOT NULL,
+        updated_at  INTEGER NOT NULL
+      );
+    `);
+  },
+};