@yemi33/minions 0.1.2336 → 0.1.2338

package/bin/minions.js

@@ -794,6 +794,13 @@ function getPkgVersion() {
   try { return require(path.join(PKG_ROOT, 'package.json')).version; } catch { return '0.0.0'; }
 }
 
+// Same as getPkgVersion() but bypasses require()'s module cache — needed to
+// see what `npm install -g` actually wrote to disk *within the same process*
+// (require() would keep returning the version captured at process start).
+function getPkgVersionFresh() {
+  try { return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version; } catch { return null; }
+}
+
 function getInstalledVersion() {
   try {
     const vFile = path.join(MINIONS_HOME, '.minions-version');
@@ -1279,8 +1286,30 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
     saveInstalledVersion(getPkgVersion());
     console.log(`  Version synced to ${getPkgVersion()} (dev/symlink install — pull from git to update code)`);
   } else {
+    const preVersion = getPkgVersionFresh();
+    // Resolve the target version explicitly BEFORE installing, and pin the
+    // install to that exact version instead of a floating `@latest` tag. This
+    // avoids a race where `npm view` (used here and by `minions version`) and
+    // a separate `npm install -g pkg@latest` resolve `latest` against npm's
+    // registry-metadata cache at different times and land on different
+    // versions — the metadata cache has its own TTL, independent of tarball
+    // integrity checks, so a stale local packument can make `npm install -g
+    // pkg@latest` silently reinstall an already-cached older version even
+    // though `npm view pkg version` reports a newer one (W-mr9k4a5x00090184).
+    let targetVersion;
+    try {
+      targetVersion = execSync('npm view @yemi33/minions version', { encoding: 'utf8', timeout: 15000, windowsHide: true }).trim();
+    } catch (e) {
+      console.error('  Failed to resolve the latest version from the npm registry:', e.message);
+      process.exit(1);
+    }
+    if (!targetVersion) {
+      console.error('  Failed to resolve the latest version from the npm registry (empty response).');
+      process.exit(1);
+    }
+
     try {
-      execSync('npm install -g @yemi33/minions@latest', { stdio: 'inherit', timeout: 120000 });
+      execSync(`npm install -g @yemi33/minions@${targetVersion}`, { stdio: 'inherit', timeout: 120000 });
     } catch (e) {
       console.error('  npm update failed:', e.message);
       process.exit(1);
@@ -1288,6 +1317,24 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
     // Equivalent to `minions init --force --skip-start`, but avoids recursing through
     // the global shim while npm is still settling the updated install.
     runPostUpdateInit();
+
+    // Verify the install actually advanced to the resolved target version. A
+    // zero exit from `npm install` only means npm performed SOME install/relink
+    // action — it does NOT guarantee the resolved version moved forward. Re-read
+    // package.json fresh from disk (bypassing require()'s cache, same reasoning
+    // as getPkgVersionFresh()) so we see exactly what npm wrote, and fail loudly
+    // instead of restarting the engine/dashboard on stale code.
+    const installedVersion = getPkgVersionFresh();
+    if (installedVersion !== targetVersion) {
+      console.error(`\n  ERROR: Update did not advance as expected.`);
+      console.error(`  Before update:      ${preVersion || 'unknown'}`);
+      console.error(`  Resolved target:    ${targetVersion} (from npm registry, resolved before install)`);
+      console.error(`  On disk after npm:  ${installedVersion || 'unknown'} (${PKG_ROOT})`);
+      console.error(`  This usually means npm resolved a stale local registry-metadata cache.`);
+      console.error(`  Try:   npm cache clean --force`);
+      console.error(`  Then:  minions update\n`);
+      process.exit(1);
+    }
   }
   // Restart engine + dashboard so they pick up the new code. With --no-wait the
   // restart is spawned detached so the caller (e.g. a DevBox maintenance task)

package/engine/ado.js

@@ -2623,6 +2623,40 @@ async function prExists(adoOrg, adoProject, adoRepo, prNumber) {
   }
 }
 
+/**
+ * W-mr9jo2n2000667ad (bug B) — fetch the list of file paths an ADO PR
+ * touched, so the stale-PR-dispatch pruner can verify a fix WI's scope
+ * actually overlaps the merged/abandoned PR before cancelling it on status
+ * alone. Reads the latest iteration's changes. Returns null on any failure
+ * (no token / network / missing iterations) — callers must treat null as
+ * "unknown", not "no files changed".
+ */
+async function getPrChangedFiles(project, prNumber) {
+  const n = parseInt(prNumber, 10);
+  if (!project || !Number.isInteger(n) || n <= 0) return null;
+  const token = await getAdoToken();
+  if (!token) return null;
+  const orgBase = getAdoOrgBase(project);
+  const adoProj = project.adoProject;
+  const adoRepo = getAdoRepositoryLookupKey(project);
+  if (!orgBase || !adoProj || !adoRepo) return null;
+  try {
+    const itersUrl = `${orgBase}/${encodeURIComponent(adoProj)}/_apis/git/repositories/${encodeURIComponent(adoRepo)}/pullrequests/${encodeURIComponent(String(n))}/iterations?api-version=7.1`;
+    const iters = await adoFetch(itersUrl, token);
+    const iterList = iters?.value;
+    if (!Array.isArray(iterList) || !iterList.length) return null;
+    const latestId = iterList[iterList.length - 1]?.id;
+    if (!latestId) return null;
+    const changesUrl = `${orgBase}/${encodeURIComponent(adoProj)}/_apis/git/repositories/${encodeURIComponent(adoRepo)}/pullrequests/${encodeURIComponent(String(n))}/iterations/${latestId}/changes?api-version=7.1`;
+    const changes = await adoFetch(changesUrl, token);
+    const entries = changes?.changeEntries;
+    if (!Array.isArray(entries)) return null;
+    return entries.map(e => e?.item?.path).filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Fetch live PR and build status for a single PR number.
  * Used by engine/ado-status.js so agents can check CI without raw curl calls.
@@ -3017,6 +3051,7 @@ module.exports = {
   getAdoThrottleState,
   fetchAdoPrMetadata,
   prExists, // issue #246 — confirm a loose ref points at a PR (not a work item) before stamping
+  getPrChangedFiles, // W-mr9jo2n2000667ad — stale-PR-pruner scope-overlap verification
   fetchSinglePrBuildStatus,
   findOpenPrOnBranch,
   applyAdoPrMetadata, // #3079 — exported for unit tests of targetRefName + retarget reset

package/engine/dispatch.js

@@ -573,6 +573,50 @@ function cancelSourceWorkItemForPrunedDispatch(entry, reason) {
   return cancelled;
 }
 
+/**
+ * W-mr9jo2n2000667ad (bug B) — best-effort resolution of the work item behind
+ * a pending dispatch entry, used only by the scope-overlap gate below.
+ */
+function _resolveWorkItemForPrunedEntry(entry) {
+  const itemId = entry?.meta?.item?.id;
+  if (!itemId) return null;
+  try {
+    const wiPath = lifecycle().resolveWorkItemPath(entry.meta);
+    if (!wiPath) return null;
+    const items = safeJsonArr(wiPath);
+    return items.find(w => w && w.id === itemId) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * W-mr9jo2n2000667ad (bug B) — fetch the changed-file list for the dispatch's
+ * targeted PR from the live host API. Returns null (unknown) on any failure
+ * or unsupported host so callers fail open to the pre-existing cancel
+ * behavior rather than getting stuck.
+ */
+async function _fetchChangedFilesForPrunedEntry(entry, project) {
+  const prNumber = shared.getPrNumber(entry?.meta?.pr);
+  if (prNumber == null || !project) return null;
+  const host = String(project.repoHost || '').toLowerCase();
+  try {
+    if (host === 'github') {
+      const github = require('./github');
+      const slug = github.getRepoSlug(project);
+      if (!slug) return null;
+      return await github.getPrChangedFiles(slug, prNumber);
+    }
+    if (host === 'ado' || !host) {
+      const ado = require('./ado');
+      return await ado.getPrChangedFiles(project, prNumber);
+    }
+  } catch (e) {
+    log('warn', `pruneStalePrDispatches: failed fetching changed files for ${entry.id}: ${e.message}`);
+  }
+  return null;
+}
+
 function pruneStalePrDispatches(config = queries.getConfig()) {
   const removed = [];
   mutateDispatch((dispatch) => {
@@ -593,6 +637,96 @@ function pruneStalePrDispatches(config = queries.getConfig()) {
   return removed.length;
 }
 
+// Reasons produced by getStalePrDispatchReason's `tracked.status !== ACTIVE`
+// branch (`PR <id> is <merged|abandoned|closed>`) are the ONLY ones gated by
+// the scope-overlap check below — context-only and branch-mismatch reasons
+// are independent of file scope and prune exactly as before.
+const _MERGED_OR_ABANDONED_REASON_RE = /\bis (merged|abandoned|closed)$/i;
+
+/**
+ * Async variant of `pruneStalePrDispatches` (bug B, W-mr9jo2n2000667ad):
+ * before hard-cancelling a `fix`-type work item purely because its targeted
+ * PR is now merged/abandoned/closed, verify the WI's own scope (file paths
+ * mentioned in its title/description, or an explicit `files`/`scope.files`
+ * field) actually appears in that PR's changed-file diff. If the WI has
+ * discoverable scope hints AND the PR's changed files can be fetched AND
+ * the two sets are disjoint, the WI is almost certainly unrelated to the PR
+ * (e.g. a false-positive `targetPr` stamp from a scratch-filename substring
+ * — see extractPrRefFromText hardening) — leave the dispatch pending and
+ * write an inbox alert for human review instead of silently cancelling it.
+ *
+ * Falls back to the original unconditional-cancel behavior when scope hints
+ * are absent, the PR's changed files can't be fetched, or the overlap check
+ * finds a genuine match — this only tightens the false-positive path, it
+ * never blocks a legitimate "PR merged, WI resolved" cancellation.
+ *
+ * Engine callers should await this; the sync `pruneStalePrDispatches` above
+ * is kept for callers/tests that don't need the network-backed scope check.
+ */
+async function pruneStalePrDispatchesAsync(config = queries.getConfig()) {
+  const snapshot = queries.getDispatch();
+  const pending = Array.isArray(snapshot?.pending) ? snapshot.pending : [];
+
+  const reasonsById = new Map();
+  for (const entry of pending) {
+    const reason = getStalePrDispatchReason(entry, config);
+    if (reason) reasonsById.set(entry.id, reason);
+  }
+
+  const flaggedForReview = [];
+  for (const entry of pending) {
+    const reason = reasonsById.get(entry.id);
+    if (!reason) continue;
+    if (entry.type !== WORK_TYPE.FIX || !_MERGED_OR_ABANDONED_REASON_RE.test(reason)) continue;
+    try {
+      const wi = _resolveWorkItemForPrunedEntry(entry);
+      const scopePaths = shared.extractScopeFilePathsFromWorkItem(wi);
+      if (!scopePaths.length) continue; // unknown scope — keep legacy cancel behavior
+
+      const project = _resolveDispatchProject(entry.meta.project, config);
+      const changedFiles = await _fetchChangedFilesForPrunedEntry(entry, project);
+      const overlap = shared.scopeOverlapsPrChangedFiles(scopePaths, changedFiles);
+      if (overlap === false) {
+        reasonsById.delete(entry.id);
+        flaggedForReview.push({ entry, reason, scopePaths, changedFiles });
+      }
+      // overlap === true → genuine match, fall through to cancel as before.
+      // overlap === null → changed files unavailable, fail open to legacy cancel.
+    } catch (e) {
+      log('warn', `pruneStalePrDispatches: scope-overlap check failed for ${entry.id}: ${e.message}`);
+      // best-effort — fall through to legacy cancel behavior
+    }
+  }
+
+  const removed = [];
+  mutateDispatch((dispatch) => {
+    dispatch.pending = (dispatch.pending || []).filter(entry => {
+      const reason = reasonsById.get(entry.id);
+      if (!reason) return true;
+      removed.push({ entry, reason });
+      return false;
+    });
+    return dispatch;
+  });
+
+  for (const { entry, reason } of removed) {
+    try { deleteDispatchPromptSidecar(entry); } catch { /* cleanup best-effort */ }
+    const cancelled = cancelSourceWorkItemForPrunedDispatch(entry, reason);
+    log('info', `Dropped stale PR dispatch ${entry.id}: ${reason}${cancelled ? ' (source work item cancelled)' : ''}`);
+  }
+
+  for (const { entry, reason, scopePaths } of flaggedForReview) {
+    const itemId = entry?.meta?.item?.id || entry.id;
+    const msg = `Stale-PR-dispatch pruner kept ${itemId} pending: targetPr ${reason}, but the WI's ` +
+      `scope (${scopePaths.join(', ')}) does not appear in that PR's diff. Not auto-cancelling — ` +
+      `flagging for human review.`;
+    log('warn', `pruneStalePrDispatches: ${msg}`);
+    try { writeInboxAlert(`stale-pr-scope-mismatch-${itemId}`, msg); } catch { /* best-effort */ }
+  }
+
+  return removed.length;
+}
+
 // ─── Retryable Failure Classification ────────────────────────────────────────
 
 function isRetryableFailureReason(reason = '', failureClass = '') {
@@ -1315,6 +1449,7 @@ module.exports = {
   updateAgentStatus,
   getStalePrDispatchReason,
   pruneStalePrDispatches,
+  pruneStalePrDispatchesAsync, // W-mr9jo2n2000667ad — scope-overlap-verified variant; engine.js tick should await this
   cancelPendingDispatchesForPr,
   cleanDispatchEntries,
   cancelPendingWorkItems,

package/engine/github.js

@@ -420,6 +420,22 @@ async function prExists(slug, prNumber, opts = {}) {
   return null;
 }
 
+/**
+ * W-mr9jo2n2000667ad (bug B) — fetch the list of file paths a GitHub PR
+ * touched, so the stale-PR-dispatch pruner can verify a fix WI's scope
+ * actually overlaps the merged/abandoned PR before cancelling it on status
+ * alone. Paginated (a PR can touch more than the default 30-file page).
+ * Returns null on any failure (network / auth / 404) — callers must treat
+ * null as "unknown", not "no files changed".
+ */
+async function getPrChangedFiles(slug, prNumber) {
+  const n = parseInt(prNumber, 10);
+  if (!slug || !Number.isInteger(n) || n <= 0) return null;
+  const result = await ghApi(`/pulls/${n}/files`, slug, { paginate: true });
+  if (!Array.isArray(result)) return null;
+  return result.map(f => f && f.filename).filter(Boolean);
+}
+
 const BUILD_ERROR_LOG_MAX_LINES = 150;
 
 /**
@@ -1961,6 +1977,7 @@ module.exports = {
   getGhThrottleState,
   ghApi, // P-8c1b6e45 — used by engine/shared-branch-pr-reconcile.js to list open PRs on a feature branch
   prExists, // issue #246 — confirm a loose ref points at a PR (not an issue) before stamping
+  getPrChangedFiles, // W-mr9jo2n2000667ad — stale-PR-pruner scope-overlap verification
   // Exported for testing
   isGitHub,
   getRepoSlug,

package/engine/runtimes/claude.js

@@ -652,8 +652,26 @@ function createStreamConsumer(ctx) {
   let claudeJoinedText = '';
   const claudeStreamBlocks = new Map();
 
+  // Only the TRAILING run of text blocks (since the last non-text block)
+  // contributes to claudeJoinedText — a tool_use/thinking block closes the
+  // run so an earlier text block never welds onto a later one within the
+  // SAME message (W-mr9jj2vx000 — CC response duplicates/welds the final
+  // answer after ~15 tool calls). Claude can emit content as
+  // [text, tool_use, tool_use, ..., text] in one message when
+  // --include-partial-messages streams multiple parallel tool calls before
+  // a trailing answer; without this, content_block_delta blindly appended
+  // every text delta onto the same buffer regardless of the tool_use block
+  // in between, producing "<narration><tool icon><narration><answer>" with
+  // no paragraph break and no new segment (segmentSeq never bumped because
+  // stream-event tool_use blocks don't call ctx.pushToolUse).
   function _rebuildClaudeJoinedText() {
-    claudeJoinedText = Array.from(claudeStreamBlocks.keys()).sort((a, b) => a - b)
+    const indices = Array.from(claudeStreamBlocks.keys()).sort((a, b) => a - b);
+    let start = 0;
+    for (let i = indices.length - 1; i >= 0; i--) {
+      const block = claudeStreamBlocks.get(indices[i]);
+      if (!block || block.type !== 'text') { start = i + 1; break; }
+    }
+    claudeJoinedText = indices.slice(start)
       .map(index => claudeStreamBlocks.get(index))
       .filter(block => block && block.type === 'text' && block.text)
       .map(block => block.text)
@@ -673,6 +691,13 @@ function createStreamConsumer(ctx) {
       const block = event.content_block || {};
       claudeStreamBlocks.set(index, { type: block.type || '', text: block.text || '' });
       if (THINKING_BLOCK_TYPES.has(block.type)) ctx.notifyThinking();
+      // A non-text block (tool_use/thinking) closes the current text run —
+      // reset the hot-path accumulator so the NEXT text block starts fresh
+      // instead of welding onto text from before this block. `ctx.pushText`
+      // already opens a new segment when the pushed value doesn't extend
+      // `lastTextSent` (see engine/llm.js), so this reset is sufficient to
+      // both stop the weld and trigger the segment boundary.
+      if (block.type !== 'text') claudeJoinedText = '';
       // Out-of-order block landing: rebuild from the Map. Common case is
       // monotonic in-order arrival, where the trailing-append branch wins.
       const indices = Array.from(claudeStreamBlocks.keys());
@@ -735,21 +760,27 @@ function createStreamConsumer(ctx) {
 
     if (obj.type === 'assistant' && Array.isArray(obj.message?.content)) {
       // Claude assistant turn: content blocks (text + tool_use).
-      // Multi-text-block messages (with --include-partial-messages) need their
-      // text JOINED before pushText, otherwise each block overwrites the prior.
+      // Multi-text-block messages (with --include-partial-messages) need
+      // consecutive text blocks JOINED before pushText, otherwise each block
+      // overwrites the prior. But a tool_use block closes the current text
+      // run — reset the accumulator on tool_use so trailing text starts a
+      // fresh segment instead of welding onto text from before the tool
+      // call(s) (W-mr9jj2vx0004bbb9 follow-up: this full-envelope path hits
+      // the same weld bug as the stream_event path above).
       let assistantText = '';
       for (const block of obj.message.content) {
         if (block?.type === 'text' && block.text) {
           assistantText += block.text;
+          ctx.pushText(assistantText);
         } else if (THINKING_BLOCK_TYPES.has(block?.type)) {
           ctx.notifyThinking();
         } else if (block?.type === 'tool_use' && block.name) {
           // Thread the tool_use id so the dashboard can flip this chip from
           // pending → completed/failed when the matching tool_result lands.
           ctx.pushToolUse(block.name, block.input || {}, block.id);
+          assistantText = '';
         }
       }
-      if (assistantText) ctx.pushText(assistantText);
     }
 
     if (obj.type === 'user' && Array.isArray(obj.message?.content)) {

package/engine/shared.js

@@ -6777,6 +6777,12 @@ function parsePrUrl(url) {
 // `isPrTargeted` paths intact and prevents PR-feedback fix WIs from being
 // dispatched on a fresh `work/<wi-id>` branch when only the description /
 // references[] carried the PR pointer (issue #2999).
+// Reject a digit-string match when it's immediately followed by a
+// file-extension-like suffix (".diff", ".json", ".patch", ...) — a strong
+// signal the match is actually a scratch/diff filename fragment (e.g.
+// "lambert-pr685.diff") rather than a genuine PR reference.
+const _FOLLOWED_BY_FILE_EXT_RE = /^\.[A-Za-z0-9]{1,8}\b/;
+
 function extractPrRefFromText(value) {
   const text = String(value || '');
   if (!text.trim()) return null;
@@ -6784,10 +6790,23 @@ function extractPrRefFromText(value) {
   if (urlMatch) return String(urlMatch[0] || '').replace(/[),.;:]+$/g, '');
   const canonicalMatch = text.match(/\b(?:github|ado):[^\s#]+#\d+\b/i);
   if (canonicalMatch) return canonicalMatch[0];
+  // W-mr9jo2n2000667ad (bug A): require a clear delimiter — "#", "-", or
+  // whitespace — between "PR"/"pull request"/"pullrequest" and the digits.
+  // A bare digit-adjacent "pr" substring (e.g. "pr685" inside
+  // "lambert-pr685.diff") is very likely part of a scratch/diff filename, not
+  // a genuine "see PR #685" reference, and must NOT match. Also reject when
+  // the digits are immediately followed by a file extension, even when a
+  // delimiter IS present (guards "PR-685.diff"-style scratch filenames too).
   const legacyMatch = text.match(/\bPR-(\d+)\b/i);
-  if (legacyMatch) return legacyMatch[1];
-  const numberMatch = text.match(/\b(?:pr|pull\s+request|pullrequest)\s*#?\s*(\d+)\b/i);
-  return numberMatch ? numberMatch[1] : null;
+  if (legacyMatch && !_FOLLOWED_BY_FILE_EXT_RE.test(text.slice(legacyMatch.index + legacyMatch[0].length))) {
+    return legacyMatch[1];
+  }
+  const numberMatch = text.match(/\b(?:pr|pull\s+request|pullrequest)\s*[#-]\s*(\d+)\b/i)
+    || text.match(/\b(?:pr|pull\s+request|pullrequest)\s+(\d+)\b/i);
+  if (numberMatch && !_FOLLOWED_BY_FILE_EXT_RE.test(text.slice(numberMatch.index + numberMatch[0].length))) {
+    return numberMatch[1];
+  }
+  return null;
 }
 
 // Cap for the description-text fallback scan in `extractWorkItemPrRef`.
@@ -7002,6 +7021,86 @@ function extractWorkItemPrRef(item) {
   return extractPrRefFromText(item.title) || null;
 }
 
+// ─── Work-item scope vs PR-diff overlap (bug B, W-mr9jo2n2000667ad) ─────────
+//
+// `pruneStalePrDispatches` used to cancel a fix-type WI the moment its
+// `targetPr` pointed at a merged/abandoned PR, with no check that the PR
+// actually touched the files the WI was about. A cleanup WI whose targetPr
+// was itself a false-positive stamp (see extractPrRefFromText hardening
+// above) got silently cancelled even though the merged PR never touched the
+// WI's actual scope. `extractScopeFilePathsFromWorkItem` + `scopeOverlapsPrChangedFiles`
+// let the pruner verify overlap before treating "PR merged" as "WI resolved".
+
+/**
+ * Best-effort extraction of file-path-like scope hints from a work item.
+ * Prefers an explicit structured scope (`item.files` or `item.scope.files`
+ * array — either may be populated by a caller/agent that already knows the
+ * exact touched paths). Falls back to scanning title + description for
+ * backtick-quoted code spans (the common "delete `foo/bar.js`" convention)
+ * and bare path-like / dotted-filename tokens. Returns [] when nothing
+ * scope-like is found — callers must treat [] as "unknown scope", not "no
+ * overlap", and fall back to their pre-existing behavior.
+ */
+function extractScopeFilePathsFromWorkItem(item) {
+  if (!item || typeof item !== 'object') return [];
+  const explicit = Array.isArray(item.files) ? item.files
+    : Array.isArray(item?.scope?.files) ? item.scope.files
+      : null;
+  if (explicit && explicit.length) {
+    return explicit.map(f => String(f || '').trim()).filter(Boolean);
+  }
+  const text = `${item.title || ''}\n${item.description || ''}`;
+  if (!text.trim()) return [];
+  const paths = new Set();
+  // Backtick-quoted code spans: `path/to/file.ext` or `bare-filename`.
+  const codeSpanRe = /`([^`\n]{1,200})`/g;
+  let m;
+  while ((m = codeSpanRe.exec(text))) {
+    const candidate = m[1].trim();
+    if (candidate && !/\s/.test(candidate)) paths.add(candidate);
+  }
+  // Bare path-like tokens: contain a '/' (directory-qualified) or end in a
+  // dotted extension (bare filename mentioned in prose).
+  const pathTokenRe = /\b[\w.-]+\/[\w./-]+\b|\b[\w-]+\.[A-Za-z0-9]{1,12}\b/g;
+  while ((m = pathTokenRe.exec(text))) {
+    paths.add(m[0]);
+  }
+  return Array.from(paths);
+}
+
+/**
+ * Does `scopePaths` (from extractScopeFilePathsFromWorkItem) intersect
+ * `changedFiles` (a PR's changed-file paths)? Matches on exact path,
+ * suffix (directory-qualified scope hint vs a deeper repo path), or bare
+ * filename (basename) equality so "lambert-pr685.diff" mentioned in prose
+ * matches a changed path like "scratch/lambert-pr685.diff".
+ *
+ * Returns:
+ *   true  — at least one scope hint matches a changed file
+ *   false — scope hints and changed files are both known and disjoint
+ *   null  — unknown (no scope hints extracted, or changedFiles unavailable)
+ *           — callers must treat null as "can't verify", not "no overlap".
+ */
+function scopeOverlapsPrChangedFiles(scopePaths, changedFiles) {
+  if (!Array.isArray(scopePaths) || !scopePaths.length) return null;
+  if (!Array.isArray(changedFiles) || !changedFiles.length) return null;
+  const normalize = p => String(p || '').replace(/^\.\//, '').replace(/\\/g, '/').toLowerCase();
+  const changedNorm = changedFiles.map(normalize).filter(Boolean);
+  const changedBase = new Set(changedNorm.map(p => p.split('/').pop()));
+  const changedSet = new Set(changedNorm);
+  for (const raw of scopePaths) {
+    const p = normalize(raw);
+    if (!p) continue;
+    if (changedSet.has(p)) return true;
+    const base = p.split('/').pop();
+    if (base && changedBase.has(base)) return true;
+    for (const cf of changedNorm) {
+      if (cf.endsWith('/' + p) || p.endsWith('/' + cf)) return true;
+    }
+  }
+  return false;
+}
+
 function getProjectPrScope(project) {
   if (!project) return '';
   const host = String(project.repoHost || '').toLowerCase();
@@ -9531,6 +9630,8 @@ module.exports = {
   extractPrRefFromText,
   extractWorkItemPrRef,
   extractStructuredWorkItemPrRef,
+  extractScopeFilePathsFromWorkItem,
+  scopeOverlapsPrChangedFiles,
   rewriteInboxRefsAcrossProjects,
   _artifactNoteFileToken, // exported so the one-time note-link backfill shares the token grammar
   getProjectPrScope,

package/engine.js

@@ -120,7 +120,7 @@ const READ_ONLY_ROOT_TASK_TYPES = shared.READ_ONLY_ROOT_TASK_TYPES;
 // ─── Dispatch Management (extracted to engine/dispatch.js) ───────────────────
 
 const { mutateDispatch, addToDispatch, addToDispatchWithValidation, isRetryableFailureReason, completeDispatch,
-  writeInboxAlert, updateAgentStatus, pruneStalePrDispatches } = require('./engine/dispatch');
+  writeInboxAlert, updateAgentStatus, pruneStalePrDispatches, pruneStalePrDispatchesAsync } = require('./engine/dispatch');
 
 // ─── Timeout / Steering / Idle (extracted to engine/timeout.js) ──────────────
 
@@ -10391,7 +10391,8 @@ async function tickInner() {
     } catch (err) { log('warn', `Stall detection error: ${err?.message || err}`); }
   }
 
-  try { pruneStalePrDispatches(config); } catch (e) { log('warn', 'prune stale PR dispatches: ' + e.message); }
+  try { await pruneStalePrDispatchesAsync(config); } catch (e) { log('warn', 'prune stale PR dispatches: ' + e.message); }
+  if (_isTickStale(myGeneration)) return;
 
   // Process pending dispatches before discovery. discoverWork() runs
   // pre-dispatch LLM validation for newly found work; a slow validator must not
@@ -10914,7 +10915,7 @@ module.exports = {
   validateConfig,
 
   // Dispatch management (re-exported from engine/dispatch.js)
-  mutateDispatch, addToDispatch, addToDispatchWithValidation, isRetryableFailureReason, completeDispatch, writeInboxAlert, updateAgentStatus, pruneStalePrDispatches,
+  mutateDispatch, addToDispatch, addToDispatchWithValidation, isRetryableFailureReason, completeDispatch, writeInboxAlert, updateAgentStatus, pruneStalePrDispatches, pruneStalePrDispatchesAsync,
   activeProcesses, realActivityMap, engineRestartGraceExempt,
   get engineRestartGraceUntil() { return engineRestartGraceUntil; },
   set engineRestartGraceUntil(v) { engineRestartGraceUntil = v; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2336",
+  "version": "0.1.2338",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"