@yemi33/minions 0.1.2306 → 0.1.2308

package/engine/shared.js

@@ -1946,6 +1946,86 @@ function mutateControl(mutator) {
   }, { defaultValue: { state: 'stopped', pid: null }, skipWriteIfUnchanged: true });
 }
 
+// ── Crash-loop detection (W-mr2c46590003e3ee) ──────────────────────────────
+// Three independent mechanisms can respawn a dead/frozen engine process:
+// engine/supervisor.js#checkEngine / #checkEngineHung, engine/watchdog.js
+// (OS-scheduled external recovery), and dashboard.js's in-process 30s
+// watchdog. None of them counted or throttled repeated crashes, so a genuine
+// crash-loop (engine dying every few minutes) silently self-healed forever
+// with no human-visible signal — see the 2026-07-01 00:20-00:30 incident
+// (4 respawns in ~5 minutes, notes/inbox/dallas-W-mr2azk6i000y06e0-*.md).
+//
+// recordEngineRespawn() gives all three mechanisms a single rolling counter
+// persisted in control.json so it survives process restarts: every call
+// appends {ts, source}, prunes entries older than CRASH_LOOP_WINDOW_MS, and
+// once the count within the window reaches CRASH_LOOP_THRESHOLD it flips a
+// dashboard-visible `control.crashLoopAlert` flag and writes a deduped
+// (one-per-day) inbox note.
+//
+// Callers MUST invoke this only at the point an actual respawn action is
+// taken — not on every health-check tick. The existing
+// RESPAWN_IN_PROGRESS_WINDOW_MS / post-spawn-grace guards already in each
+// mechanism prevent two watchers from double-spawning for the same crash, so
+// recording only real spawns keeps a single crash from being counted 2-3x
+// across the three watchers.
+const CRASH_LOOP_WINDOW_MS = Number(process.env.MINIONS_CRASH_LOOP_WINDOW_MS) || 10 * 60 * 1000; // 10 min
+const CRASH_LOOP_THRESHOLD = Number(process.env.MINIONS_CRASH_LOOP_THRESHOLD) || 3;
+
+function recordEngineRespawn(source) {
+  const now = Date.now();
+  let crashLoop = false;
+  let count = 1;
+  let windowEntries = [];
+  try {
+    mutateControl((control) => {
+      const prior = Array.isArray(control.engineRespawns) ? control.engineRespawns : [];
+      const entries = prior
+        .filter(e => e && Number.isFinite(e.ts) && (now - e.ts) <= CRASH_LOOP_WINDOW_MS)
+        .concat([{ ts: now, source: String(source || 'unknown') }]);
+      // Defensive cap — the window filter above already bounds this in
+      // practice, but guards against unbounded growth under clock skew or an
+      // operator-widened window.
+      control.engineRespawns = entries.slice(-50);
+      windowEntries = control.engineRespawns;
+      count = windowEntries.length;
+      if (count >= CRASH_LOOP_THRESHOLD) {
+        crashLoop = true;
+        control.crashLoopAlert = {
+          count,
+          windowMs: CRASH_LOOP_WINDOW_MS,
+          firstAt: new Date(windowEntries[0].ts).toISOString(),
+          lastAt: new Date(now).toISOString(),
+          sources: windowEntries.map(e => e.source),
+        };
+      } else if (control.crashLoopAlert) {
+        // Window rolled off past incidents — clear a stale alert so the
+        // dashboard doesn't keep showing a resolved crash-loop forever.
+        delete control.crashLoopAlert;
+      }
+      return control;
+    });
+  } catch (e) {
+    log('warn', `recordEngineRespawn: control.json update failed: ${e.message}`);
+  }
+
+  if (crashLoop) {
+    try {
+      const lines = windowEntries.map(e => `- ${e.source} @ ${new Date(e.ts).toISOString()}`).join('\n');
+      const body = `# Engine crash-loop detected\n\n` +
+        `${count} engine respawns in the last ${Math.round(CRASH_LOOP_WINDOW_MS / 60000)} minutes ` +
+        `(threshold: ${CRASH_LOOP_THRESHOLD}).\n\n` +
+        `Respawns:\n${lines}\n\n` +
+        `The engine keeps self-healing (each respawn succeeded) but is crashing repeatedly — ` +
+        `investigate \`engine/engine-stdio.log\` around the timestamps above before this becomes ` +
+        `a silent outage.\n`;
+      writeToInbox('engine', 'crash-loop-detected', body, null, { severity: 'critical' });
+    } catch (e) {
+      log('warn', `recordEngineRespawn: inbox alert failed: ${e.message}`);
+    }
+  }
+  return { count, crashLoop };
+}
+
 // W-mp60tw0u000j3931: Lock-safe read-modify-write for engine/state.json — the
 // persistent cross-restart engine-level state file (migration markers,
 // one-shot reconciliation versions, etc.). Mirrors mutateControl's shape.
@@ -2904,6 +2984,14 @@ const ENGINE_DEFAULTS = {
   // & Review Loop, or set `engine.autoFixPaused: true` in config.json.
   autoFixPaused: false, // hard-stop kill-switch / master override (see comment above)
   autoConsolidateMemory: false, // opt-in: periodically spawn engine/kb-sweep-runner.js from the tick loop (4h cadence). Inbox→notes consolidation already runs every tick via consolidateInbox; this flag only controls the KB sweep.
+  // W-mqtvnnj1000357fa — fleet-wide fallback for live-checkout auto-stash. When
+  // true, a dirty live-checkout tree is `git stash push --include-untracked`'d
+  // before dispatch instead of failing with FAILURE_CLASS.LIVE_CHECKOUT_DIRTY,
+  // so dispatch proceeds without manual operator intervention. Per-project
+  // `project.liveCheckoutAutoStash` overrides this (resolveLiveCheckoutAutoStash).
+  // The engine never auto-pops the stash — the operator runs `git stash pop`.
+  // Default false so a fresh install behaves identically to before this knob.
+  liveCheckoutAutoStash: false,
   prNoOpFixPauseAttempts: 2, // pause one PR automation cause after repeated no-op fixes for unchanged evidence
   quarantineAutoRecoveryMax: 2, // #2996 follow-up: cap on auto-flipping WORKTREE_DIRTY/WORKTREE_DIVERGENT failures back to pending (the quarantine is self-healing so the next dispatch starts clean; the cap prevents infinite loops if quarantine itself keeps failing).
   // W-mq5n1zx5 — Layer 1a/2b: harden the quarantine rename path against
@@ -4556,6 +4644,7 @@ const FAILURE_CLASS = {
   LIVE_CHECKOUT_FAILED: 'live-checkout-failed', // #305 (live-checkout dispatch mode): prepareLiveCheckout THREW before agent spawn (helper guard, ref validation, or a transient `git status`/`rev-parse`/`checkout` failure) — distinct from the confirmed-dirty result (LIVE_CHECKOUT_DIRTY) which the helper returns, not throws. A thrown error is NOT proof the tree is dirty, so it must not be over-classified as dirty. Retryable with bounded backoff (NOT in dispatch.js neverRetry): racy branch-lock handoff, just-finished sibling dispatch, or transient git errors frequently clear on the next attempt; the engine auto-retries up to ENGINE_DEFAULTS.maxRetries before giving up. Genuinely terminal underlying reasons (auth, validation) still short-circuit via the reason-string check in isRetryableFailureReason.
   LIVE_CHECKOUT_MID_OPERATION: 'live-checkout-mid-operation', // P-a7f3c1d9 (live-checkout dispatch mode): spawnAgent could not switch/create the target branch in project.localPath because the operator tree is mid-operation — an in-progress merge/rebase/cherry-pick/bisect or a detached HEAD. Distinct from LIVE_CHECKOUT_DIRTY (uncommitted changes): here the tree may be clean but the branch op cannot proceed. Engine refuses to spawn (it never runs `git reset`/`git clean`/`git rebase --abort` against the operator tree). Non-retryable — operator must finish or abort the in-progress operation, or checkout a branch, before re-dispatch.
   LIVE_CHECKOUT_BLOB_FETCH: 'live-checkout-blob-fetch', // PL-live-checkout-reliability-hardening (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because the tree could not be materialized — on a Scalar/GVFS-managed ADO partial (blobless) clone, switching onto a branch whose tree differs from HEAD hydrates the changed paths' blobs through the GVFS cache server (`*.gvfscache.dev.azure.com`), a different endpoint than the main git remote that receives NO auth in the headless engine shell, so the fetch fails DETERMINISTICALLY. Distinct from LIVE_CHECKOUT_FAILED (transient) because retrying reproduces it identically — surfaced once as an operator-actionable refusal instead of retry-storming to the cap. Non-retryable — the operator hydrates the branch once with their own credentials (`git checkout <branch>` interactively, or `scalar prefetch` / `git -C <repo> fetch`), then re-dispatches. The engine NEVER forces, resets, cleans, or stashes the operator tree, and best-effort switches HEAD back to the original ref so the tree is not stranded half-populated.
+  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.
   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.
@@ -9061,7 +9150,7 @@ module.exports = {
   assertStateFileSize,
   withFileLock,
   mutateJsonFileLocked,
-  mutateControl,
+  mutateControl, recordEngineRespawn,
   mutateEngineState, // W-mp60tw0u000j3931
   readEngineState,   // W-mp60tw0u000j3931
   mutateCooldowns,

package/engine/supervisor.js

@@ -45,6 +45,17 @@ const MINIONS_DIR = path.resolve(__dirname, '..');
 function _sharedOrNull() {
   try { return require('./shared'); } catch { return null; }
 }
+// Crash-loop counter (W-mr2c46590003e3ee) — best-effort. shared.js owns the
+// counter/threshold/inbox-alert logic (engine/shared.js#recordEngineRespawn)
+// so supervisor.js, engine/watchdog.js, and dashboard.js's in-process
+// watchdog all feed the same rolling window in control.json instead of each
+// keeping (and silently ignoring) their own. Falls through to a no-op when
+// shared.js can't load, matching this file's existing fail-open posture.
+function _recordCrashLoopRespawn(source) {
+  const shared = _sharedOrNull();
+  if (!shared || typeof shared.recordEngineRespawn !== 'function') return;
+  try { shared.recordEngineRespawn(source); } catch { /* best-effort */ }
+}
 function _engineDir() { return _sharedOrNull()?.ENGINE_DIR || __dirname; }
 const STATIC_ENGINE_DIR = __dirname; // for require-time paths that can't be lazy
 function CONTROL_PATH_FN() { return path.join(_engineDir(), 'control.json'); }
@@ -458,6 +469,7 @@ function checkEngine(now) {
   reapStrayProcesses(path.join(MINIONS_DIR, 'engine.js'), 'engine');
   const newPid = spawnEngine();
   _lastEngineRespawnAt = now;
+  _recordCrashLoopRespawn('supervisor:dead-pid');
   console.log(`[supervisor] Engine respawned (new PID: ${newPid})`);
 }
 
@@ -492,6 +504,7 @@ function checkEngineHung(now) {
   reapStrayProcesses(path.join(MINIONS_DIR, 'engine.js'), 'engine');
   const newPid = spawnEngine();
   _lastEngineRespawnAt = now;
+  _recordCrashLoopRespawn('supervisor:stale-heartbeat');
   console.log(`[supervisor] Engine restarted due to stale heartbeat (new PID: ${newPid})`);
 }
 

package/engine/watchdog.js

@@ -249,6 +249,16 @@ async function tick(opts) {
     });
     if (child && typeof child.unref === 'function') child.unref();
     logLine(minionsHome, `spawned minions ${action} pid=${child && child.pid} (detached)`);
+    // Crash-loop counter (W-mr2c46590003e3ee) — best-effort, injected so this
+    // module stays dependency-free of shared.js (matches isStopIntentSet /
+    // confirmPortUp above). Caller (bin/minions.js) wires opts.recordRespawn
+    // to shared.recordEngineRespawn so all three engine-respawn mechanisms
+    // (supervisor.js, this watchdog, dashboard.js's in-process watchdog)
+    // share one rolling window in control.json instead of each silently
+    // ignoring repeated crashes.
+    if (typeof opts.recordRespawn === 'function') {
+      try { opts.recordRespawn(`watchdog:${action}`); } catch { /* best-effort */ }
+    }
     return { healthy: false, action, spawnedPid: child && child.pid };
   } catch (err) {
     logLine(minionsHome, `FAILED to spawn minions ${action}: ${err && err.message || err}`);

package/engine.js

@@ -1974,6 +1974,43 @@ function _applyAgentTempEnv(childEnv, project) {
   } catch { /* leave inherited TEMP untouched */ }
 }
 
+// W-mr28h2j2000y0de1 review (calebt_microsoft, 2026-07-01): "classify as
+// non-retryable" alone leaves the operator to manually clean up every time.
+// Before refusing, ATTEMPT to actually resolve the conflict — remove the
+// conflicting worktree and let the caller retry the checkout — but ONLY when
+// it is safe to do so. Every one of these gates must pass or we leave the
+// conflicting worktree untouched and fall back to the existing refusal:
+//   1. conflictPath resolves inside THIS project's configured worktreeRoot —
+//      the standard location for engine-created worktrees. Anything outside
+//      it might be a human's own tree; shared.removeWorktree's containment
+//      check would refuse it anyway, but we check first for a clearer reason.
+//   2. it carries the engine ownership marker (shared.hasWorktreeOwnerMarker)
+//      — a hand-made worktree (`git worktree add /tmp/foo …`) has no marker.
+//   3. shared.removeWorktree succeeds. It independently refuses to touch a
+//      worktree with a LIVE dispatch running inside it (isWorktreePathLive,
+//      fails open) and refuses real-repo-root / non-linked-worktree paths.
+// Returns { removed, reason } for alert/log enrichment either way.
+function _tryAutoResolveLiveCheckoutWorktreeConflict({ conflictPath, gitRoot, engineConfig, log }) {
+  try {
+    const _wtRoot = path.resolve(gitRoot, (engineConfig && engineConfig.worktreeRoot) || ENGINE_DEFAULTS.worktreeRoot);
+    const _resolvedConflict = path.resolve(conflictPath);
+    if (_resolvedConflict !== _wtRoot && !_resolvedConflict.startsWith(_wtRoot + path.sep)) {
+      return { removed: false, reason: 'outside the configured worktreeRoot — not engine-managed, left untouched' };
+    }
+    if (!shared.hasWorktreeOwnerMarker(_resolvedConflict)) {
+      return { removed: false, reason: 'no engine ownership marker — likely human-created, left untouched' };
+    }
+    const _removed = shared.removeWorktree(_resolvedConflict, gitRoot, _wtRoot);
+    if (!_removed) {
+      return { removed: false, reason: 'shared.removeWorktree declined (live dispatch active inside it, real-repo guard, or removal failure — see engine logs)' };
+    }
+    return { removed: true, reason: 'removed stale engine-owned worktree' };
+  } catch (e) {
+    log('warn', `live-checkout: auto-resolve threw: ${e.message}`);
+    return { removed: false, reason: `auto-resolve threw: ${e.message}` };
+  }
+}
+
 async function spawnAgent(dispatchItem, config) {
   const { id, agent: agentId, type, meta } = dispatchItem;
   // Resolve prompt — prefers sidecar file when dispatchItem._promptFile is set
@@ -2420,6 +2457,56 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // ── Auto-stash a dirty live-checkout tree (W-mqtvnnj1000357fa) ──────────
+    // When the tree is dirty AND auto-stash is enabled (per-project field wins,
+    // else engine fleet-wide fallback), `git stash push --include-untracked` the
+    // operator's changes so dispatch can proceed instead of failing with
+    // FAILURE_CLASS.LIVE_CHECKOUT_DIRTY. The full flow (stash → re-preflight →
+    // clear retry stamp → operator inbox note) lives in live-checkout.js to keep
+    // spawnAgent lean; here we only handle the engine-specific outcomes. The
+    // engine NEVER pops the stash automatically (operator choice).
+    // NOTE: the helper gates on `liveResult.reason === 'dirty'` internally so the
+    // confirmed-dirty refusal `if` below remains the first textual match for that
+    // dirty-reason check in this file.
+    const _autoStash = await _liveCheckout.applyLiveCheckoutAutoStash({
+      liveResult: _liveResult,
+      project,
+      engine: engineConfig,
+      localPath: cwd,
+      branchName,
+      mainRef: _liveMainRef,
+      gitOpts: _gitOpts,
+      dispatchId: id,
+      wiId: _wiIdForAlert,
+      log: (msg, lvl) => log(lvl || 'info', msg),
+      clearDirtyStamp: () => {
+        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_dirty') delete wi._pendingReason;
+            return data;
+          });
+        }
+      },
+      writeStashNote: (key, body) => writeInboxAlert(key, body),
+    });
+    if (_autoStash.outcome === 'threw') {
+      const stashLiveErr = _autoStash.error;
+      log('error', `spawnAgent: live-checkout helper threw after auto-stash for ${id}: ${stashLiveErr.message}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        `live-checkout failed: ${stashLiveErr.message}`.slice(0, 800),
+        'Live-checkout helper threw after auto-stash (not proof of a dirty tree). Auto-retried with bounded backoff; transient git/branch-lock state usually clears on the next attempt.',
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_FAILED },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
+    _liveResult = _autoStash.liveResult;
     if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'dirty') {
       const _dirtyFiles = Array.isArray(_liveResult.dirtyFiles) ? _liveResult.dirtyFiles : [];
       const _branchInfo = typeof _liveResult.branchInfo === 'string' ? _liveResult.branchInfo : '';
@@ -2637,6 +2724,109 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // W-mr28h2j2000y0de1: worktree-conflict refusal. The existing-branch
+    // `git checkout` refused because the target 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). This is a STRUCTURAL conflict — it does NOT clear on
+    // retry, ever, until a human or the engine removes/reassigns the other
+    // worktree — so it gets its own non-retryable FAILURE_CLASS instead of
+    // LIVE_CHECKOUT_FAILED's bounded retry-storm. prepareLiveCheckout already
+    // best-effort switched HEAD back to the operator's original ref.
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'worktree-conflict') {
+      // W-mr28h2j2000y0de1 review (calebt_microsoft): try to actually RESOLVE
+      // the conflict before refusing. Only proceeds when the conflicting
+      // worktree is engine-owned and not live-in-use (see
+      // _tryAutoResolveLiveCheckoutWorktreeConflict); on success, retry the
+      // checkout once and fall through to the normal success path below.
+      const _conflictPathForResolve = typeof _liveResult.conflictingWorktreePath === 'string' && _liveResult.conflictingWorktreePath
+        ? _liveResult.conflictingWorktreePath
+        : null;
+      if (_conflictPathForResolve) {
+        const _resolveOutcome = _tryAutoResolveLiveCheckoutWorktreeConflict({
+          conflictPath: _conflictPathForResolve, gitRoot: cwd, engineConfig, log,
+        });
+        if (_resolveOutcome.removed) {
+          log('info', `live-checkout: auto-resolved worktree conflict — ${_resolveOutcome.reason} at ${_conflictPathForResolve}; retrying checkout`);
+          try {
+            _liveResult = await _liveCheckout.prepareLiveCheckout({
+              localPath: cwd,
+              branchName,
+              mainRef: _liveMainRef,
+              gitOpts: _gitOpts,
+              dispatchId: id,
+              wiId: _wiIdForAlert,
+              skipDirtyCheck: !!project.skipLiveCheckoutDirtyCheck,
+              log: (msg, lvl) => log(lvl || 'info', msg),
+            });
+          } catch (retryErr) {
+            log('warn', `live-checkout: retry after auto-resolve threw: ${retryErr.message}`);
+            _liveResult = { ok: false, reason: 'worktree-conflict', conflictingWorktreePath: _conflictPathForResolve, message: retryErr.message };
+          }
+        } else {
+          log('info', `live-checkout: worktree conflict at ${_conflictPathForResolve} not auto-resolved (${_resolveOutcome.reason})`);
+        }
+      }
+    }
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'worktree-conflict') {
+      const _conflictMsg = typeof _liveResult.message === 'string' ? _liveResult.message : '';
+      const _conflictPath = typeof _liveResult.conflictingWorktreePath === 'string' && _liveResult.conflictingWorktreePath
+        ? _liveResult.conflictingWorktreePath
+        : null;
+      const _pathPhrase = _conflictPath ? `\`${_conflictPath}\`` : 'an unknown location';
+      const _alertBody = [
+        '# Live-checkout blocked: branch already used by another worktree',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**Branch:** ${branchName}`,
+        `**Conflicting worktree:** ${_conflictPath || '(unknown location)'}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        `The engine could not switch \`${cwd}\` onto \`${branchName}\` because that branch is already checked out in another worktree at ${_pathPhrase}. This is a structural conflict — **it will NOT clear on retry**. Your tree was left on its original ref (the engine never forces, resets, or cleans it).`,
+        ...(_conflictMsg ? ['', '```', _conflictMsg, '```'] : []),
+        '',
+        '## Recovery',
+        '',
+        `Pick ONE, depending on whether the other worktree still holds work you need:`,
+        '',
+        `1. **If that worktree is stale / no longer needed** — remove it to free the branch for the live checkout:`,
+        '',
+        '```',
+        `git worktree remove ${_conflictPath || '<path>'}`,
+        `# or, if it has uncommitted changes you are SURE you can discard (this DISCARDS that WIP):`,
+        `git worktree remove --force ${_conflictPath || '<path>'}`,
+        '```',
+        '',
+        `2. **If that worktree holds real work-in-progress** — do NOT re-dispatch this work item in live mode. Finish, commit, and push directly from ${_pathPhrase} instead, or rename/retarget the branch so the two no longer collide.`,
+      ].join('\n');
+      try { writeInboxAlert(`live-checkout-worktree-conflict-${_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_worktree_conflict';
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      const _shortMsg = `live-checkout blocked: ${branchName} already used by worktree at ${_conflictPath || 'unknown location'}`;
+      log('error', `spawnAgent: ${_shortMsg}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        _shortMsg.slice(0, 800),
+        'Live-checkout could not switch onto the branch because it is already checked out in another worktree. Structural — operator must remove/reassign the conflicting worktree (or finish its WIP) before re-dispatch. Retrying is provably useless.',
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_WORKTREE_CONFLICT, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
     log('info', `live-checkout: ${_liveResult.created ? 'created' : 'switched to'} branch ${branchName} in ${cwd} (in-place; no worktree)`);
     // PL-live-checkout-reliability-hardening: a clean spawn clears the two-strike
     // dirty counter so a project that was transiently dirty once isn't treated as
@@ -8049,6 +8239,20 @@ function discoverFromWorkItems(config, project) {
     const promptItem = linkedPr ? withWorkItemPrContext(item, linkedPr) : item;
     const prBranch = linkedPr?.branch || '';
     const isPrTargeted = !!(linkedPr && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST));
+    // Issue #607 — `linkedPr` above resolves through the LOOSE
+    // extractWorkItemPrRef (title/first-paragraph-of-description text scan),
+    // which is fine for prompt-context enrichment (promptItem, above) that
+    // downgrades gracefully on a miss. But `dispatch.meta.pr` is a hard signal:
+    // `_isPrBackedDispatch`/`getStalePrDispatchReason` (engine/dispatch.js)
+    // treat ANY dispatch carrying it as PR-backed and will cancel the source
+    // work item outright if the tracked PR turns out to be merged/abandoned/
+    // context-only or branch-mismatched. A loose text match against an
+    // unrelated already-tracked PR (e.g. an ordinary implement item whose
+    // description says "see PR #99 for context") must never bind meta.pr —
+    // only a STRUCTURED PR pointer (targetPr/pr/references[]/pr_followup —
+    // see extractStructuredWorkItemPrRef) is strong enough evidence of real
+    // operator intent to make this dispatch cancellable on PR staleness.
+    const dispatchLinkedPr = (linkedPr && getStructuredWorkItemPrRef(item)) ? linkedPr : null;
     // W-mq18ec6h000p7b87: gate on the STRUCTURED-only ref. Loose
     // getWorkItemPrRef would also pick up description-scan refs (e.g. a
     // refactor item whose prose mentioned "PR #3015 for context") and trip
@@ -8130,7 +8334,7 @@ function discoverFromWorkItems(config, project) {
       agentRole: config.agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent',
       task: `[${project?.name || 'project'}] ${item.title || item.description?.slice(0, 80) || item.id}`,
       prompt,
-      meta: { dispatchKey: key, cooldownKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(isPrTargeted || (item.branchStrategy === 'shared-branch' && item.featureBranch)), item: promptItem, project: { name: project?.name, localPath: project?.localPath }, deferAgentResolution: deferredAgentResolution, ...(linkedPr ? { pr: linkedPr } : {}) }
+      meta: { dispatchKey: key, cooldownKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(isPrTargeted || (item.branchStrategy === 'shared-branch' && item.featureBranch)), item: promptItem, project: { name: project?.name, localPath: project?.localPath }, deferAgentResolution: deferredAgentResolution, ...(dispatchLinkedPr ? { pr: dispatchLinkedPr } : {}) }
     });
 
     } catch (err) { log('warn', `discoverFromWorkItems: skipping ${item.id}: ${err.message}`); }
@@ -9914,8 +10118,8 @@ async function tickInner() {
     // sibling-less stamps are preserved as tracking signals.
     try {
       const result = pruneScopeMismatchDuplicatePrs(config);
-      if (result?.pruned > 0) {
-        log('info', `[pull-requests] scope-mismatch sweep pruned ${result.pruned} duplicate record(s) across ${result.scanned} scanned`);
+      if (result?.pruned > 0 || result?.relocated > 0) {
+        log('info', `[pull-requests] scope-mismatch sweep pruned ${result.pruned} duplicate record(s), relocated ${result.relocated || 0} record(s) across ${result.scanned} scanned`);
       }
     } catch (err) {
       log('warn', `[pull-requests] scope-mismatch sweep error: ${err?.message || err}`);
@@ -10602,6 +10806,7 @@ module.exports = {
   findExistingWorktree, // exported for testing
   probeBranchOnRemote, // exported for testing (W-mphnm6a1000281b8)
   _maxTurnsForType, buildProjectContext, normalizeAc, _buildAgentSpawnFlags, _classifyAgentFailure, // exported for testing
+  _tryAutoResolveLiveCheckoutWorktreeConflict, // exported for testing (W-mr28h2j2000y0de1 review — auto-resolve worktree conflicts)
   _isOutputTruncated, AGENT_OUTPUT_CAP_BYTES, // P-8e4c2a17: exported for testing (OUTPUT_TRUNCATED detection)
   promoteCheckpointSteeringForClose, // exported for testing
   normalizePrBranch, resolvePrBranch, prCausePart, getPrCauseHead, getPrCauseBase, getPrAutomationCauseKey, getPrAutomationDispatchKey, // exported for testing

package/package.json

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

package/playbooks/review.md

@@ -30,6 +30,8 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
 {{#project_skills_block}}
 {{project_skills_block}}
 
+> **Skipping an in-scope review skill is gated.** Before you record a `meta.review.skillSkipped` (or `meta.skill.skipped`) outcome for any skill listed above, re-read that skill's own SKILL.md checklist and confirm your skip reason does not contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item it documents. If the diff trips ANY such item, do NOT skip — apply the skill (or at least that item). When you do skip, surface the exact same `{name, reason}` in your PR review comment via `minions pr comment … --skill-skipped-json '{"name":"…","reason":"…"}'` so a human sees it alongside your verdict before merge (no drift between the report and the comment). See `playbooks/shared-rules.md` → "Skipped an in-scope project skill?".
+
 {{/project_skills_block}}
 2. Think about deploy risk before commenting:
    - What user-visible behavior changed?

package/playbooks/shared-rules.md

@@ -176,6 +176,15 @@ When you author a **PR review / fix summary comment**, the same harness footprin
 
 One bullet per affordance, in the order skills → MCP servers → commands → docs; `N` is the bullet count. Whether the CLI folds it in or you hand-render it on a raw fallback, the section is the human-readable mirror of your `harnessUsed` completion field — keep the two consistent.
 
+### Skipped an in-scope project skill? Validate the skip, then surface it in the PR comment
+
+`meta.review.skillSkipped` / `meta.skill.skipped` (shape `{name, reason}`, see `docs/completion-reports.md`) lets you self-report that you intentionally skipped an available, **in-scope** project (review) skill. Two hard rules apply — this is not aspirational:
+
+1. **Validate the skip against the skill's own scope before recording it.** Re-read the skipped skill's SKILL.md review criteria / checklist (the content already injected via the `## Project skills` / `## Project review skills` block). Confirm your skip reason does **not** contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item the skill documents. If the diff trips ANY explicit checklist item the skill covers, skipping is **not** permitted — apply the skill (or at minimum that specific checklist item). A skip reason that waves away a gate the skill explicitly documents (e.g. "no CHANGELOG needed for this diff" when the skill's CHANGELOG Requirements section says otherwise) is invalid.
+2. **Surface the skip in the PR comment, not just the JSON.** When you post a review/fix summary comment, the skip must be visible in the same comment as the verdict so a human sees it **before** merge. Via `minions pr comment` (GitHub and ADO `--host ado`), pass `--skill-skipped-file <path>` (JSON `{name, reason}`) or inline `--skill-skipped-json <json>`; the shared builder (`engine/comment-format.js#buildSkippedSkillSection`, consumed by both `engine/gh-comment.js` and `engine/ado-comment.js`) folds a byte-identical `> ⚠️ Skipped project skill: <name> — <reason>` callout in for you. On raw fallbacks (`gh pr comment` / `az repos pr comment` / ADO REST) render that exact one-line blockquote callout yourself.
+
+The **same** `{name, reason}` you record in `meta.review.skillSkipped` / `meta.skill.skipped` must be the one rendered in the PR comment — no drift between the two.
+
 ## Minions API access
 
 The Minions dashboard runs at `http://localhost:7331` whenever the engine is up. Agents may call its HTTP endpoints when (and only when) the playbook explicitly authorizes it for a particular task — most dispatches do not need any API access, and uninvited writes to engine-managed state are still prohibited (see "Do NOT write to `agents/*/status.json`" above).