@yemi33/minions 0.1.2306 → 0.1.2308

package/engine/discover-project-skills.js

@@ -437,6 +437,8 @@ function renderProjectSkillsBlock(entries) {
   }
   lines.push('');
   lines.push("Record the skill outcome in your completion report's `meta.skill` block (`invoked` or `skipped` — see `docs/completion-reports.md`) so the engine can later measure skill-vs-first-principles signal.");
+  lines.push('');
+  lines.push("**Before you record a `skipped` outcome for an in-scope skill, this is a hard constraint, not a suggestion:** re-read that skill's own SKILL.md review criteria / checklist (the content injected above) and confirm your skip reason does not contradict any explicit \"Flag if…\" / \"Verify that…\" / \"Requirements\" item it 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 here\" when the skill's CHANGELOG Requirements section says otherwise) is invalid. When you do skip, the SAME `{name, reason}` you record in `meta.skill.skipped` must be the reason surfaced in the PR comment — no drift between the two.");
   return lines.join('\n');
 }
 
@@ -469,6 +471,8 @@ function renderReviewSkillsBlock(entries) {
   }
   lines.push('');
   lines.push("Record the skill outcome in your completion report's `meta.review` block (`skillInvoked` or `skillSkipped` — see `docs/completion-reports.md`) so the engine can later measure skill-vs-first-principles signal.");
+  lines.push('');
+  lines.push("**Before you record a `skillSkipped` outcome for an in-scope review skill, this is a hard constraint, not a suggestion:** re-read that skill's own SKILL.md review criteria / checklist (the content injected above) and confirm your skip reason does not contradict any explicit \"Flag if…\" / \"Verify that…\" / \"Requirements\" item it documents. If the diff under review trips ANY explicit checklist item the skill covers, skipping is NOT permitted — apply the skill (or at minimum that specific checklist item) and let it inform your verdict. 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. When you do skip, the SAME `{name, reason}` you record in `meta.review.skillSkipped` must be the reason surfaced in the PR comment — no drift between the two.");
   return lines.join('\n');
 }
 

package/engine/dispatch.js

@@ -444,7 +444,10 @@ async function addToDispatchWithValidation(item, opts = {}) {
 
   let evaluation;
   try {
-    evaluation = await validate(wi, { engineConfig: config?.engine });
+    evaluation = await validate(wi, {
+      engineConfig: config?.engine,
+      project: _resolveEvalProjectContext(item, config),
+    });
   } catch (e) {
     log('warn', `pre-dispatch-eval: validator threw — failing open: ${e.message}`);
     return addToDispatch(item);
@@ -458,6 +461,37 @@ async function addToDispatchWithValidation(item, opts = {}) {
   return null;
 }
 
+/**
+ * Build the target-project identity passed to the pre-dispatch validator so the
+ * LLM knows which repo the work item targets. Without this the model has no way
+ * to know which project it is reasoning about and defaults to describing the
+ * Minions engine checkout it executes inside (cwd is hardcoded to MINIONS_DIR),
+ * producing false-invalid verdicts backed by fabricated file-existence claims
+ * about the wrong repo (W-mr25eg2400078d4b; repro WI W-mr2401ga0007830d
+ * targeting constellation). Best-effort — resolves the full project config to
+ * derive a canonical repo slug, but degrades gracefully to name/localPath only.
+ * @returns {{name?: string, slug?: string, localPath?: string}|null}
+ */
+function _resolveEvalProjectContext(item, config) {
+  const metaProject = item?.meta?.project;
+  if (!metaProject) return null;
+  const name = typeof metaProject === 'string' ? metaProject : metaProject.name;
+  const ctx = {};
+  if (name) ctx.name = String(name);
+  if (metaProject && typeof metaProject === 'object' && metaProject.localPath) {
+    ctx.localPath = String(metaProject.localPath);
+  }
+  try {
+    const full = _resolveDispatchProject(name || metaProject, config);
+    if (full && typeof full === 'object') {
+      if (!ctx.localPath && full.localPath) ctx.localPath = String(full.localPath);
+      const slug = shared.getProjectPrScope(full);
+      if (slug) ctx.slug = slug;
+    }
+  } catch { /* best-effort — name/localPath alone still help */ }
+  return Object.keys(ctx).length > 0 ? ctx : null;
+}
+
 
 function _resolveDispatchProject(projectRef, config) {
   if (!projectRef) return null;
@@ -580,6 +614,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, // P-a3f9b204 — live-checkout refused to spawn because operator localPath is dirty; mechanical retry won't fix it (operator must commit/stash/discard). NOTE (W-mqzmkoqt000hbca2): engine.js#spawnAgent ALWAYS passes an explicit `agentRetryable` for this class, so this Set entry is never the actual gate — when auto-cleanup (liveCheckoutAutoReset/AutoStash) is enabled the engine overrides to retryable. Kept as a defensive safety net for any caller that omits the explicit override.
       FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION, // P-a7f3c1d9 — live-checkout refused to spawn because the operator tree is mid-operation (in-progress merge/rebase/cherry-pick/bisect or detached HEAD); mechanical retry won't fix it (operator must finish/abort the op or checkout a branch)
       FAILURE_CLASS.LIVE_CHECKOUT_BLOB_FETCH, // PL-live-checkout-reliability-hardening — live-checkout `git checkout <existing-branch>` failed hydrating the tree through the auth-less GVFS cache server (blobless partial clone, headless); deterministic, so mechanical retry just reproduces it (operator must hydrate the branch with their own creds, then re-dispatch)
+      FAILURE_CLASS.LIVE_CHECKOUT_WORKTREE_CONFLICT, // W-mr28h2j2000y0de1 — live-checkout `git checkout <existing-branch>` failed because that branch is already checked out in another worktree; structural conflict, so mechanical retry just reproduces it (operator must `git worktree remove` the other tree or finish its WIP, then re-dispatch)
       FAILURE_CLASS.OUTPUT_TRUNCATED, // P-8e4c2a17 — agent stdout exceeded the hard capture cap before the terminal result event; mechanical retry just reproduces the overflow (agent must reduce output volume or the task must be split)
     ]);
     if (neverRetry.has(failureClass)) return false;

package/engine/gh-comment.js

@@ -43,6 +43,7 @@ const { execFileSync: _execFileSync } = require('child_process');
 const { resolveTokenForSlug: _defaultResolveTokenForSlug } = require('./gh-token');
 const {
   buildHarnessUsedSection,
+  buildSkippedSkillSection,
   linkifyBrandTrailer,
   MINIONS_BRAND_URL,
   // Neutral marker + body builder now lives in comment-format.js so the GitHub
@@ -155,13 +156,14 @@ function postPrComment({
   kind,
   workItemId,
   harnessUsed,
+  skillSkipped,
   timeoutMs = 30000,
   execFileSync = _execFileSync,
   resolveTokenForSlug,
 } = {}) {
   _validateRepo(repo);
   _validatePrNumber(prNumber);
-  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed });
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed, skillSkipped });
   const file = _writeTempBodyFile(finalBody);
   const env = _resolveTokenEnvForRepo(repo, resolveTokenForSlug);
   try {
@@ -185,13 +187,14 @@ function postPrReviewComment({
   kind,
   workItemId,
   harnessUsed,
+  skillSkipped,
   timeoutMs = 30000,
   execFileSync = _execFileSync,
   resolveTokenForSlug,
 } = {}) {
   _validateRepo(repo);
   _validatePrNumber(prNumber);
-  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed });
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed, skillSkipped });
   const file = _writeTempBodyFile(finalBody);
   const env = _resolveTokenEnvForRepo(repo, resolveTokenForSlug);
   try {
@@ -222,6 +225,7 @@ function postPrReview({
   kind,
   workItemId,
   harnessUsed,
+  skillSkipped,
   timeoutMs = 30000,
   execFileSync = _execFileSync,
   resolveTokenForSlug,
@@ -234,7 +238,7 @@ function postPrReview({
   }
   _validateRepo(repo);
   _validatePrNumber(prNumber);
-  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed });
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed, skillSkipped });
   const file = _writeTempBodyFile(finalBody);
   const env = _resolveTokenEnvForRepo(repo, resolveTokenForSlug);
   try {
@@ -254,6 +258,7 @@ module.exports = {
   // Builders / parsers (pure functions — usable from anywhere)
   buildMinionsCommentBody,
   buildHarnessUsedSection, // re-export of engine/comment-format.js for comment callers
+  buildSkippedSkillSection, // re-export of engine/comment-format.js for comment callers
   linkifyBrandTrailer, // re-export of engine/comment-format.js for comment callers
   MINIONS_BRAND_URL, // re-export of engine/comment-format.js for comment callers
   parseMinionsMarker,

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,