@yemi33/minions 0.1.2381 → 0.1.2382

package/docs/engine-restart.md

@@ -70,6 +70,16 @@ If an agent is killed as an orphan and the work item retries, cooldowns use expo
 
 The engine.js *process itself* (not an agent) can crash and get auto-respawned by three independent mechanisms: `engine/supervisor.js#checkEngine` (dead-PID), `engine/supervisor.js#checkEngineHung` (stale-heartbeat), and `engine/watchdog.js` (OS-scheduled external recovery); `dashboard.js`'s in-process 30s watchdog also auto-restarts on a dead PID (the user-triggered Restart Engine button is excluded). Each successful respawn calls `shared.recordEngineRespawn(source)`, which appends `{ts, source}` to `control.json`'s `engineRespawns[]` (rolling window, default `CRASH_LOOP_WINDOW_MS` = 10 min). Once respawns within the window reach `CRASH_LOOP_THRESHOLD` (default 3), `control.crashLoopAlert` is set (dashboard-visible via `/api/status`) and a deduped (one-per-day) `notes/inbox/` alert is written; the alert clears automatically once the window rolls past the incident. Override the window/threshold via `MINIONS_CRASH_LOOP_WINDOW_MS` / `MINIONS_CRASH_LOOP_THRESHOLD` env vars.
 
+### 7. Exclusive Restart Topology
+
+Managed dashboard spawns must bind the requested port; automatic fallback remains available only for standalone `node dashboard.js` use. Before a supervisor respawn, every matching stale daemon is killed and confirmed dead. If any PID survives, the supervisor skips the replacement and retries on its next tick instead of creating a second engine or a dashboard on another port.
+
+`minions restart` verifies ownership of the exact engine, dashboard, and supervisor PIDs it spawned and rejects duplicate daemon processes. A failed verification tears down the partial stack and leaves `stop-intent.json` set so watchdogs cannot race another replacement into the failed topology.
+
+PID-bearing file locks are reaped immediately when their recorded owner is dead. The five-minute stale threshold remains for legacy locks without owner metadata and the longer safety window remains for live holders.
+
+Dashboard hot polling avoids recurring event-loop stalls: freshness-directory walks are coalesced briefly, plan scans are cached for 30 seconds and processed in cooperative batches, and quarantine-ref Git reads run asynchronously in parallel.
+
 ## Safe Restart Pattern
 
 ```bash

package/docs/worktree-lifecycle.md

@@ -77,6 +77,15 @@ distinguishes the **original worktree-preflight issue** from a
 
 ## Quarantine path (dirty / divergent)
 
+Before quarantine, a reused worktree that is filesystem-clean and strictly
+ahead of `origin/<branch>` is pushed fast-forward to origin. Dispatch close
+and stale-orphan cleanup run the same preservation check before pool return or
+worktree removal. Dirty trees and branches confirmed behind origin retain the
+quarantine fallback; transient probe, fetch, auth, and push failures leave clean
+ahead commits in place for retry. Recoverable
+`refs/minions/quarantine/*` and `refs/minions/quarantine-wip/*` refs are listed
+on Dashboard → Engine under **Quarantined Work**.
+
 When `discoverFromWorkItems` finds a worktree in a `WORKTREE_DIRTY`,
 `WORKTREE_DIVERGENT`, or post-stuck state, `_quarantineDirtyWorktree`
 moves it to `<root>/.quarantined/<basename>-<utc>` and lets the next tick

package/engine/claude-md-context.js

@@ -0,0 +1,195 @@
+/**
+ * engine/claude-md-context.js — CLAUDE.md propagation for non-Claude runtimes.
+ *
+ * W-mrdon0pe000l045a. CLAUDE.md auto-discovery is a Claude-Code-CLI-only
+ * convention (the claude binary reads CLAUDE.md itself at startup). Copilot and
+ * Codex have NO equivalent auto-load, so repo-authored CLAUDE.md files — which
+ * frequently carry load-bearing "must be kept in sync" rules and name blessed
+ * tooling — are structurally invisible to a Copilot/Codex-based fleet.
+ *
+ * This module discovers the *nearest applicable* CLAUDE.md files for a dispatch
+ * (bounded walk-UP from path hints toward the project root — NOT a full monorepo
+ * walk) and renders them into a prompt block. engine/playbook.js injects that
+ * block as a "Project instructions (CLAUDE.md)" context layer, gated on the
+ * runtime capability `claudeMdNativeDiscovery` (skip when true → Claude) and the
+ * `propagateClaudeMdForNonClaudeRuntimes` config flag.
+ *
+ * The whole point is to be CHEAP: it only stats CLAUDE.md at each ancestor
+ * directory of a small set of hint dirs (capped depth + capped file count), so
+ * it never walks a huge monorepo like office/src.
+ *
+ * This module is pure file discovery + string building — no engine state, no
+ * locking, no writes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { truncateTextBytes, ENGINE_DEFAULTS } = require('./shared');
+
+const CLAUDE_MD_FILENAME = 'CLAUDE.md';
+// Cap the number of CLAUDE.md files collected across all hints — defense against
+// a dispatch with many path hints spread across a deep tree.
+const MAX_FILES = 8;
+// Cap the walk-up depth from any single hint dir — defense for pathological deep
+// Windows paths so a single hint can't spin the loop unbounded.
+const MAX_WALK_DEPTH = 24;
+// Byte cap for the whole injected block. Reuses the same budget the sibling
+// notes / agent-memory context layers use (maxNotesPromptBytes), so CLAUDE.md
+// propagation can never balloon a prompt on a large monorepo.
+const DEFAULT_MAX_BYTES = ENGINE_DEFAULTS.maxNotesPromptBytes;
+
+function _pathEq(a, b) {
+  if (process.platform === 'win32') return a.toLowerCase() === b.toLowerCase();
+  return a === b;
+}
+
+// Is `target` inside (or equal to) `root`?
+function _isWithin(root, target) {
+  const rel = path.relative(root, target);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * Normalize a hint (a file OR directory, relative-to-root OR absolute) into an
+ * absolute directory contained within `root`. Returns null when the hint
+ * escapes the project root (path traversal guard). Non-existent hints are still
+ * resolved structurally (extension ⇒ file ⇒ parent dir; otherwise dir).
+ */
+function _hintToDir(root, hint) {
+  if (!hint || typeof hint !== 'string' || !hint.trim()) return null;
+  const cleaned = hint.trim();
+  let abs = path.isAbsolute(cleaned) ? cleaned : path.join(root, cleaned);
+  abs = path.resolve(abs);
+  if (!_isWithin(root, abs)) return null;
+  try {
+    const st = fs.statSync(abs);
+    if (st.isDirectory()) return abs;
+    return path.dirname(abs);
+  } catch {
+    // Doesn't exist on disk — infer file vs dir from a trailing extension.
+    return path.extname(abs) ? path.dirname(abs) : abs;
+  }
+}
+
+/**
+ * Discover CLAUDE.md files by walking UP from each hint directory to the project
+ * root, plus the project root itself as a guaranteed fallback. Returns entries
+ * ordered nearest-first (deepest directory first, project root last) so the
+ * caller renders "nearest wins" — the most specific instructions lead.
+ *
+ * @param {{ projectRoot: string, pathHints?: string[] }} opts
+ * @returns {{ absPath: string, relPath: string, depth: number }[]}
+ */
+function discoverClaudeMdFiles({ projectRoot, pathHints = [] } = {}) {
+  if (!projectRoot || typeof projectRoot !== 'string') return [];
+  const root = path.resolve(projectRoot);
+  try { if (!fs.statSync(root).isDirectory()) return []; } catch { return []; }
+
+  // Starting dirs: each valid hint dir, then the root itself (fallback so the
+  // project-root CLAUDE.md is always considered even with zero hints).
+  const startDirs = [];
+  for (const h of Array.isArray(pathHints) ? pathHints : []) {
+    const d = _hintToDir(root, h);
+    if (d) startDirs.push(d);
+  }
+  startDirs.push(root);
+
+  const found = new Map(); // absPath -> { depth, rel }
+  for (const start of startDirs) {
+    let dir = start;
+    let steps = 0;
+    while (steps <= MAX_WALK_DEPTH) {
+      const candidate = path.join(dir, CLAUDE_MD_FILENAME);
+      if (!found.has(candidate)) {
+        try {
+          if (fs.statSync(candidate).isFile()) {
+            const rel = path.relative(root, dir);
+            const depth = (rel === '' || rel === '.') ? 0 : rel.split(/[\\/]/).length;
+            found.set(candidate, { depth });
+          }
+        } catch { /* no CLAUDE.md at this level */ }
+      }
+      if (_pathEq(dir, root)) break;      // stop at project root (never above)
+      const parent = path.dirname(dir);
+      if (_pathEq(parent, dir)) break;    // filesystem-root guard
+      if (!_isWithin(root, parent)) break;
+      dir = parent;
+      steps++;
+    }
+  }
+
+  const entries = Array.from(found.entries()).map(([absPath, meta]) => ({
+    absPath,
+    relPath: (path.relative(root, absPath) || CLAUDE_MD_FILENAME).replace(/\\/g, '/'),
+    depth: meta.depth,
+  }));
+  // nearest-first: deepest dir first; stable tiebreak on relPath for determinism.
+  entries.sort((a, b) => (b.depth - a.depth) || a.relPath.localeCompare(b.relPath));
+  return entries.slice(0, MAX_FILES);
+}
+
+/**
+ * Build the CLAUDE.md propagation block (inner content, no outer header/fence —
+ * engine/playbook.js owns those). Reads each discovered file, labels it by its
+ * repo-relative path, and truncates to stay within `maxBytes` total. Returns
+ * `{ block, files }` where `block` is '' when nothing was found or all files
+ * were empty.
+ *
+ * @param {{ projectRoot: string, pathHints?: string[], maxBytes?: number }} opts
+ */
+function buildClaudeMdPropagationBlock({ projectRoot, pathHints = [], maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  const files = discoverClaudeMdFiles({ projectRoot, pathHints });
+  if (files.length === 0) return { block: '', files: [] };
+
+  const cap = Math.max(256, Number(maxBytes) || DEFAULT_MAX_BYTES);
+  const parts = [];
+  const included = [];
+  let used = 0;
+
+  for (const f of files) {
+    let content;
+    try { content = fs.readFileSync(f.absPath, 'utf8'); } catch { continue; }
+    if (!content || !content.trim()) continue;
+
+    const heading = `\n\n### ${f.relPath}\n\n`;
+    const headingBytes = Buffer.byteLength(heading, 'utf8');
+    const remaining = cap - used - headingBytes;
+    if (remaining <= 0) break; // no room even for the next heading
+
+    const body = truncateTextBytes(content, remaining, '\n\n_...CLAUDE.md truncated (read the full file if needed)_');
+    parts.push(heading + body);
+    used += headingBytes + Buffer.byteLength(body, 'utf8');
+    included.push(f.relPath);
+    if (used >= cap) break;
+  }
+
+  if (parts.length === 0) return { block: '', files: [] };
+  return { block: parts.join('').replace(/^\n+/, ''), files: included };
+}
+
+/**
+ * Does the named runtime auto-discover CLAUDE.md natively? Reads the adapter's
+ * `capabilities.claudeMdNativeDiscovery`. Unknown runtimes return false ("does
+ * NOT auto-discover") so propagation is the safe additive default — an
+ * unrecognized runtime is far more likely to lack native CLAUDE.md loading than
+ * to have it.
+ */
+function runtimeAutoDiscoversClaudeMd(cliName) {
+  try {
+    const { resolveRuntime } = require('./runtimes');
+    const rt = resolveRuntime(cliName);
+    return !!(rt && rt.capabilities && rt.capabilities.claudeMdNativeDiscovery);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  CLAUDE_MD_FILENAME,
+  MAX_FILES,
+  MAX_WALK_DEPTH,
+  DEFAULT_MAX_BYTES,
+  discoverClaudeMdFiles,
+  buildClaudeMdPropagationBlock,
+  runtimeAutoDiscoversClaudeMd,
+};

package/engine/consolidation.js

@@ -85,6 +85,34 @@ function _readNotesForAppendOrNull() {
   return fs.existsSync(NOTES_PATH) ? null : '';
 }
 
+// Resiliently write notes.md from inside a consolidation lock callback.
+// CRASH GUARD (#858): safeWrite -> renameSync throws EPERM on Windows when
+// notes.md is held open by another process (e.g. a leaked dashboard
+// /state/notes.md read stream). That throw used to propagate out of the
+// async consolidateWithLLM(...) chain / the regex-fallback timer callback with
+// NO surrounding try/catch, becoming an UNHANDLED PROMISE REJECTION (or an
+// uncaught timer exception) that killed the whole engine daemon. Supervisor
+// respawned it, but pooled Copilot ACP agents cannot reattach across restart,
+// so every in-flight agent was orphaned.
+//
+// This wraps safeWrite in shared._retryFsOp (extra exponential-backoff retries
+// on EPERM/EBUSY/EACCES on top of safeWrite's own short retry loop) AND a
+// try/catch, so a transient lock retries then DEFERS: returns false so the
+// caller leaves the inbox notes in place for the next tick instead of crashing.
+// Returns true on success, false if the write could not be completed.
+function _writeNotesOrDefer(content, label) {
+  try {
+    // Keep the in-lock retry budget small (safeWrite already retries EPERM ~5x
+    // internally): a few extra exponential-backoff attempts cover a slightly
+    // longer transient hold without stalling the consolidation lock.
+    shared._retryFsOp(() => safeWrite(NOTES_PATH, content), `write notes.md (${label})`, { attempts: 3, baseMs: 100 });
+    return true;
+  } catch (err) {
+    log('warn', `${label}: notes.md write failed after retries (${err?.code || ''} ${err?.message || err}) \u2014 deferring, inbox notes left for next cycle`);
+    return false;
+  }
+}
+
 // Per-agent memory files live under knowledge/agents/<agent>.md and are
 // injected into individual agent prompts (in addition to the broadcast
 // notes.md). See knowledge/agents/README.md for the convention.
@@ -971,7 +999,17 @@ function consolidateWithLLM(items, existingNotes, files, config) {
     fallbackDone = true;
     if (message) log('warn', message);
     if (err?.message) log('debug', `LLM error: ${err.message}`);
-    consolidateWithRegex(items, files, config);
+    // CRASH GUARD (#858): _fallback runs from a promise .catch AND from a
+    // setTimeout callback. An uncaught throw from consolidateWithRegex in the
+    // timer path is an uncaught exception that kills the daemon; in the .catch
+    // path it is an unhandled rejection. The notes.md write already defers on
+    // lock contention, but keep a top-level guard so no other regex-fallback
+    // failure can ever crash the engine — leave inbox notes for the next tick.
+    try {
+      consolidateWithRegex(items, files, config);
+    } catch (e) {
+      log('warn', `Regex consolidation fallback failed (${e?.code || ''} ${e?.message || e}) \u2014 inbox notes left for next cycle`);
+    }
   }
 
   const llmCall = callLLM(prompt, sysPrompt, {
@@ -1033,7 +1071,9 @@ function consolidateWithLLM(items, existingNotes, files, config) {
         // DATA-LOSS GUARD: cap size but archive the overflow instead of
         // silently discarding it (see _capNotesPreservingOverflow).
         const newContent = _capNotesPreservingOverflow(current + entry);
-        safeWrite(NOTES_PATH, newContent);
+        // CRASH GUARD (#858): defer (return false) on a transient write lock
+        // instead of throwing out of this async chain and crashing the daemon.
+        if (!_writeNotesOrDefer(newContent, 'LLM consolidation')) return false;
         return true;
       });
       if (!wrote) {
@@ -1169,7 +1209,10 @@ function consolidateWithRegex(items, files, config) {
     }
     // DATA-LOSS GUARD: cap size but archive the overflow (see LLM path).
     const newContent = _capNotesPreservingOverflow(current + entry);
-    safeWrite(NOTES_PATH, newContent);
+    // CRASH GUARD (#858): defer (return false) on a transient write lock
+    // instead of throwing out of this synchronous fallback (invoked from a
+    // timer callback and a promise .catch) and crashing the daemon.
+    if (!_writeNotesOrDefer(newContent, 'Regex consolidation')) return false;
     return true;
   });
   if (!wrote) {
@@ -1530,4 +1573,5 @@ module.exports = {
   buildCondensedKbBody,
   _alertContentHash,
   _alertHashExists,
+  _writeNotesOrDefer,
 };

package/engine/db/migrations/026-pre-dispatch-rejections.js

@@ -0,0 +1,55 @@
+function _parseObject(raw) {
+  try {
+    const value = JSON.parse(raw);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  version: 26,
+  description: 'normalize exhausted pre-dispatch rejections out of execution failures',
+  up(db) {
+    const rows = db.prepare(`
+      SELECT rowid, data
+      FROM work_items
+      WHERE status = 'failed' AND archived = 0
+    `).all();
+    const update = db.prepare(`
+      UPDATE work_items
+      SET status = 'pending', data = ?, updated_at = ?
+      WHERE rowid = ? AND archived = 0
+    `);
+    const now = Date.now();
+    for (const row of rows) {
+      const item = _parseObject(row.data);
+      if (!item || item._failureClass !== 'pre-dispatch-eval-stuck') continue;
+      const evaluation = item._preDispatchEval && typeof item._preDispatchEval === 'object'
+        ? item._preDispatchEval
+        : {};
+      const evaluatedAt = evaluation.evaluatedAt || item.failedAt || new Date(now).toISOString();
+      const history = Array.isArray(evaluation.history) ? evaluation.history : [];
+      if (history.length === 0 && evaluation.reason) {
+        history.push({
+          reason: evaluation.reason,
+          evaluatedAt,
+          description: evaluation.description || '',
+        });
+      }
+      item.status = 'pending';
+      item._pendingReason = 'pre_dispatch_eval_rejected';
+      item._preDispatchEval = {
+        ...evaluation,
+        valid: false,
+        exhausted: true,
+        exhaustedAt: evaluation.exhaustedAt || evaluatedAt,
+        history,
+      };
+      delete item._failureClass;
+      delete item.failReason;
+      delete item.failedAt;
+      update.run(JSON.stringify(item), now, row.rowid);
+    }
+  },
+};

package/engine/dispatch.js

@@ -307,10 +307,10 @@ function addToDispatch(item) {
 function _persistInvalidWorkItem(item, evaluation) {
   const meta = item?.meta;
   const itemId = meta?.item?.id;
-  if (!itemId) return { stuck: false };
+  if (!itemId) return { exhausted: false };
   let wiScope;
   try { wiScope = lifecycle().resolveWorkItemScope(meta); } catch { wiScope = null; }
-  if (!wiScope) return { stuck: false };
+  if (!wiScope) return { exhausted: false };
   // W-mrcrh5hj0017d22f — repeat-rejection cap. Compare against the
   // description snapshot from the LAST rejection so an operator edit to the
   // WI resets the counter (it deserves a fresh evaluation), while an
@@ -319,7 +319,7 @@ function _persistInvalidWorkItem(item, evaluation) {
   const maxRejections = queries.getConfig()?.engine?.preDispatchEvalMaxRejections
     ?? ENGINE_DEFAULTS.preDispatchEvalMaxRejections;
   const currentDescription = String((meta.item && meta.item.description) || '');
-  let stuck = false;
+  let exhausted = false;
   try {
     mutateWorkItems(wiScope, (items) => {
       if (!Array.isArray(items)) return items;
@@ -329,31 +329,79 @@ function _persistInvalidWorkItem(item, evaluation) {
       const prior = wi._preDispatchEval;
       const sameDescription = prior && prior.description === currentDescription;
       const rejectCount = (sameDescription ? (prior.rejectCount || 0) : 0) + 1;
+      const history = Array.isArray(prior?.history) ? prior.history.slice(-19) : [];
+      const evaluatedAt = ts();
+      history.push({
+        reason: evaluation.reason || '',
+        evaluatedAt,
+        description: currentDescription,
+      });
       wi._preDispatchEval = {
         valid: false,
         reason: evaluation.reason || '',
-        evaluatedAt: ts(),
+        evaluatedAt,
         rejectCount,
         description: currentDescription,
+        history,
       };
       if (rejectCount >= maxRejections) {
-        stuck = true;
-        wi.status = WI_STATUS.FAILED;
-        wi._failureClass = FAILURE_CLASS.PRE_DISPATCH_EVAL_STUCK;
-        wi.failReason = `pre-dispatch-eval rejected this work item ${rejectCount} times in a row ` +
-          `with an unchanged description — last reason: ${evaluation.reason || 'criteria not actionable'}`;
-        wi.failedAt = ts();
-        wi._pendingReason = 'pre_dispatch_eval_stuck';
+        exhausted = true;
+        wi.status = WI_STATUS.PENDING;
+        wi._preDispatchEval.exhausted = true;
+        wi._preDispatchEval.exhaustedAt = evaluatedAt;
+        wi._pendingReason = 'pre_dispatch_eval_rejected';
+        delete wi._failureClass;
+        delete wi.failReason;
+        delete wi.failedAt;
       }
       return items;
     }, { skipWriteIfUnchanged: true });
   } catch (e) {
     log('warn', `pre-dispatch-eval: failed to persist reason on ${itemId}: ${e.message}`);
   }
-  if (stuck) {
-    log('warn', `pre-dispatch-eval: ${itemId} rejected ${maxRejections}+ times with unchanged description — flipped to failed (PRE_DISPATCH_EVAL_STUCK) instead of re-evaluating forever`);
+  if (exhausted) {
+    log('warn', `pre-dispatch-eval: ${itemId} rejected ${maxRejections}+ times with unchanged description — paused pending operator edit`);
+  }
+  return { exhausted };
+}
+
+function _clearPreDispatchRejection(item, evaluation) {
+  const meta = item?.meta;
+  const itemId = meta?.item?.id;
+  if (!itemId) return;
+  let wiScope;
+  try { wiScope = lifecycle().resolveWorkItemScope(meta); } catch { wiScope = null; }
+  if (!wiScope) return;
+  try {
+    mutateWorkItems(wiScope, (items) => {
+      if (!Array.isArray(items)) return items;
+      const wi = items.find(w => w && w.id === itemId);
+      if (!wi || !wi._preDispatchEval) return items;
+      wi._preDispatchEval = {
+        ...wi._preDispatchEval,
+        valid: true,
+        reason: evaluation?.reason || '',
+        evaluatedAt: ts(),
+        rejectCount: 0,
+        description: String(meta.item?.description || ''),
+      };
+      delete wi._preDispatchEval.exhausted;
+      delete wi._preDispatchEval.exhaustedAt;
+      if (wi._pendingReason === 'pre_dispatch_eval_rejected') delete wi._pendingReason;
+      return items;
+    }, { skipWriteIfUnchanged: true });
+  } catch (e) {
+    log('warn', `pre-dispatch-eval: failed to clear rejection on ${itemId}: ${e.message}`);
+  }
+  try {
+    mutateDispatch((dispatch) => {
+      dispatch.review = (Array.isArray(dispatch.review) ? dispatch.review : [])
+        .filter(entry => entry?.meta?.item?.id !== itemId);
+      return dispatch;
+    });
+  } catch (e) {
+    log('warn', `pre-dispatch-eval: failed to clear review entry for ${itemId}: ${e.message}`);
   }
-  return { stuck };
 }
 
 function _routeToReviewQueue(item, evaluation) {
@@ -438,6 +486,11 @@ async function addToDispatchWithValidation(item, opts = {}) {
   if (!hasCriteria && !hasUsableDescription) {
     return addToDispatch(item);
   }
+  const priorEvaluation = wi?._preDispatchEval;
+  if (priorEvaluation?.exhausted === true
+      && priorEvaluation.description === String(wi?.description || '')) {
+    return null;
+  }
 
   // W-mq9acoo800177bcb — PRD-sourced bypass. plan-to-prd already LLM-vets
   // every item it lands in a PRD, so re-validating each materialized item
@@ -477,14 +530,13 @@ async function addToDispatchWithValidation(item, opts = {}) {
     return addToDispatch(item);
   }
 
-  if (!evaluation || evaluation.valid !== false) return addToDispatch(item);
+  if (!evaluation || evaluation.valid !== false) {
+    _clearPreDispatchRejection(item, evaluation);
+    return addToDispatch(item);
+  }
 
-  const { stuck } = _persistInvalidWorkItem(item, evaluation);
-  // W-mrcrh5hj0017d22f: once the WI has been flipped to failed for
-  // repeat-rejection, don't also push it into the review queue — the
-  // failed status already stops future discovery ticks from re-evaluating
-  // it, and a review-queue entry would just be a stale duplicate signal.
-  if (!stuck) _routeToReviewQueue(item, evaluation);
+  const { exhausted } = _persistInvalidWorkItem(item, evaluation);
+  if (!exhausted) _routeToReviewQueue(item, evaluation);
   log('warn', `pre-dispatch-eval: blocked work item ${wi.id} — ${evaluation.reason || 'criteria not actionable'}`);
   return null;
 }