@yemi33/minions 0.1.2305 → 0.1.2307

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.
@@ -188,6 +220,65 @@ function _collectAutoCleanablePaths(dirtyFiles) {
   return cleanable.length > 0 ? cleanable : null;
 }
 
+// issue #608 — detects a branch name that the ENGINE created for a live-mode
+// dispatch (never the operator's own branch). Matches ONLY the literal
+// `work/<wi-id>` convention produced by `shared.deriveWorkItemBranchName` —
+// deliberately narrow so an operator's own `user/...`/`feature/...` branch is
+// never mistaken for agent litter. Used by the orphaned-agent-branch self-heal
+// below (prepareLiveCheckout) to recognize a stray branch left behind by an
+// earlier dispatch whose dispatch-end restore did not complete.
+function _looksLikeAgentBranch(name) {
+  return typeof name === 'string' && /^work\//.test(name.trim());
+}
+
+// issue #608 — pull the current local branch name out of the `## <branch>...`
+// header line that `git status --porcelain=v1 -b` already returns, so the
+// orphaned-agent-branch self-heal below needs ZERO extra git calls on the
+// common (non-stray) dirty path — preserving the existing "no extra git calls
+// when the tree isn't all-artifact-cleanable" contract asserted by
+// test/unit/prepare-live-checkout.test.js. Returns '' for a detached HEAD
+// (`## HEAD (no branch)`) or an unparsable header.
+function _extractBranchFromPorcelainHeader(branchInfo) {
+  if (!branchInfo || typeof branchInfo !== 'string') return '';
+  const body = branchInfo.replace(/^##\s*/, '');
+  const firstToken = body.split(' ')[0] || '';
+  const localBranch = firstToken.split('...')[0];
+  return (!localBranch || localBranch === 'HEAD') ? '' : localBranch;
+}
+
+// issue #608 — commit whatever is staged/unstaged onto the CURRENT branch
+// with bounded retry+backoff, specifically to survive a transient
+// `.git/index.lock` collision against a sibling git process (the root cause
+// of the 2026-06-30 incident: two live-checkout dispatches raced `git add -A`
+// / `git commit` against the same working tree, the commit lost the lock race
+// once, and the prior code gave up on the first failure with no retry). Only
+// RETRIES when the failure looks like transient lock contention; any other
+// failure (e.g. "nothing to commit") returns immediately so callers fall
+// through to their existing best-effort handling. Never throws — callers get
+// `{ ok:false, error }` on exhaustion.
+async function _commitAgentWipWithRetry(git, baseOpts, message, options = {}) {
+  const attempts = Number.isFinite(options.attempts) ? options.attempts : 3;
+  const baseDelayMs = Number.isFinite(options.baseDelayMs) ? options.baseDelayMs : 300;
+  const sleep = typeof options.sleep === 'function'
+    ? options.sleep
+    : (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  let lastErr = null;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      await git(['add', '-A'], baseOpts);
+      await git(['commit', '--no-verify', '-m', message], baseOpts);
+      return { ok: true, attempts: attempt };
+    } catch (e) {
+      lastErr = e;
+      const msg = String((e && e.message) || '');
+      const transientLock = /index\.lock/i.test(msg) || /another git process/i.test(msg);
+      if (!transientLock || attempt === attempts) break;
+      await sleep(baseDelayMs * attempt);
+    }
+  }
+  return { ok: false, error: lastErr, attempts };
+}
+
 // W-mqvejug6000eeb20 — production default for resolving the live-checkout
 // auto-reset decision when the caller (engine.js spawnAgent) does not pass an
 // explicit `autoReset` boolean. engine.js is intentionally not threading the
@@ -237,6 +328,7 @@ async function prepareLiveCheckout(opts = {}) {
     _rm,        // private injection for testing — defaults to fs.rmSync (recursive, force)
     _resolveAutoReset, // private injection for testing — defaults to config-based resolver
     _writeInboxNote,   // private injection for testing — defaults to dispatch.writeInboxAlert
+    _sleep,            // private injection for testing — defaults to a real setTimeout-based sleep
   } = opts;
 
   // ── Required-arg guards. Throw rather than return {ok:false} so a
@@ -319,6 +411,52 @@ async function prepareLiveCheckout(opts = {}) {
         const reRaw = await git(['status', '--porcelain=v1', '-b'], baseOpts);
         ({ branchInfo, dirtyFiles } = parsePorcelain(reRaw));
       }
+      // issue #608 — orphaned-agent-branch self-heal. If the tree is STILL dirty
+      // and HEAD is sitting on a DIFFERENT engine-created branch than the one
+      // THIS dispatch is about to use, the dirt is provably leftover from an
+      // earlier dispatch whose dispatch-end restore never completed (e.g. an
+      // `.git/index.lock` race against a sibling dispatch — see
+      // restoreLiveCheckoutAtDispatchEnd). Left alone, the ORIGINAL-REF CAPTURE
+      // below (Step 3) would adopt that stray branch as `originalRef`, and every
+      // future dispatch would inherit it in turn — the tree never stops
+      // orbiting agent branches and every dispatch fails LIVE_CHECKOUT_DIRTY
+      // forever (321 incidents / 12 days). Since the branch was created BY the
+      // engine (matched narrowly via `_looksLikeAgentBranch` — the literal
+      // `work/<id>` convention from shared.deriveWorkItemBranchName, never the
+      // operator's own branch), committing the leftover WIP there is exactly as
+      // safe as the existing dispatch-end self-heal: additive, fully
+      // recoverable from that branch's own history, and never touches the
+      // operator's real branch. Unconditional (not opt-in) because it is
+      // non-destructive, unlike the auto-reset path below. After committing,
+      // switch back to `mainRef` — the one ref that is always a real,
+      // non-agent baseline — so the tree stops drifting onto agent branches.
+      if (dirtyFiles.length > 0) {
+        const strayBranch = _extractBranchFromPorcelainHeader(branchInfo);
+        if (strayBranch && strayBranch !== branchName && _looksLikeAgentBranch(strayBranch)) {
+          const commitRes = await _commitAgentWipWithRetry(
+            git, baseOpts,
+            `minions: auto-save orphaned WIP from ${strayBranch} (dispatch ${dispatchId || '(unknown)'})`,
+            { sleep: _sleep },
+          );
+          if (commitRes.ok) {
+            logFn(`[live-checkout] self-healed orphaned agent branch '${strayBranch}' — committed WIP` +
+              (commitRes.attempts > 1 ? ` after ${commitRes.attempts} attempts` : '') +
+              `, switching back to '${mainRef}'`, 'info');
+            try {
+              await git(['checkout', mainRef], baseOpts);
+            } catch (backErr) {
+              logFn(`[live-checkout] could not switch back to '${mainRef}' after self-healing '${strayBranch}': ${backErr && backErr.message}`, 'warn');
+            }
+            // Re-run the dirty check. Either the tree is now clean (self-heal
+            // succeeded end-to-end) or something new appeared (rare) — either
+            // way the normal auto-reset / dirty-bail logic below sees fresh state.
+            const healRaw = await git(['status', '--porcelain=v1', '-b'], baseOpts);
+            ({ branchInfo, dirtyFiles } = parsePorcelain(healRaw));
+          } else {
+            logFn(`[live-checkout] could not self-heal orphaned agent branch '${strayBranch}' (commit failed): ${commitRes.error && commitRes.error.message}`, 'warn');
+          }
+        }
+      }
       if (dirtyFiles.length > 0) {
         // W-mqvejug6000eeb20 — opt-in auto-reset. Default behavior is to bail with
         // reason:'dirty' (spawnAgent translates to non-retryable LIVE_CHECKOUT_DIRTY
@@ -558,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)
     }
   };
@@ -641,6 +791,7 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
     log,
     writeInboxAlert,
     _git, // private injection for testing — defaults to shared.shellSafeGit
+    _sleep, // private injection for testing — defaults to a real setTimeout-based sleep
   } = opts;
 
   const logFn = (typeof log === 'function') ? log : () => {};
@@ -750,16 +901,27 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
           onAgentBranch = cur && cur === branchName;
         } catch { /* best-effort */ }
         if (onAgentBranch) {
-          try {
-            await git(['add', '-A'], baseOpts);
-            // --no-verify: skip operator commit hooks that may fail headless.
-            await git(['commit', '--no-verify', '-m', `minions: auto-save agent WIP (dispatch ${did})`], baseOpts);
+          // issue #608 — bounded retry+backoff on the commit. The 2026-06-30
+          // incident was caused by exactly this commit losing a transient
+          // `.git/index.lock` race against a sibling dispatch's git process;
+          // the previous single-attempt code gave up immediately and left the
+          // stage half-committed, which then perpetuated as a stray agent
+          // branch for every subsequent dispatch (see the orphaned-agent-branch
+          // self-heal in prepareLiveCheckout). `--no-verify` skips operator
+          // commit hooks that may fail headless.
+          const commitRes = await _commitAgentWipWithRetry(
+            git, baseOpts,
+            `minions: auto-save agent WIP (dispatch ${did})`,
+            { sleep: _sleep },
+          );
+          if (commitRes.ok) {
             result.autoCommitted = true;
-            logFn('info', `live-checkout: auto-committed agent WIP onto ${branchName} before restore (dispatch ${did})`);
-          } catch (commitErr) {
+            logFn('info', `live-checkout: auto-committed agent WIP onto ${branchName} before restore (dispatch ${did})` +
+              (commitRes.attempts > 1 ? ` after ${commitRes.attempts} attempts` : ''));
+          } else {
             // Leave the tree as-is; the plain checkout below will refuse and the
             // fallback alert fires. Never force, never discard.
-            logFn('warn', `live-checkout: could not auto-save agent WIP onto ${branchName} for ${did}: ${commitErr && commitErr.message}`);
+            logFn('warn', `live-checkout: could not auto-save agent WIP onto ${branchName} for ${did}: ${commitRes.error && commitRes.error.message}`);
           }
         }
       }
@@ -836,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
  *
@@ -902,9 +1222,17 @@ async function maybeRestoreLiveCheckoutFromRecord(opts = {}) {
 module.exports = {
   prepareLiveCheckout,
   restoreLiveCheckoutAtDispatchEnd,
+  resolveLiveCheckoutAutoStash,
+  performLiveCheckoutAutoStash,
+  applyLiveCheckoutAutoStash,
   maybeRestoreLiveCheckoutFromRecord,
   _isPartialCloneBlobError,
+  _isWorktreeConflictError,
+  _extractConflictingWorktreePath,
   _isAutoCleanableArtifact,
   _collectAutoCleanablePaths,
+  _looksLikeAgentBranch,
+  _extractBranchFromPorcelainHeader,
+  _commitAgentWipWithRetry,
   LIVE_CHECKOUT_AUTO_CLEAN_PATTERNS,
 };

package/engine/playbook.js

@@ -13,7 +13,7 @@ const { wrapUntrusted, buildSource } = require('./untrusted-fence');
 const { MINIONS_BRAND_URL } = require('./comment-format');
 
 const { safeJson, safeRead, getProjects, log, ts, dateStamp, truncateTextBytes, ENGINE_DEFAULTS, WI_STATUS, WORK_TYPE, PR_STATUS, DISPATCH_RESULT, getProjectOrg } = shared;
-const { getConfig, getDispatch, getNotes, getAgentCharter, getPrs, getKnowledgeBaseIndex, AGENTS_DIR } = queries;
+const { getConfig, getDispatch, getNotes, getPrs, getKnowledgeBaseIndex, AGENTS_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
 const PLAYBOOKS_DIR = path.join(MINIONS_DIR, 'playbooks');
@@ -1052,7 +1052,7 @@ function _checkPlaybookSections(content, context = '') {
 // Lean system prompt: agent identity + rules only (~2-4KB, never grows)
 function buildSystemPrompt(agentId, config, project) {
   const agent = config.agents[agentId] || tempAgents.get(agentId) || { name: agentId, role: 'Temporary Agent', expertise: [] };
-  const charter = getAgentCharter(agentId); // returns '' for temp agents (no charter file)
+  const charter = safeRead(path.join(AGENTS_DIR, agentId, 'charter.md')); // returns '' for temp agents (no charter file)
   project = project || getProjects(config)[0] || {};
 
   let prompt = '';

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/queries.js

@@ -722,10 +722,6 @@ function getAgentStatus(agentId) {
 // setAgentStatus removed — agent status is derived from dispatch.json.
 // Status.json files no longer exist.
 
-function getAgentCharter(agentId) {
-  return safeRead(path.join(AGENTS_DIR, agentId, 'charter.md'));
-}
-
 function getAgents(config) {
   config = config || getConfig();
   // Fall back to DEFAULT_AGENTS if config has no agents (uninitialized repo)
@@ -2063,13 +2059,21 @@ function getWorkItems(config, opts) {
   });
 
   const cacheMtimes = _snapshotWorkItemsMtimes(config);
+  // Use Date.now() here (not the `now` captured at function entry) so the
+  // 1 s TTL is measured from when the cache was BUILT, not from when the
+  // call started. On a slow or loaded machine the first cold call can take
+  // > 1 s while DB migrations run; if we used the entry-time `now`, the
+  // very next call would see (entry_time_of_call_2 − entry_time_of_call_1)
+  // >= 1 000 ms and miss the cache, defeating the cache entirely.
+  // (W-mr00aooc000i1d6b — queries-work-items-cache CI failure on slow runners)
+  const cacheSetAt = Date.now();
   if (enrich) {
     _workItemsCache = allItems;
-    _workItemsCacheAt = now;
+    _workItemsCacheAt = cacheSetAt;
     _workItemsCacheMtimes = cacheMtimes;
   } else {
     _workItemsLeanCache = allItems;
-    _workItemsLeanCacheAt = now;
+    _workItemsLeanCacheAt = cacheSetAt;
     _workItemsLeanCacheMtimes = cacheMtimes;
   }
   return allItems;
@@ -3320,7 +3324,7 @@ module.exports = {
   _buildNotesByWiMap, // exported for testing
 
   // Agents
-  getAgentStatus, getAgentCharter, getAgents, getAgentDetail,
+  getAgentStatus, getAgents, getAgentDetail,
 
   // Pull requests
   getPrs, getPullRequests,