@yemi33/minions 0.1.2306 → 0.1.2307

package/engine/lifecycle.js

@@ -6308,18 +6308,34 @@ function diagnoseEmptyOutput(failureClass, code, elapsedMs) {
   return `[empty-output: process exited in ${elapsedMs}ms \u2014 possible causes: machine sleep, network unavailability, auth failure]`;
 }
 
-// W-mqba5ulq000nd255 — Reconciliation sweep: delete PR records flagged with
-// `_invalidProjectScope: { reason: "pr_scope_mismatch" }` IFF a sibling
-// record for the same canonical pr.id exists in another project whose scope
-// matches the PR URL (i.e. the correctly-scoped project owns the canonical
-// record). Sibling-less mismatches are preserved as tracking. Runs once per
-// tick from engine.js after the ADO/GitHub reconcile polls finish.
+// W-mqba5ulq000nd255 / W-mr2cqq12000b04f8 — Reconciliation sweep with two
+// defenses against mis-scoped `_invalidProjectScope: { reason: "pr_scope_mismatch" }`
+// records:
 //
-// Returns { pruned, scanned } so the engine tick can log a summary line.
+//  1. PRUNE — a sibling record for the same canonical pr.id already exists in
+//     the correctly-scoped project (e.g. a fresh dispatch there re-synced it).
+//     The mis-scoped duplicate is deleted; the sibling is the surviving record.
+//
+//  2. RELOCATE — no sibling exists yet, but a project IS configured whose
+//     scope matches the PR's real repo (e.g. work dispatched under project
+//     "minions-opg" opened a PR against `yemi33/minions`, and a "minions"
+//     project mapping to that repo is configured). Without this, the record
+//     would sit mis-scoped forever — the correct project's tracker (read by
+//     repo-scoped schedules such as daily-merge-approved-minions-prs) would
+//     never see it. The record is moved: upserted into the correct project's
+//     file (which clears `_invalidProjectScope` since it's now correctly
+//     scoped) and removed from the mis-scoped project's file.
+//
+// When no configured project matches the PR's real scope at all, the record
+// is left in place with its `_invalidProjectScope` stamp so operators can
+// still find it (still surfaced via GET /api/pull-requests aggregation).
+// Runs once per tick from engine.js after the ADO/GitHub reconcile polls finish.
+//
+// Returns { pruned, relocated, scanned } so the engine tick can log a summary line.
 function pruneScopeMismatchDuplicatePrs(config) {
   config = config || getConfig();
   const projects = shared.getProjects(config) || [];
-  if (projects.length === 0) return { pruned: 0, scanned: 0 };
+  if (projects.length === 0) return { pruned: 0, relocated: 0, scanned: 0 };
 
   // Map project name -> canonical scope so we can find which project IS the
   // correctly-scoped owner for a given mismatch record.
@@ -6344,13 +6360,17 @@ function pruneScopeMismatchDuplicatePrs(config) {
   }
 
   // Build per-project delete sets keyed by id, so we batch one mutation per
-  // affected project file.
-  const deletesByProject = new Map(); // projectName -> Set(prId)
+  // affected project file. Track prune-deletes and relocate-deletes in
+  // separate id sets (per project) so `pruned` vs `relocated` counts stay
+  // accurate even though both end up removing rows from the same file.
+  const pruneDeletesByProject = new Map(); // projectName -> Set(prId)
+  const relocateDeletesByProject = new Map(); // projectName -> Set(prId)
+  // Records to insert into their correctly-scoped project's file.
+  const relocationsByTargetProject = new Map(); // projectName -> [{ rec, owningScope }]
   let scanned = 0;
   let pruned = 0;
 
   for (const records of byId.values()) {
-    if (records.length < 2) continue;
     for (const rec of records) {
       scanned++;
       if (!rec._invalidProjectScope || rec._invalidProjectScope.reason !== 'pr_scope_mismatch') continue;
@@ -6358,32 +6378,79 @@ function pruneScopeMismatchDuplicatePrs(config) {
       if (!correctScope) continue;
       const correctProject = projectByScope.get(correctScope);
       if (!correctProject) continue; // no configured project owns the URL — keep as tracking
-      // Sibling check: is there a record under the correct scope for the same id?
-      const sibling = records.find(r => r !== rec && r._scope === correctProject.name);
-      if (!sibling) continue;
-      // Safe to prune.
       const owningScope = rec._scope;
       if (!owningScope || owningScope === 'central') continue;
-      if (!deletesByProject.has(owningScope)) deletesByProject.set(owningScope, new Set());
-      deletesByProject.get(owningScope).add(rec.id);
+      if (owningScope === correctProject.name) continue; // already correctly scoped
+      // Sibling check: is there a record under the correct scope for the same id?
+      const sibling = records.find(r => r !== rec && r._scope === correctProject.name);
+      if (sibling) {
+        // Safe to prune — the sibling already owns the canonical record.
+        if (!pruneDeletesByProject.has(owningScope)) pruneDeletesByProject.set(owningScope, new Set());
+        pruneDeletesByProject.get(owningScope).add(rec.id);
+      } else {
+        // No sibling anywhere: relocate the record into the correctly-scoped
+        // project instead of leaving it stuck mis-scoped indefinitely.
+        if (!relocationsByTargetProject.has(correctProject.name)) relocationsByTargetProject.set(correctProject.name, []);
+        relocationsByTargetProject.get(correctProject.name).push({ rec, owningScope });
+      }
+    }
+  }
+
+  // Relocate first (insert into target), only marking the source record for
+  // deletion once the insert into the correct project succeeds — this avoids
+  // losing a record if the insert throws mid-way.
+  let relocated = 0;
+  for (const [targetProjectName, entries] of relocationsByTargetProject) {
+    const targetProject = projects.find(p => p.name === targetProjectName);
+    if (!targetProject) continue;
+    const targetPrPath = projectPrPath(targetProject);
+    for (const { rec, owningScope } of entries) {
+      const entry = { ...rec };
+      delete entry._scope;
+      delete entry._invalidProjectScope;
+      delete entry.project; // let upsertPullRequestRecord backfill from targetProject
+      try {
+        const result = shared.upsertPullRequestRecord(targetPrPath, entry, {
+          project: targetProject,
+          itemIds: Array.isArray(rec.prdItems) ? rec.prdItems : null,
+        });
+        if (result.created || result.linked) {
+          relocated++;
+          if (!relocateDeletesByProject.has(owningScope)) relocateDeletesByProject.set(owningScope, new Set());
+          relocateDeletesByProject.get(owningScope).add(rec.id);
+          log('info', `[pull-requests] relocated mis-scoped PR ${rec.id} from project=${owningScope} to correctly-scoped project=${targetProjectName}`);
+        }
+      } catch (err) {
+        log('warn', `pruneScopeMismatchDuplicatePrs: failed to relocate ${rec.id} to ${targetProjectName}: ${err?.message || err}`);
+      }
     }
   }
 
-  if (deletesByProject.size === 0) return { pruned: 0, scanned };
+  // Merge prune + relocate delete sets per project so each file is mutated once.
+  const deletesByProject = new Map();
+  for (const [projectName, ids] of pruneDeletesByProject) {
+    deletesByProject.set(projectName, new Set(ids));
+  }
+  for (const [projectName, ids] of relocateDeletesByProject) {
+    if (!deletesByProject.has(projectName)) deletesByProject.set(projectName, new Set());
+    for (const id of ids) deletesByProject.get(projectName).add(id);
+  }
+
+  if (deletesByProject.size === 0) return { pruned: 0, relocated, scanned };
 
   for (const [projectName, idsToDelete] of deletesByProject) {
     const project = projects.find(p => p.name === projectName);
     if (!project) continue;
     const prPath = projectPrPath(project);
+    const pruneIds = pruneDeletesByProject.get(projectName) || new Set();
     try {
       shared.mutatePullRequests(prPath, (prs) => {
-        const before = prs.length;
+        const deletedIds = prs.filter(p => idsToDelete.has(p?.id)).map(p => p.id);
         const next = prs.filter(p => !idsToDelete.has(p?.id));
-        const deleted = before - next.length;
-        if (deleted > 0) {
-          pruned += deleted;
-          for (const id of idsToDelete) {
-            log('info', `[pull-requests] pruned scope-mismatch duplicate ${id} from project=${projectName} (sibling exists in correctly-scoped project)`);
+        for (const id of deletedIds) {
+          if (pruneIds.has(id)) {
+            pruned++;
+            log('info', `[pull-requests] removed mis-scoped duplicate ${id} from project=${projectName}`);
           }
         }
         return next;
@@ -6393,7 +6460,7 @@ function pruneScopeMismatchDuplicatePrs(config) {
     }
   }
 
-  return { pruned, scanned };
+  return { pruned, relocated, scanned };
 }
 
 // Repair helper: collapse prNumber duplicates across all project-scoped and

package/engine/live-checkout.js

@@ -53,6 +53,11 @@
  *   { ok:false, reason:'dirty',         dirtyFiles:[…] }
  *   { ok:false, reason:'mid-operation', op:'merge'|'rebase'|'cherry-pick'|'revert', details }
  *   { ok:false, reason:'detached-head', sha }
+ *   { ok:false, reason:'blob-fetch',        op, branch, message, originalRef, originalRefType }
+ *   { ok:false, reason:'worktree-conflict', op, branch, conflictingWorktreePath, message, originalRef, originalRefType }
+ *     (W-mr28h2j2000y0de1) — the target branch is already checked out in another
+ *     worktree; `git checkout <branch>` refuses deterministically. Non-retryable
+ *     at the caller — a human/engine must remove or reassign the other worktree.
  *
  * NOTE: `mainRef` is still accepted (and validated) for caller-contract
  * stability, but it is NOT used to seed the new branch in live mode — HEAD
@@ -132,6 +137,33 @@ function _isPartialCloneBlobError(message = '') {
   );
 }
 
+// W-mr28h2j2000y0de1 — worktree-conflict signature match. When 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 behind by a checkoutMode change), a plain `git checkout
+// <branch>` inside the operator checkout (project.localPath) refuses
+// DETERMINISTICALLY with git's own literal phrasing:
+//   fatal: '<branch>' is already used by worktree at '<path>'
+// This is a STRUCTURAL conflict — it does NOT clear on retry, ever, until a
+// human or the engine removes/reassigns the other worktree. So (like the
+// blob-fetch case) it must be surfaced ONCE as an operator-actionable refusal
+// instead of retry-storming an identical LIVE_CHECKOUT_FAILED to the cap. The
+// matcher keys on git's stable literal wording (case-insensitive substring)
+// and, when present, captures the conflicting worktree path so the caller's
+// inbox alert can name the exact tree to remove or finish work in.
+function _isWorktreeConflictError(message = '') {
+  return /is already used by worktree at/i.test(String(message || ''));
+}
+
+// Extract the conflicting worktree path from git's "is already used by worktree
+// at '<path>'" message. Returns the captured path, or null when the phrasing
+// didn't include an extractable path (defensive — the caller degrades to an
+// "unknown location" alert).
+function _extractConflictingWorktreePath(message = '') {
+  const m = String(message || '').match(/is already used by worktree at '([^']+)'/i);
+  return m ? m[1] : null;
+}
+
 // W-mqva907q — auto-clean safe untracked build artifacts before a live-checkout
 // dirty bail. A `git status --porcelain` line for a stray `__pycache__/` (or
 // other regenerable cache) should NOT block dispatch the way a real edit does.
@@ -664,6 +696,18 @@ async function prepareLiveCheckout(opts = {}) {
           originalRefType,
         };
       }
+      if (_isWorktreeConflictError(msg)) {
+        return {
+          ok: false,
+          reason: 'worktree-conflict',
+          op: creating ? 'create' : 'checkout',
+          branch: branchName,
+          conflictingWorktreePath: _extractConflictingWorktreePath(msg),
+          message: msg.slice(0, 500),
+          originalRef,
+          originalRefType,
+        };
+      }
       throw checkoutErr; // transient → caller retries (LIVE_CHECKOUT_FAILED)
     }
   };
@@ -954,6 +998,164 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
   }
 }
 
+/**
+ * resolveLiveCheckoutAutoStash — W-mqtvnnj1000357fa
+ *
+ * Decides whether a dirty live-checkout tree should be auto-stashed before
+ * dispatch instead of failing with FAILURE_CLASS.LIVE_CHECKOUT_DIRTY.
+ *
+ * Resolution order (per-project overrides fleet, matching resolveCheckoutMode
+ * and the per-agent cli/model override pattern):
+ *   1. If `project.liveCheckoutAutoStash` is an explicit boolean, use it.
+ *   2. Else if `engine.liveCheckoutAutoStash` is an explicit boolean, use it.
+ *   3. Else default false.
+ *
+ * Pure — no I/O. Tested in test/unit/live-checkout-auto-stash.test.js.
+ *
+ * @param {{ project?:object|null, engine?:object|null }} opts
+ * @returns {boolean}
+ */
+function resolveLiveCheckoutAutoStash(opts = {}) {
+  const { project, engine } = opts;
+  if (project && typeof project.liveCheckoutAutoStash === 'boolean') {
+    return project.liveCheckoutAutoStash;
+  }
+  if (engine && typeof engine.liveCheckoutAutoStash === 'boolean') {
+    return engine.liveCheckoutAutoStash;
+  }
+  return false;
+}
+
+/**
+ * performLiveCheckoutAutoStash — W-mqtvnnj1000357fa
+ *
+ * Runs `git stash push --include-untracked -m "<message>"` in the operator's
+ * live checkout so a dirty tree can be parked and dispatch can proceed. The
+ * engine NEVER pops the stash automatically — that is the operator's choice
+ * (step 5 of the WI). The stash name is logged + surfaced in an inbox note so
+ * the operator can `git stash pop` manually.
+ *
+ * `--include-untracked` is intentional (the WI text shows the bare form): the
+ * dirty preflight uses `git status --porcelain`, which counts untracked `??`
+ * files as dirty, so a tracked-only stash would leave the tree dirty and the
+ * re-run preflight would still bail. Including untracked makes the tree clean.
+ *
+ * Never throws on a stash failure and never silently swallows it — returns
+ * `{ ok:false, error }` so the caller can fall through to the existing
+ * retry-once-then-fail behavior (step 4 of the WI).
+ *
+ * MUST be called OUTSIDE any file lock — it shells out to git and the lock
+ * callbacks must stay synchronous/fast.
+ *
+ * @param {{ localPath:string, dispatchId?:string, gitOpts?:object,
+ *           log?:(msg:string, lvl?:string)=>void, _git?:Function }} opts
+ * @returns {Promise<{ ok:boolean, stashMessage:string, error?:string }>}
+ */
+async function performLiveCheckoutAutoStash(opts = {}) {
+  const { localPath, dispatchId, gitOpts, log, _git } = opts;
+  if (!localPath || typeof localPath !== 'string') {
+    throw new Error('performLiveCheckoutAutoStash: localPath is required (got ' + JSON.stringify(localPath) + ')');
+  }
+  const git = (typeof _git === 'function') ? _git : shared.shellSafeGit;
+  const logFn = (typeof log === 'function') ? log : () => {};
+  const baseOpts = { cwd: localPath, ...(gitOpts || {}) };
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const stashMessage = `minions-auto-stash-${dispatchId || 'nodispatch'}-${stamp}`;
+  try {
+    await git(['stash', 'push', '--include-untracked', '-m', stashMessage], baseOpts);
+    logFn(
+      `live-checkout: auto-stashed dirty tree as "${stashMessage}" in ${localPath} — ` +
+      `the engine will NOT pop it automatically; run \`git stash pop\` in ${localPath} to restore.`,
+      'info',
+    );
+    return { ok: true, stashMessage };
+  } catch (e) {
+    const error = (e && e.message) ? e.message : String(e);
+    logFn(`live-checkout: auto-stash failed in ${localPath}: ${error}`, 'warn');
+    return { ok: false, stashMessage, error };
+  }
+}
+
+/**
+ * applyLiveCheckoutAutoStash — W-mqtvnnj1000357fa
+ *
+ * Orchestrates the dirty-tree auto-stash flow so spawnAgent stays lean. When the
+ * preflight `liveResult` is a confirmed-dirty refusal AND auto-stash is enabled
+ * (per-project field wins, else engine fleet-wide fallback), this:
+ *   1. `git stash push --include-untracked` the operator's changes
+ *      (performLiveCheckoutAutoStash — runs OUTSIDE any file lock).
+ *   2. On stash success, re-runs `prepareLiveCheckout` (the tree is now clean).
+ *   3. Clears the WI's `_pendingReason === 'live_checkout_dirty'` stamp via the
+ *      injected `clearDirtyStamp` callback so a future dirty tree is not treated
+ *      as "already failed" (resets the retry-once state).
+ *   4. Writes an operator inbox note via the injected `writeStashNote(key, body)`
+ *      callback (the engine NEVER pops the stash automatically).
+ *
+ * Returns a discriminated outcome the caller acts on:
+ *   - `{ outcome:'unchanged', liveResult }` — not dirty, disabled, or stash failed
+ *     (caller falls through to the existing retry-once-then-fail dirty handling).
+ *   - `{ outcome:'stashed', liveResult }`   — stashed + re-preflighted; proceed.
+ *   - `{ outcome:'threw', error }`           — the re-preflight threw; caller must
+ *     fail the dispatch as LIVE_CHECKOUT_FAILED (engine-specific completion).
+ *
+ * @param {object} opts
+ * @returns {Promise<{outcome:'unchanged'|'stashed'|'threw', liveResult?:object, error?:Error}>}
+ */
+async function applyLiveCheckoutAutoStash(opts = {}) {
+  const {
+    liveResult, project, engine, localPath, branchName, mainRef,
+    gitOpts, dispatchId, wiId, log,
+    clearDirtyStamp, writeStashNote,
+  } = opts;
+  const logFn = (typeof log === 'function') ? log : () => {};
+  const reason = (liveResult && liveResult.ok === false) ? liveResult.reason : null;
+  if (reason !== 'dirty' || !resolveLiveCheckoutAutoStash({ project, engine })) {
+    return { outcome: 'unchanged', liveResult };
+  }
+  let stashResult;
+  try {
+    stashResult = await performLiveCheckoutAutoStash({ localPath, dispatchId, gitOpts, log });
+  } catch (stashErr) {
+    stashResult = { ok: false, error: stashErr && stashErr.message };
+  }
+  if (!stashResult || !stashResult.ok) {
+    logFn(`spawnAgent: live-checkout auto-stash failed for ${dispatchId} (${(stashResult && stashResult.error) || 'unknown'}); falling through to dirty-fail handling`, 'warn');
+    return { outcome: 'unchanged', liveResult };
+  }
+  let newLive;
+  try {
+    newLive = await prepareLiveCheckout({ localPath, branchName, mainRef, gitOpts, dispatchId, wiId, log });
+  } catch (stashLiveErr) {
+    return { outcome: 'threw', error: stashLiveErr };
+  }
+  if (typeof clearDirtyStamp === 'function') {
+    try { clearDirtyStamp(); } catch (e) { logFn(`live-checkout: failed to clear _pendingReason after auto-stash: ${e.message}`, 'warn'); }
+  }
+  if (typeof writeStashNote === 'function') {
+    try {
+      const body = [
+        '# Live-checkout dirty tree auto-stashed',
+        '',
+        `**Project:** ${(project && project.name) || '(unknown)'}`,
+        `**Local path:** ${localPath}`,
+        `**Branch:** ${branchName}`,
+        `**Work item:** ${wiId}`,
+        `**Dispatch:** ${dispatchId}`,
+        `**Stash:** \`${stashResult.stashMessage}\``,
+        '',
+        `The live checkout at \`${localPath}\` had uncommitted changes. Because live-checkout auto-stash is enabled, the engine ran \`git stash push --include-untracked\` so this dispatch could proceed. The engine never \`git reset\` or \`git clean\` your tree.`,
+        '',
+        '## Recovery',
+        '',
+        `The engine does NOT pop the stash automatically. To restore your changes, run \`git stash pop\` (or \`git stash apply\`) in \`${localPath}\`. Locate it with \`git stash list\` — look for \`${stashResult.stashMessage}\`.`,
+      ].join('\n');
+      writeStashNote(`live-checkout-autostash-${wiId}`, body);
+    } catch (e) { logFn(`live-checkout: writeInboxAlert (auto-stash) failed: ${e.message}`, 'warn'); }
+  }
+  logFn(`spawnAgent: live-checkout auto-stashed dirty tree for ${dispatchId} (${stashResult.stashMessage}); proceeding with dispatch`, 'info');
+  return { outcome: 'stashed', liveResult: newLive };
+}
+
 /**
  * maybeRestoreLiveCheckoutFromRecord — PL-live-checkout-reliability-hardening
  *
@@ -1020,8 +1222,13 @@ async function maybeRestoreLiveCheckoutFromRecord(opts = {}) {
 module.exports = {
   prepareLiveCheckout,
   restoreLiveCheckoutAtDispatchEnd,
+  resolveLiveCheckoutAutoStash,
+  performLiveCheckoutAutoStash,
+  applyLiveCheckoutAutoStash,
   maybeRestoreLiveCheckoutFromRecord,
   _isPartialCloneBlobError,
+  _isWorktreeConflictError,
+  _extractConflictingWorktreePath,
   _isAutoCleanableArtifact,
   _collectAutoCleanablePaths,
   _looksLikeAgentBranch,

package/engine/pre-dispatch-eval.js

@@ -45,6 +45,44 @@ const DEFAULT_TIMEOUT_MS = 60000;
 // descriptions don't carry enough signal for the gate to add value.
 const DESCRIPTION_MIN_CHARS = 80;
 
+// Guardrail appended to every prompt. The validator runs a pure text-reasoning
+// LLM call (direct: true, cwd hardcoded to MINIONS_DIR per engine/llm.js
+// _spawnProcess) with NO filesystem tools, so the model cannot see the target
+// project's code. P-b5e2a481 removed the read tools that were making the model
+// search MINIONS_DIR, but the model kept *asserting* unverified file-existence
+// claims in its reasoning text (e.g. "this repo contains no TypeScript files")
+// while actually describing the Minions engine checkout it runs inside rather
+// than the WI's real target repo (W-mr25eg2400078d4b, repro WI
+// W-mr2401ga0007830d targeting constellation). Forbidding empirical repo claims
+// in the prompt makes an invalid verdict that hinges on a fabricated
+// file-existence claim structurally impossible.
+const NO_FS_GUARDRAIL = [
+  'IMPORTANT — you have NO filesystem or repository access and CANNOT see the',
+  "target project's code, files, or directory structure. Judge ONLY whether the",
+  'work item is well-specified: clear, internally consistent, actionable, and',
+  'testable in the abstract as a software task. Do NOT assert or assume whether',
+  'any specific file, directory, path, module, package, or code symbol exists or',
+  'does not exist, and do NOT cite file paths or file contents as evidence. A',
+  'verdict of "valid": false must NEVER rest on a claim about what the repository',
+  'does or does not contain — you have not seen it. Only mark invalid when the',
+  'description itself is too vague, contradictory, or underspecified to act on.',
+].join('\n');
+
+function _describeProject(project) {
+  if (!project || typeof project !== 'object') return '';
+  const name = project.name ? String(project.name).trim() : '';
+  const slug = project.slug ? String(project.slug).trim() : '';
+  const localPath = project.localPath ? String(project.localPath).trim() : '';
+  const parts = [];
+  if (name) parts.push(`name "${name}"`);
+  if (slug) parts.push(`repo ${slug}`);
+  if (localPath) parts.push(`local checkout at ${localPath}`);
+  if (parts.length === 0) return '';
+  return `Target project: ${parts.join(', ')}. This work item targets that `
+    + 'project, which is a DIFFERENT repository from the Minions engine codebase '
+    + 'you are running inside.';
+}
+
 function _extractCriteria(workItem) {
   if (!workItem || typeof workItem !== 'object') return [];
   const candidates = [workItem.acceptance_criteria, workItem.acceptanceCriteria];
@@ -59,17 +97,21 @@ function _extractDescription(workItem) {
   return (workItem.description || '').trim();
 }
 
-function _buildPrompt(workItem, criteria) {
+function _buildPrompt(workItem, criteria, project) {
   const title = workItem.title || workItem.name || workItem.id || 'untitled';
   const description = _extractDescription(workItem);
-  const lines = [
-    `Work item: ${title}`,
-  ];
+  const lines = [];
+  const projectLine = _describeProject(project);
+  if (projectLine) lines.push(projectLine, '');
+  lines.push(`Work item: ${title}`);
   const hasCriteria = Array.isArray(criteria) && criteria.length > 0;
   if (description) lines.push('', 'Description:', description);
   if (hasCriteria) {
     lines.push('', 'Acceptance criteria:');
     for (const c of criteria) lines.push(`- ${c}`);
+  }
+  lines.push('', NO_FS_GUARDRAIL);
+  if (hasCriteria) {
     lines.push('',
       'Are these acceptance criteria clear, actionable, and testable?',
       'Reply with JSON: {"valid": true|false, "reason": "..."}.');
@@ -146,6 +188,12 @@ function _resolveModel(opts) {
  * @param {string} [opts.model] - explicit model override; otherwise the
  *   engine's CC model resolution applies, falling back to `undefined`
  *   (adapter default) when nothing is configured.
+ * @param {object} [opts.project] - target-project identity for prompt context
+ *   (`{ name, slug, localPath }`). Threaded by
+ *   `engine/dispatch.js addToDispatchWithValidation` so the model knows which
+ *   repo the work item targets (it CANNOT see any repo) and does not default to
+ *   describing the Minions engine checkout it runs inside
+ *   (W-mr25eg2400078d4b).
  * @param {number} [opts.timeout] - LLM timeout in ms.
  * @returns {Promise<{valid: boolean, reason: string}>}
  */
@@ -159,7 +207,7 @@ async function validateAcceptanceCriteria(workItem, opts = {}) {
     return { valid: true, reason: 'no acceptance criteria to validate' };
   }
 
-  const prompt = _buildPrompt(workItem, criteria);
+  const prompt = _buildPrompt(workItem, criteria, opts.project);
   let result;
   try {
     result = await callLLM(prompt, SYSTEM_PROMPT, {
@@ -219,6 +267,7 @@ module.exports = {
   // Exposed for unit testing — engine code MUST go through validateAcceptanceCriteria.
   _extractCriteria,
   _extractDescription,
+  _describeProject,
   _buildPrompt,
   _parseResponse,
   _resolveModel,

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,