@yemi33/minions 0.1.1988 → 0.1.1989

package/README.md

@@ -657,7 +657,7 @@ To move to a new machine: `npm install -g @yemi33/minions && minions init --forc
     # Core orchestration
     shared.js            queries.js            cli.js
     lifecycle.js         dispatch.js           cooldown.js
-    timeout.js           steering.js           recovery.js
+    timeout.js           steering.js
     pre-dispatch-eval.js
     # Discovery, routing, playbooks
     routing.js           playbook.js           cleanup.js

package/dashboard/js/command-center.js

@@ -1013,7 +1013,27 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
       for (var li = 0; li < lines.length; li++) {
         var line = lines[li];
         if (!line.startsWith('data: ')) continue;
-        try { await _handleEvent(JSON.parse(line.slice(6))); } catch {}
+        // W-mpdavudb000v8446 — these used to swallow ALL errors via `catch {}`,
+        // hiding JSON.parse failures AND any DOM/render exception thrown by
+        // _handleEvent. When chunks=2 outcome=done server-side but the user
+        // saw thinking dots forever, this was the most likely observability
+        // hole: a render error in updateStreamDiv / addMsg / renderMd would
+        // disappear silently and the loop would keep reading. Log with enough
+        // context (event type, tab, error message) to triage from the browser
+        // console without dumping raw event payloads (which may include user
+        // content). Failure is still non-fatal — we keep reading the stream
+        // so the `done` event still has a chance to flip terminalEventSeen.
+        var rawJson = line.slice(6);
+        var evt;
+        try { evt = JSON.parse(rawJson); }
+        catch (parseErr) {
+          try { console.error('[cc-sse] parse-failed', { tab: activeTabId, len: rawJson.length, error: String(parseErr && parseErr.message || parseErr) }); } catch (_e) {}
+          continue;
+        }
+        try { await _handleEvent(evt); }
+        catch (handleErr) {
+          try { console.error('[cc-sse] handle-failed', { tab: activeTabId, type: evt && evt.type, error: String(handleErr && handleErr.message || handleErr), stack: handleErr && handleErr.stack }); } catch (_e) {}
+        }
       }
     }
     if (buf.trim()) {
@@ -1021,7 +1041,17 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
       for (var ri = 0; ri < remainingLines.length; ri++) {
         var rline = remainingLines[ri];
         if (!rline.startsWith('data: ')) continue;
-        try { await _handleEvent(JSON.parse(rline.slice(6))); } catch {}
+        var trailRaw = rline.slice(6);
+        var trailEvt;
+        try { trailEvt = JSON.parse(trailRaw); }
+        catch (parseErr) {
+          try { console.error('[cc-sse] parse-failed-trailing', { tab: activeTabId, len: trailRaw.length, error: String(parseErr && parseErr.message || parseErr) }); } catch (_e) {}
+          continue;
+        }
+        try { await _handleEvent(trailEvt); }
+        catch (handleErr) {
+          try { console.error('[cc-sse] handle-failed-trailing', { tab: activeTabId, type: trailEvt && trailEvt.type, error: String(handleErr && handleErr.message || handleErr), stack: handleErr && handleErr.stack }); } catch (_e) {}
+        }
       }
     }
     return { interrupted: !terminalEventSeen, reconnectable: true };

package/dashboard/js/settings.js

@@ -106,6 +106,7 @@ async function openSettings() {
         settingsToggle('GitHub Polling', 'set-ghPollEnabled', e.ghPollEnabled !== false, 'Keeps GitHub PR build results, votes, and comments fresh each tick; GitHub PR dispatch gates are inert when this is off') +
       '</div>' +
       '<div style="margin-top:10px;padding-top:10px;border-top:1px solid var(--border);display:flex;flex-direction:column;gap:4px">' +
+        settingsToggle('Auto-apply review vote to PR', 'set-autoApplyReviewVote', !!e.autoApplyReviewVote, 'When ON, Minions review verdicts (APPROVE / REQUEST_CHANGES) automatically flip the platform vote on ADO/GitHub. When OFF (default), verdicts are informational only and the human casts the final vote.') +
         settingsToggle('Auto-fix Builds', 'set-autoFixBuilds', e.autoFixBuilds !== false, 'Shared dispatch gate: auto-fix agent when a PR build fails; also requires that PR provider polling is enabled') +
         settingsToggle('Auto-fix Conflicts', 'set-autoFixConflicts', e.autoFixConflicts !== false, 'Shared dispatch gate: auto-fix agent when a PR merge conflict is detected; also requires that PR provider polling is enabled') +
         settingsToggle('Auto-review PRs', 'set-autoReviewPrs', e.autoReviewPrs !== false, 'Shared dispatch gate: review agent for newly opened agent PRs; also requires that PR provider polling is enabled') +
@@ -568,6 +569,7 @@ async function saveSettings() {
       autoDecompose: document.getElementById('set-autoDecompose').checked,
       allowTempAgents: document.getElementById('set-allowTempAgents').checked,
       autoArchive: document.getElementById('set-autoArchive').checked,
+      autoApplyReviewVote: document.getElementById('set-autoApplyReviewVote').checked,
       autoFixBuilds: document.getElementById('set-autoFixBuilds').checked,
       autoFixConflicts: document.getElementById('set-autoFixConflicts').checked,
       autoReviewPrs: document.getElementById('set-autoReviewPrs').checked,

package/dashboard.js

@@ -462,6 +462,38 @@ function resolveManualPrLinkProject(url, projectName, projects = PROJECTS) {
     };
   }
 
+  // Lenient ADO match: repo segment may be a GUID that matches repositoryId
+  if (matches.length === 0 && prScope.startsWith('ado:')) {
+    const lenientMatches = projects.filter(p => shared.isAdoPrScopeCompatible(prScope, p));
+    if (lenientMatches.length === 1) {
+      const targetProject = lenientMatches[0];
+      return {
+        project: targetProject,
+        resolution: {
+          reason: 'inferred',
+          scope: prScope,
+          project: targetProject.name || '',
+          storage: 'project',
+          message: `Inferred project "${targetProject.name}" from PR scope ${prScope} (ADO repository ID match).`,
+        },
+      };
+    }
+    if (lenientMatches.length > 1) {
+      const names = lenientMatches.map(p => p.name).filter(Boolean);
+      return {
+        project: null,
+        resolution: {
+          reason: 'ambiguous',
+          scope: prScope,
+          project: 'central',
+          storage: 'central',
+          matches: names,
+          message: `PR scope ${prScope} matches multiple configured projects (${names.join(', ')}); linked in central PR tracking. Select a project to attach it.`,
+        },
+      };
+    }
+  }
+
   if (matches.length > 1) {
     const names = matches.map(p => p.name).filter(Boolean);
     return {
@@ -2287,6 +2319,54 @@ For all state files, look under \`${MINIONS_DIR}\`.${indexSection}`;
   return result;
 }
 
+// ── Compact state refresh for resumed CC sessions (W-mpeap2ug0016e69c) ──
+// Injected every turn on resume so new projects, MCPs, and agent changes
+// are visible without opening a new session. Smaller than the full preamble
+// (skips API/CLI indexes) and uses a shorter cache TTL.
+
+let _refreshCache = null;
+let _refreshCacheTs = 0;
+const REFRESH_TTL = 10000; // 10s — short TTL so state propagates quickly on resume
+
+function _resetRefreshCache() {
+  _refreshCache = null;
+  _refreshCacheTs = 0;
+}
+
+function buildCCStateRefresh() {
+  const now = Date.now();
+  if (_refreshCache && now - _refreshCacheTs < REFRESH_TTL) return _refreshCache;
+
+  const ts = new Date().toISOString().slice(0, 16);
+  const agents = getAgents().map(a => `- ${a.name}: ${a.status}`).join('\n');
+  const projects = PROJECTS.map(p => `- ${p.name} (${p.repo || p.localPath})`).join('\n');
+
+  // MCP servers — just names + source for orientation
+  let mcpLine = '(none discovered)';
+  try {
+    const mcps = getMcpServers();
+    if (mcps && mcps.length > 0) {
+      const maxShow = 15;
+      const shown = mcps.slice(0, maxShow).map(m => m.name).join(', ');
+      mcpLine = mcps.length > maxShow ? `${shown} …and ${mcps.length - maxShow} more` : shown;
+    }
+  } catch { /* optional */ }
+
+  const result = `### State Refresh (${ts})
+
+**Projects:** ${PROJECTS.length}
+${projects || '(none)'}
+
+**MCP Tools:** ${mcpLine}
+
+**Agents:**
+${agents || '(none)'}`;
+
+  _refreshCache = result;
+  _refreshCacheTs = now;
+  return result;
+}
+
 // The ===ACTIONS=== delimiter parser tiers (findCCActionsHeader,
 // findCCActionsPartialDelimiter, stripCCActionsForStream/Display) and the
 // _extractActionsJson Copilot fence-stripper were retired with the move to
@@ -2735,8 +2815,14 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   const resumeHasOutOfBandCarryover = !!sessionId && _transcriptHasCarryoverContext(transcript, { outOfBandOnly: true, currentMessage: message });
   const freshNeedsCarryover = _transcriptHasCarryoverContext(transcript, { currentMessage: message });
 
-  function buildPrompt({ includePreamble = true, includeCarryover = false, includeResumeGuard = false, outOfBandOnly = false } = {}) {
-    const parts = (!skipStatePreamble && includePreamble) ? [`## Current Minions State (${new Date().toISOString().slice(0, 16)})\n\n${buildCCStatePreamble()}`] : [];
+  function buildPrompt({ includePreamble = true, includeRefresh = false, includeCarryover = false, includeResumeGuard = false, outOfBandOnly = false } = {}) {
+    let preamblePart = null;
+    if (!skipStatePreamble && includePreamble) {
+      preamblePart = `## Current Minions State (${new Date().toISOString().slice(0, 16)})\n\n${buildCCStatePreamble()}`;
+    } else if (!skipStatePreamble && includeRefresh) {
+      preamblePart = buildCCStateRefresh();
+    }
+    const parts = preamblePart ? [preamblePart] : [];
     if (extraContext) parts.push(extraContext);
     if (includeResumeGuard) parts.push(CC_RESUME_BOOKKEEPING_GUARD);
     if (includeCarryover) {
@@ -2755,6 +2841,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   if (sessionId && maxTurns > 1) {
     const p1 = llm.callLLM(buildPrompt({
       includePreamble: false,
+      includeRefresh: true,
       includeResumeGuard: resumeNeedsBookkeepingGuard,
       includeCarryover: resumeNeedsCarryover || resumeHasOutOfBandCarryover,
       outOfBandOnly: !resumeNeedsCarryover,
@@ -2877,8 +2964,14 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
   const resumeHasOutOfBandCarryover = !!sessionId && _transcriptHasCarryoverContext(transcript, { outOfBandOnly: true, currentMessage: message });
   const freshNeedsCarryover = _transcriptHasCarryoverContext(transcript, { currentMessage: message });
 
-  function buildPrompt({ includePreamble = true, includeCarryover = false, includeResumeGuard = false, outOfBandOnly = false } = {}) {
-    const parts = (!skipStatePreamble && includePreamble) ? [`## Current Minions State (${new Date().toISOString().slice(0, 16)})\n\n${buildCCStatePreamble()}`] : [];
+  function buildPrompt({ includePreamble = true, includeRefresh = false, includeCarryover = false, includeResumeGuard = false, outOfBandOnly = false } = {}) {
+    let preamblePart = null;
+    if (!skipStatePreamble && includePreamble) {
+      preamblePart = `## Current Minions State (${new Date().toISOString().slice(0, 16)})\n\n${buildCCStatePreamble()}`;
+    } else if (!skipStatePreamble && includeRefresh) {
+      preamblePart = buildCCStateRefresh();
+    }
+    const parts = preamblePart ? [preamblePart] : [];
     if (extraContext) parts.push(extraContext);
     if (includeResumeGuard) parts.push(CC_RESUME_BOOKKEEPING_GUARD);
     if (includeCarryover) {
@@ -2896,6 +2989,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
   if (sessionId && maxTurns > 1) {
     const p1 = llm.callLLMStreaming(buildPrompt({
       includePreamble: false,
+      includeRefresh: true,
       includeResumeGuard: resumeNeedsBookkeepingGuard,
       includeCarryover: resumeNeedsCarryover || resumeHasOutOfBandCarryover,
       outOfBandOnly: !resumeNeedsCarryover,
@@ -4245,6 +4339,22 @@ const server = http.createServer(async (req, res) => {
         if (!Array.isArray(body.depends_on)) return jsonReply(res, 400, { error: 'depends_on must be an array of strings' });
         if (!body.depends_on.every(s => typeof s === 'string')) return jsonReply(res, 400, { error: 'depends_on entries must be strings' });
       }
+      // Validate agent/agents against config.agents (W-mpeanskq001311cf)
+      const knownAgents = CONFIG.agents && typeof CONFIG.agents === 'object' ? Object.keys(CONFIG.agents) : [];
+      if (knownAgents.length > 0) {
+        const allowTemp = !!CONFIG.engine?.allowTempAgents;
+        const isValidAgent = (name) => knownAgents.includes(name) || (allowTemp && /^temp-/.test(name));
+        if (body.agent && typeof body.agent === 'string' && body.agent.trim()) {
+          if (!isValidAgent(body.agent.trim())) {
+            return jsonReply(res, 400, { error: `Unknown agent "${body.agent}". Valid agents: ${knownAgents.join(', ')}`, validAgents: knownAgents });
+          }
+        }
+        const agentsArr = Array.isArray(body.agents) ? body.agents.filter(Boolean) : [];
+        const invalidAgents = agentsArr.filter(a => typeof a === 'string' && !isValidAgent(a.trim()));
+        if (invalidAgents.length > 0) {
+          return jsonReply(res, 400, { error: `Unknown agent(s) in agents array: ${invalidAgents.join(', ')}. Valid agents: ${knownAgents.join(', ')}`, validAgents: knownAgents });
+        }
+      }
       // Worktree-requiring types must own a project so the engine's spawnAgent
       // can resolve a per-project rootDir. With no project (and no single
       // auto-target via defaultWhenSingle), spawn falls back to MINIONS_DIR's
@@ -6784,20 +6894,64 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     let _ccStreamEnded = false;
     let _ccHeartbeatTimer = null;
     let _ccLastHeartbeatAt = Date.now();
+    // W-mpdavudb000v8446 — SSE delivery telemetry. Previously writeCcEvent
+    // swallowed all write failures (res.destroyed / res.write returning false
+    // for backpressure / sync throw), and the [cc-timing] log only proved
+    // onChunk/onDone fired — NOT that bytes left the kernel. When chunks=2
+    // outcome=done but the user sees thinking dots forever, the gap was here.
+    // Now writeCcEvent inspects res state and logs a structured [cc-sse-fail]
+    // line whenever it cannot actually deliver a chunk/done frame to the wire.
     const writeCcEvent = (payload) => {
-      try {
-        const wire = 'data: ' + JSON.stringify(payload) + '\n\n';
-        res.write(wire);
-        if (payload && payload.type === 'chunk') {
-          _ccTelemetry.chunks++;
-          _ccTelemetry.bytes += Buffer.byteLength(String(payload.text || ''), 'utf8');
-        } else if (payload && payload.type === 'tool') {
-          _ccTelemetry.tools++;
-        }
-        return true;
-      } catch {
+      const type = payload && payload.type;
+      const isUserFacing = type === 'chunk' || type === 'done' || type === 'tool' || type === 'tool-update' || type === 'error';
+      const _logFail = (reason, extra) => {
+        if (!isUserFacing) return;
+        try {
+          const meta = {
+            tab: tabId || _ccTelemetry.tabId || 'unknown',
+            type,
+            reason,
+            destroyed: !!res.destroyed,
+            writableEnded: !!res.writableEnded,
+            writableFinished: !!res.writableFinished,
+            streamEnded: _ccStreamEnded,
+            ...(extra || {}),
+          };
+          shared.log('warn', `[cc-sse-fail] ${JSON.stringify(meta)}`);
+        } catch { /* telemetry is best-effort */ }
+      };
+      if (res.destroyed || res.writableEnded) {
+        _logFail(res.destroyed ? 'res-destroyed' : 'res-writable-ended');
+        return false;
+      }
+      let wire;
+      try { wire = 'data: ' + JSON.stringify(payload) + '\n\n'; }
+      catch (err) {
+        _logFail('json-serialize-failed', { error: String((err && err.message) || err).slice(0, 200) });
         return false;
       }
+      let writeOk;
+      try { writeOk = res.write(wire); }
+      catch (err) {
+        _logFail('res-write-threw', { error: String((err && err.message) || err).slice(0, 200), bytes: wire.length });
+        return false;
+      }
+      if (writeOk === false) {
+        // Backpressure — Node's writable buffer is over its highWaterMark.
+        // The write IS still queued, so don't treat this as a failure, but
+        // surface it so a slow consumer is visible in telemetry. Most CC
+        // chunks are small enough that we never hit this in practice.
+        try {
+          shared.log('warn', `[cc-sse-backpressure] tab=${tabId || _ccTelemetry.tabId || 'unknown'} type=${type} bytes=${wire.length}`);
+        } catch { /* telemetry is best-effort */ }
+      }
+      if (payload && payload.type === 'chunk') {
+        _ccTelemetry.chunks++;
+        _ccTelemetry.bytes += Buffer.byteLength(String(payload.text || ''), 'utf8');
+      } else if (payload && payload.type === 'tool') {
+        _ccTelemetry.tools++;
+      }
+      return true;
     };
     const stopCcHeartbeat = () => {
       if (_ccHeartbeatTimer) {
@@ -6970,7 +7124,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const resumeNeedsCarryover = wasResume && _ccRuntimeNeedsResumeCarryover(currentRuntime);
         const resumeNeedsBookkeepingGuard = wasResume && _ccRuntimeNeedsResumeBookkeepingGuard(currentRuntime);
         const resumeHasOutOfBandCarryover = wasResume && _transcriptHasCarryoverContext(body.transcript, { outOfBandOnly: true, currentMessage: body.message });
-        const preamble = wasResume ? '' : buildCCStatePreamble();
+        const preamble = wasResume ? buildCCStateRefresh() : buildCCStatePreamble();
         const includeFullCarryover = sessionReset || resumeNeedsCarryover;
         const resumeGuard = resumeNeedsBookkeepingGuard ? CC_RESUME_BOOKKEEPING_GUARD : '';
         const carryover = (includeFullCarryover || resumeHasOutOfBandCarryover)
@@ -9138,6 +9292,8 @@ module.exports = {
   _resolveScheduleProjectValue: resolveScheduleProjectValue,
   _collectArchivedWorkItems: collectArchivedWorkItems,
   buildCCStatePreamble,
+  buildCCStateRefresh,
+  _resetRefreshCache,
   _routesAsMeta,
   _server: server,
   _buildTranscriptCarryover,

package/docs/completion-reports.md

@@ -68,7 +68,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `summary` | string | Short prose describing what changed and how it was validated. Truncated to 500 chars in dashboard surfaces (`engine/queries.js`). Do not summarize validation as "tests passed" — name the commands that ran. |
 | `verdict` | string \| null | Required for review tasks: `approved` or `changes-requested`. `null` for non-review tasks. Aliases: `approve`, `request_changes`, `changes_requested`. |
 | `pr` | string | PR URL, `PR-<number>`, or `N/A`. The engine uses this to attach the PR to the work item; missing-PR detection treats anything other than a recognizable URL/PR id as missing unless `noop: true` is set. |
-| `failure_class` | string | One of the `failure_class` enum values below, or `N/A`. Drives retry policy in `engine/dispatch.js` and recovery routing in `engine/recovery.js`. |
+| `failure_class` | string | One of the `failure_class` enum values below, or `N/A`. Drives retry policy in `engine/dispatch.js`. |
 | `retryable` | boolean | `true` if the engine should auto-retry the dispatch on failure. Overrides the default per-class retry policy when present. |
 | `needs_rerun` | boolean | `true` if the same work needs to be re-dispatched (vs. retried). Used by build-fix and review-fix loops. |
 | `artifacts` | array | Durable artifacts the agent created or updated; surfaces in the dashboard work-item detail modal. See [Artifacts](#artifacts). |
@@ -235,6 +235,5 @@ If the JSON report exists and is well-formed, the engine ignores the fenced bloc
 - `engine/shared.js` — `FAILURE_CLASS`, `COMPLETION_FIELDS`, `dispatchCompletionReportPath()`
 - `engine/lifecycle.js` — `parseCompletionReportFile()`, `parseCompletionNoop()`, `enforcePrAttachmentContract()`
 - `engine/dispatch.js` — `isRetryableFailureReason()`, `writeFailedAgentReport()`
-- `engine/recovery.js` — per-`failure_class` recovery recipes
 - `docs/rfc-completion-json.md` — original RFC describing the protocol's design
 - `playbooks/shared-rules.md` — the per-task "Completion Reports" instruction every playbook inherits

package/docs/deprecated.json

@@ -1,18 +1,4 @@
 [
-  {
-    "id": "managed-spawn-env-allowlist",
-    "removedAt": "2026-05-18",
-    "reason": "ENGINE_DEFAULTS.managedSpawn.envKeyAllowlist + envKeyAllowlistPrefixes removed; replaced by envKeyDenyPatterns + envKeyDenyOverrides. The allowlist shape required an engine PR for every new framework/project env prefix (W-mpbpa09c000rd513 tried per-project allowlist extension; user steered away — 'make sure that we are not hardcoding any env variables or being so rigid about it'). The denylist shape matches the actual credential-leakage threat model and lets plain project vars like CONSTELLATION_SERVER, DATABASE_URL, REDIS_HOST work with zero engine config while still blocking credential-shaped keys (AWS_*, *_TOKEN, *_SECRET, etc.). Per-project tightening is supported via project.managedSpawnExtraDenyPatterns (additive only, no per-project override list).",
-    "removedLocations": [
-      "engine/shared.js ENGINE_DEFAULTS.managedSpawn.envKeyAllowlist (15 keys)",
-      "engine/shared.js ENGINE_DEFAULTS.managedSpawn.envKeyAllowlistPrefixes (8 prefixes)",
-      "engine/managed-spawn.js _envKeyAllowed (rewritten to deny+override+shape model)",
-      "engine/managed-spawn.js buildManagedSpawnHint (env-key guidance rewritten)",
-      "PR #2624 (closed, superseded — added per-project allowlist union; replaced here by per-project deny tightening)",
-      "test/unit/managed-spawn-validator.test.js 4e/4f/11a (rewritten for denylist semantics)"
-    ],
-    "notes": "Already removed in this PR; entry exists to track the breaking shape change in the deprecation log. Delete entry after 3 days per /cleanup-deprecated."
-  },
   {
     "id": "config-poll-key-migration",
     "location": "engine/queries.js:123-162",
@@ -23,35 +9,20 @@
   },
   {
     "id": "legacy-done-aliases",
-    "location": "engine/cleanup.js:799-894",
+    "location": "engine/cleanup.js:970-972",
     "constants": ["LEGACY_DONE_ALIASES", "LEGACY_NEEDS_REVIEW_STATUS"],
     "reason": "Read-side tolerance: cleanup sweep auto-migrates four obsolete work-item / PRD status strings ('in-pr', 'implemented', 'complete', 'needs-human-review') to the canonical 'done' / 'failed' values. The aliases are no longer written anywhere in the engine; the constants exist only to repair stale on-disk values from old engine versions.",
     "targetRemovalDate": null,
-    "notes": "Keep indefinitely until telemetry / a sweep log shows zero migrations performed for 30 consecutive days across all known projects (work-items.json + prd/*.json). At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js (definitions at :799-800; usage at :803-815 for work items and :880-887 for PRD missing_features) can be deleted. Total cost on disk today: 4 strings."
+    "notes": "Keep indefinitely until telemetry / a sweep log shows zero migrations performed for 30 consecutive days across all known projects (work-items.json + prd/*.json). At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js (definitions at :970-972; usage at :973-1000 for work items and :1051-1057 for PRD missing_features) can be deleted. Total cost on disk today: 4 strings."
   },
   {
-    "id": "native-teams-integration",
-    "removedAt": "2026-05-14",
-    "reason": "Native Microsoft Teams Bot Framework integration removed end-to-end. The Teams MCP server (teams-* tools, configured in the CC client outside this repo) supersedes the in-repo Bot Framework path. Removal closes the dual-implementation gap and drops the botbuilder dependency.",
-    "removedLocations": [
-      "engine/teams.js",
-      "engine/teams-cards.js",
-      "engine/teams-state.json (runtime state)",
-      "engine/teams-inbox.json (runtime state, generated by the deleted /api/bot handler)",
-      "dashboard.js: POST /api/bot route + handleTeamsBot, TEAMS_INBOX_PATH constant, CC mirror hooks (teamsPostCCResponse), plan-approval/rejection Teams notifications, settings GET/POST teams block",
-      "dashboard/js/settings.js: Teams Integration settings UI + teamsPayload submit",
-      "engine/lifecycle.js: teamsNotifyCompletion, teamsNotifyPlanEvent (verify-created + plan-completed), teamsNotifyPrEvent (post-merge)",
-      "engine/github.js + engine/ado.js: teamsNotifyPrEvent on pr-approved and build-failed",
-      "engine/preflight.js: Teams integration doctor check",
-      "engine/cli.js: teamsInboxTimer + clearInterval on shutdown",
-      "engine/shared.js: ENGINE_DEFAULTS.teams block",
-      "package.json: botbuilder dependency (4.23.3)",
-      "docs/teams-setup.md, docs/teams-production.md",
-      "test/unit/auto-recovery.test.js: ~58 Teams test cases",
-      "test/unit/preflight-behavioral.test.js: 4 doctor Teams checks + teams field in the docs-link coverage scenario",
-      "README.md / CLAUDE.md / docs/README.md / TODO.md / docs/rfc-completion-json.md: prose references"
-    ],
-    "notes": "The Teams MCP (teams-* tools) lives outside this repo in the CC client config and is NOT affected. If Teams-style notifications are needed again, route them through the MCP layer or an external webhook watch action — do not re-introduce the Bot Framework SDK in-process."
+    "id": "completion-fallback-parsers",
+    "description": "parseStructuredCompletion and parseCompletionFieldSummary in engine/lifecycle.js",
+    "file": "engine/lifecycle.js",
+    "lines": "2747, 2848",
+    "telemetryGate": "_engine.completionFallbacks must read 0 across sweep window",
+    "enforcingTest": "test/unit/completion-fallback-telemetry.test.js:217-234",
+    "notes": "Do NOT set removedAt until telemetry confirms zero usage"
   }
 ]
 

package/docs/rfc-completion-json.md

@@ -184,7 +184,7 @@ The agent must not write the file in pieces. Empty, truncated, or malformed JSON
 | Value | When | Engine action |
 |-------|------|---------------|
 | `done` | Work complete; PR pushed (if applicable) | Mark WI `done`, sync PRD |
-| `partial` | Some progress; agent ran out of turns or hit a known stop point | Auto-retry per `RECOVERY_RECIPES` (`engine/recovery.js`) |
+| `partial` | Some progress; agent ran out of turns or hit a known stop point | Auto-retry per runtime/agent retryability |
 | `failed` | Hard failure; no recovery attempted by agent | Use `failure.class` to pick recipe |
 | `noop` | Idempotent bail (review already posted, plan already shipped, etc.) | Mark WI `done` without retry, no failure metric |
 | `needs-review` | Agent could not classify; flag for human | Set WI `failed` with an explicit `failReason` |
@@ -257,7 +257,7 @@ When `completion.json` is absent or invalid: full fallback to stdout regex on ev
 |-------|--------|----------|----------------|
 | **0. Preparation** (no flag) | Day 0 | Engine writes `MINIONS_COMPLETION_PATH` env var. Engine reads completion.json *opportunistically* (uses it when present, falls back to regex when absent). Playbooks updated to write the file. `parseStructuredCompletion`'s ` ```completion ` block continues to be parsed and merged with `completion.json` during this phase only — agents who upgrade slowly still work. | — |
 | **1. Dual-mode** | Day 0 → Day 7 | Same as Phase 0, plus new metric `_engine.completionFile.{parsed,fallback,invalid}` per agent in `metrics.json`. Daily KB sweep posts a digest of fallback rates. | ≥95% of dispatches in the last 24h produce a parseable completion.json |
-| **2. Strict** (gated by `engine.requireCompletionFile = false` → `true`) | Day 7 → Day 10 | When the flag is `true`, missing/invalid completion.json marks the dispatch `failed` with `failure.class = 'config-error'` (no retry, see `RECOVERY_RECIPES`). Default still `false`. | All permanent agents observed clean for 3 consecutive days |
+| **2. Strict** (gated by `engine.requireCompletionFile = false` → `true`) | Day 7 → Day 10 | When the flag is `true`, missing/invalid completion.json marks the dispatch `failed` with `failure.class = 'config-error'` (no retry). Default still `false`. | All permanent agents observed clean for 3 consecutive days |
 | **3. Default flip** | Day 10 | `engine.requireCompletionFile` default becomes `true`. Stdout regex parsers (`syncPrsFromOutput`, `parseReviewVerdict`, etc.) become deprecated shims, registered in `docs/deprecated.json` with a `cleanup` date 3 days out (per the existing `/cleanup-deprecated` skill convention). | — |
 | **4. Removal** | Day 13 | Stdout regex parsers deleted; ` ```completion ` block support removed. Only `completion.json` is read. | — |
 

package/engine/cc-worker-pool.js

@@ -96,6 +96,19 @@ const _internals = {
 const _tabs = new Map();
 let _reaperTimer = null;
 
+// CC_POOL_TRACE-gated structured trace logger. Off by default; enable via
+// `CC_POOL_TRACE=1 minions restart` to dump every getSession lifecycle
+// transition, stream sessionId capture, and session/update notification
+// match/mismatch to stderr. Added for W-mpdavudb000v8446 follow-up so the
+// next investigation cycle can correlate engine state with the user-perceived
+// first-message hang. NO PII — only tabId (caller-supplied), sessionIds
+// (opaque ACP ids), and protocol flags. Safe to leave on in dev/staging.
+function _trace(...parts) {
+  if (!process.env.CC_POOL_TRACE) return;
+  try { process.stderr.write('[cc-pool] ' + parts.join(' ') + '\n'); }
+  catch { /* swallow telemetry errors */ }
+}
+
 function _hashMcpServers(mcpServers) {
   // Stable hash via JSON.stringify; mcpServers is an array of plain objects
   // in practice (name/command/env) so the natural key order is fine.
@@ -141,6 +154,19 @@ class Worker {
     // settles. Racing getSession() callers await this to avoid the
     // "warm-reuse path returns sessionId=null while init is still pending"
     // hang on first message of a freshly-warmed tab (W-mpd45blx00072f04).
+    //
+    // Follow-up investigation (W-mpdavudb000v8446) verified the post-ab141995
+    // engine path holds the necessary invariants (see
+    // test/unit/cc-worker-pool-fresh-tab-race.test.js):
+    //   * after `await worker.initPromise`, worker.sessionId is the real id
+    //   * Worker.stream sets inflight.sessionId to that same real id
+    //   * session/prompt is written with sessionId === inflight.sessionId
+    // When the symptom recurs (intermittent first-message hang despite the
+    // fix), it's almost certainly downstream of the pool — SSE delivery,
+    // browser-side render, or telemetry overstating delivery. Set
+    // `CC_POOL_TRACE=1` to dump every state transition + sessionId snapshot
+    // through the pool to stderr so the next investigation can correlate
+    // engine state with the user-perceived hang.
     this.initPromise = null;
   }
 
@@ -253,8 +279,24 @@ class Worker {
       return;
     }
     // Notification (no id) — only `session/update` matters for streaming.
-    if (obj.method === 'session/update' && obj.params && this.inflight) {
-      if (obj.params.sessionId !== this.inflight.sessionId) return;
+    if (obj.method === 'session/update' && obj.params) {
+      // Trace EVERY session/update notification, including drops — this is
+      // exactly where the W-mpd45blx00072f04 hang manifested (chunks dropped
+      // because inflight.sessionId was null). Logging both the notification
+      // sid and the inflight sid lets the next investigation cycle prove
+      // whether the engine still drops chunks. (W-mpdavudb000v8446)
+      const notifSid = obj.params.sessionId;
+      const inflightSid = this.inflight ? this.inflight.sessionId : null;
+      const updKind = obj.params.update && obj.params.update.sessionUpdate;
+      if (!this.inflight) {
+        _trace(`tab=${this.tabId} session/update dropped: no inflight (notifSid=${notifSid} kind=${updKind})`);
+        return;
+      }
+      if (notifSid !== inflightSid) {
+        _trace(`tab=${this.tabId} session/update dropped: sid mismatch (notifSid=${notifSid} inflightSid=${inflightSid} kind=${updKind})`);
+        return;
+      }
+      _trace(`tab=${this.tabId} session/update delivered: sid=${notifSid} kind=${updKind}`);
       const update = obj.params.update;
       if (!update) return;
       if (update.sessionUpdate === 'agent_message_chunk') {
@@ -338,6 +380,14 @@ class Worker {
       settled: false,
     };
     this.inflight = inflight;
+    // W-mpdavudb000v8446 — trace the sessionId captured by inflight at the
+    // exact moment Worker.stream commits to a write. inflight.sessionId is
+    // the value session/update notifications must match against in
+    // _handleMessage; if it's ever null, every chunk for this turn is silently
+    // dropped (the ab141995 hang signature). Pair with the [cc-pool] dispatch
+    // log on the dashboard side to correlate engine state with user-perceived
+    // delivery.
+    _trace(`tab=${this.tabId} stream begin: worker.sessionId=${this.sessionId} inflight.sessionId=${inflight.sessionId} reqId=${id}`);
 
     if (signal && typeof signal.addEventListener === 'function') {
       inflight.signalHandler = () => this.cancel();
@@ -504,6 +554,7 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
   //   'new-session' — proc reused, fresh session/new (sysprompt hash changed)
   //   'cold-spawn'  — fresh proc + initialize + session/new
   let lifecycle = 'warm-reuse';
+  _trace(`tab=${tabId} getSession entry: worker.exists=${!!worker} worker.sessionId=${worker?.sessionId ?? 'null'} worker.initPromise=${worker?.initPromise ? 'pending' : 'null'}`);
 
   if (worker) {
     // W-mpd45blx00072f04: if the existing worker is still mid-init (warm
@@ -516,6 +567,7 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
     // freshly-warmed CC tab hangs (no chunks streamed, eventual onDone
     // with empty text).
     if (worker.initPromise) {
+      _trace(`tab=${tabId} getSession await-init: joining in-flight initPromise`);
       try {
         await worker.initPromise;
       } catch (err) {
@@ -523,10 +575,12 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
         // (or is about to) delete _tabs[tabId] and close the worker in its
         // own catch handler. Surface the same error to this caller so the
         // dashboard's spawn-failed path runs instead of hanging.
+        _trace(`tab=${tabId} getSession await-init failed: ${err.message}`);
         throw err;
       }
       // Re-read in case the failing initPromise's cleanup already ran.
       worker = _tabs.get(tabId) || null;
+      _trace(`tab=${tabId} getSession await-init done: worker.exists=${!!worker} worker.sessionId=${worker?.sessionId ?? 'null'}`);
     }
   }
 
@@ -592,6 +646,22 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
 
   _ensureReaper();
 
+  // W-mpdavudb000v8446 — trace the handle being returned. If lifecycle is
+  // 'warm-reuse' but sessionId is null/empty, the engine has hit a state the
+  // ab141995 fix was supposed to prevent — surface it loudly. The empty-id
+  // case is also caught defensively below so callers can react instead of
+  // wedging on a null-sid session/prompt frame.
+  _trace(`tab=${tabId} getSession return: lifecycle=${lifecycle} sessionId=${worker.sessionId ?? 'null'}`);
+  if (!worker.sessionId) {
+    // This is the bug class the ab141995 fix closed; if it ever recurs the
+    // engine should fail loudly rather than hand back a half-initialized
+    // handle. Throwing here lets the dashboard surface spawn-failed instead
+    // of the silent thinking-dots-forever symptom.
+    throw new Error(
+      `cc-worker-pool: getSession returning handle with null sessionId (tab=${tabId} lifecycle=${lifecycle}) — engine race regression, see W-mpd45blx00072f04 / W-mpdavudb000v8446`
+    );
+  }
+
   return {
     sessionId: worker.sessionId,
     lifecycle,

package/engine/lifecycle.js

@@ -1684,7 +1684,8 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
   const prevReviewStatus = reviewPr?.reviewStatus || '';
   const wasNegative = prevReviewStatus === 'changes-requested' || prevReviewStatus === 'waiting'
     || liveStatus === 'changes-requested' || liveStatus === 'waiting';
-  if (verdictRaw === 'approved' && !isSelfReview && wasNegative && projectObjForChecks) {
+  const autoApplyVote = config?.engine?.autoApplyReviewVote ?? ENGINE_DEFAULTS.autoApplyReviewVote;
+  if (autoApplyVote && verdictRaw === 'approved' && !isSelfReview && wasNegative && projectObjForChecks) {
     try {
       const reconcileFn = hostForChecks === 'github'
         ? require('./github').dismissPriorViewerChangesRequestedReviews
@@ -1707,7 +1708,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
     }
   }
 
-  if (liveStatus && liveStatus !== 'pending') postReviewStatus = liveStatus;
+  if (autoApplyVote && liveStatus && liveStatus !== 'pending') postReviewStatus = liveStatus;
 
   // Fallback: if live check returned pending (e.g., GitHub self-approval blocked), use the agent's completion report.
   if (!postReviewStatus) {

package/engine/shared.js

@@ -1676,6 +1676,7 @@ const ENGINE_DEFAULTS = {
   autoReviewPrs: true, // auto-dispatch review agents for newly opened agent PRs
   autoReReviewPrs: true, // auto-dispatch review agents after a PR fix is pushed
   autoFixReviewFeedback: true, // auto-dispatch fix agents for minions review changes-requested verdicts
+  autoApplyReviewVote: false, // when true, review verdicts (APPROVE / REQUEST_CHANGES) automatically flip the platform vote; when false (default), verdicts are informational only
   autoFixHumanComments: true, // auto-dispatch fix agents for actionable human PR comments
   prNoOpFixPauseAttempts: 2, // pause one PR automation cause after repeated no-op fixes for unchanged evidence
   completionReportRetentionDays: 90, // retain completion report sidecars beyond capped dispatch history
@@ -1735,6 +1736,7 @@ const ENGINE_DEFAULTS = {
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
   enablePreDispatchEval: true, // P-d2a9f6e5: cheap LLM gate before queueing — on by default. See engine/pre-dispatch-eval.js (Ripley §3 recommendation, 2026-05-11 architecture review). Validates from acceptance_criteria when present, falls back to description when criteria are absent but description is rich (≥80 chars). Fail-open on any validator error.
   completionNonceRequired: false, // P-d2a8f6c1 (agent trust boundary F8): when true, a missing `nonce` field in the completion JSON hard-fails the dispatch with failure_class:'completion-nonce-mismatch'. Default false for one release so older agents/runtime caches that haven't picked up the prompt change degrade with a warning instead of breaking. Mismatched nonces hard-fail regardless of this flag. See docs/completion-reports.md → "Trust boundary".
+  autoApplyReviewVote: false, // W-mpea9fyb0010febf: when true, review verdict flips the platform vote (ADO resetReviewerNegativeVote / GitHub dismissPriorViewerChangesRequestedReviews). When false (default), the verdict is recorded in pull-requests.json reviewStatus only — informational, no platform side-effect.
 
   // ── Runtime fleet (P-3b8e5f1d) ──────────────────────────────────────────────
   // Single source of truth for which CLI runtime + model every spawn uses.
@@ -3213,7 +3215,15 @@ function buildWorktreeDirName({
   const suffix = _worktreeNameSuffix(dispatchId, projectName, branchName);
   if (platform === 'win32') return `W-${suffix}`;
   const projectSlug = String(projectName || 'default').replace(/[^a-zA-Z0-9_-]/g, '-');
-  return `${projectSlug}-${sanitizeBranch(branchName || 'worktree')}-${suffix}`;
+  // `sanitizeBranch` preserves `/` (legit in git ref names) but on POSIX that
+  // turns the FS dir name into a nested path. Flatten by replacing `/` → `-`
+  // so the dir name is a single basename. Without this, `path.join(parent,
+  // dirName)` creates `parent/work/W-…/` on Linux for a `work/W-…` branch,
+  // and `readdirSync(parent)` returns `work` (not the full name) — breaking
+  // engine/worktree-gc.js's globalLiveDirNames lookup and evicting live
+  // worktrees on boot.
+  const branchSlug = sanitizeBranch(branchName || 'worktree').replace(/\//g, '-');
+  return `${projectSlug}-${branchSlug}-${suffix}`;
 }
 
 /**
@@ -3677,6 +3687,31 @@ function isPrCompatibleWithProject(project, prRef, url = '') {
   return !getPrProjectScopeMismatch(project, prRef, url);
 }
 
+/**
+ * Check if a parsed ADO PR scope is compatible with a project config,
+ * considering that the repo segment in the URL might be either the friendly
+ * repoName or the repositoryId (GUID). Case-insensitive comparison.
+ */
+function isAdoPrScopeCompatible(parsedScope, project) {
+  if (!parsedScope || !project) return false;
+  const colonIdx = String(parsedScope).indexOf(':');
+  if (colonIdx < 0) return false;
+  const host = String(parsedScope).slice(0, colonIdx);
+  if (host !== 'ado') return false;
+  const rest = String(parsedScope).slice(colonIdx + 1);
+  const parts = rest.split('/');
+  if (parts.length !== 3) return false;
+  const [scopeOrg, scopeProject, scopeRepo] = parts;
+  const projOrg = normalizePrScopeSegment(project.adoOrg);
+  const projAdoProject = normalizePrScopeSegment(project.adoProject);
+  if (!projOrg || !projAdoProject) return false;
+  if (scopeOrg !== projOrg || scopeProject !== projAdoProject) return false;
+  const projRepoName = normalizePrScopeSegment(project.repoName);
+  const projRepositoryId = normalizePrScopeSegment(project.repositoryId);
+  if (!projRepoName && !projRepositoryId) return false;
+  return scopeRepo === projRepoName || scopeRepo === projRepositoryId;
+}
+
 /**
  * Build a canonical, repository-scoped PR identifier.
  *
@@ -4752,6 +4787,7 @@ module.exports = {
   getPrScopeInfo,
   getPrProjectScopeMismatch,
   isPrCompatibleWithProject,
+  isAdoPrScopeCompatible,
   getCanonicalPrId,
   findPrRecord,
   snapshotPrRecord,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1988",
+  "version": "0.1.1989",
   "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"

package/engine/recovery.js

@@ -1,130 +0,0 @@
-/**
- * engine/recovery.js — Recovery recipes for classified agent failures.
- * Maps FAILURE_CLASS values to per-class retry limits and escalation policies.
- * Zero external dependencies — uses only Node.js built-ins and imports from shared.js.
- */
-
-const { FAILURE_CLASS, ESCALATION_POLICY, ENGINE_DEFAULTS } = require('./shared');
-
-// ─── Recovery Recipes ───────────────────────────────────────────────────────
-
-/**
- * Each recipe defines:
- *   maxAttempts  — max retries for this failure class (0 = never retry)
- *   escalation   — ESCALATION_POLICY value
- *   freshSession — whether to clear session.json before retry
- *   description  — human-readable explanation for logs/dashboard
- */
-const RECOVERY_RECIPES = new Map([
-  [FAILURE_CLASS.CONFIG_ERROR, {
-    maxAttempts: 0,
-    escalation: ESCALATION_POLICY.NO_RETRY,
-    freshSession: false,
-    description: 'Configuration error — fix config before retrying',
-  }],
-  [FAILURE_CLASS.PERMISSION_BLOCKED, {
-    maxAttempts: 0,
-    escalation: ESCALATION_POLICY.NO_RETRY,
-    freshSession: false,
-    description: 'Permission/trust gate blocked — requires human intervention',
-  }],
-  [FAILURE_CLASS.AUTH, {
-    maxAttempts: 0,
-    escalation: ESCALATION_POLICY.NO_RETRY,
-    freshSession: false,
-    description: 'Git/network authentication failed (missing az login, expired token, GCM prompt) — requires human credential fix before retry',
-  }],
-  [FAILURE_CLASS.MERGE_CONFLICT, {
-    maxAttempts: 2,
-    escalation: ESCALATION_POLICY.RETRY_SAME,
-    freshSession: false,
-    description: 'Merge conflict — retry may succeed after dependency updates',
-  }],
-  [FAILURE_CLASS.BUILD_FAILURE, {
-    maxAttempts: 2,
-    escalation: ESCALATION_POLICY.RETRY_SAME,
-    freshSession: false,
-    description: 'Build/test failure — retry with same context for iterative fix',
-  }],
-  [FAILURE_CLASS.TIMEOUT, {
-    maxAttempts: 1,
-    escalation: ESCALATION_POLICY.RETRY_FRESH,
-    freshSession: true,
-    description: 'Timeout — retry with fresh session to avoid stuck state',
-  }],
-  [FAILURE_CLASS.EMPTY_OUTPUT, {
-    maxAttempts: 1,
-    escalation: ESCALATION_POLICY.HUMAN_REVIEW,
-    freshSession: true,
-    description: 'Empty output — agent produced nothing useful, flag for review',
-  }],
-  [FAILURE_CLASS.SPAWN_ERROR, {
-    maxAttempts: 2,
-    escalation: ESCALATION_POLICY.RETRY_FRESH,
-    freshSession: true,
-    description: 'Spawn error — retry with fresh session after transient failure',
-  }],
-  [FAILURE_CLASS.NETWORK_ERROR, {
-    maxAttempts: 3,
-    escalation: ESCALATION_POLICY.AUTO,
-    freshSession: false,
-    description: 'Network/API error — retry with exponential backoff',
-  }],
-  [FAILURE_CLASS.MAX_TURNS, {
-    maxAttempts: 3,
-    escalation: ESCALATION_POLICY.RETRY_SAME,
-    freshSession: false,
-    description: 'Max turns reached — work in progress, retry same agent to continue',
-  }],
-  [FAILURE_CLASS.OUT_OF_CONTEXT, {
-    maxAttempts: 1,
-    escalation: ESCALATION_POLICY.HUMAN_REVIEW,
-    freshSession: true,
-    description: 'Context exhausted — retry with fresh session, flag if repeated',
-  }],
-  [FAILURE_CLASS.WORKTREE_PREFLIGHT, {
-    maxAttempts: 0,
-    escalation: ESCALATION_POLICY.NO_RETRY,
-    freshSession: false,
-    description: 'Worktree preflight rejected — same inputs will recompute to the same rejection (drive-root rootDir, nested-in-project worktree). Fix the dispatch (attach a project, move MINIONS_DIR, or override engine.worktreeRoot) before retrying.',
-  }],
-  [FAILURE_CLASS.UNKNOWN, {
-    maxAttempts: null, // null = fall back to ENGINE_DEFAULTS.maxRetries
-    escalation: ESCALATION_POLICY.AUTO,
-    freshSession: false,
-    description: 'Unclassified failure — use default retry behavior',
-  }],
-]);
-
-// ─── Public API ─────────────────────────────────────────────────────────────
-
-/**
- * Get the recovery recipe for a failure class.
- * @param {string} failureClass — one of FAILURE_CLASS values
- * @returns {object} recipe with maxAttempts, escalation, freshSession, description
- */
-function getRecoveryRecipe(failureClass) {
-  return RECOVERY_RECIPES.get(failureClass) || RECOVERY_RECIPES.get(FAILURE_CLASS.UNKNOWN);
-}
-
-/**
- * Determine whether a failed dispatch should be retried based on its failure class
- * and current attempt count.
- * @param {string} failureClass — one of FAILURE_CLASS values (or empty for unclassified)
- * @param {number} attemptCount — how many times this item has already been retried
- * @returns {boolean} true if another retry is allowed
- */
-function shouldRetry(failureClass, attemptCount = 0) {
-  const recipe = getRecoveryRecipe(failureClass || FAILURE_CLASS.UNKNOWN);
-  // null maxAttempts = fall back to global ENGINE_DEFAULTS.maxRetries
-  const limit = recipe.maxAttempts !== null ? recipe.maxAttempts : ENGINE_DEFAULTS.maxRetries;
-  return attemptCount < limit;
-}
-
-// ─── Exports ────────────────────────────────────────────────────────────────
-
-module.exports = {
-  RECOVERY_RECIPES,
-  getRecoveryRecipe,
-  shouldRetry,
-};