@yemi33/minions 0.1.555 → 0.1.557

package/CHANGELOG.md

@@ -1,11 +1,13 @@
 # Changelog
 
-## 0.1.555 (2026-04-07)
+## 0.1.557 (2026-04-08)
 
 ### Features
 -  add pin/unpin button to inbox and KB document modals
 
 ### Fixes
+- add max retry cap and escalation for build fix cycles (#497)
+- defer dispatched status until spawnAgent succeeds + add _any_ routing token (#482)
 -  move pin button to modal header next to Copy button
 - fetch actual build error logs instead of just reason string (#489)
 

package/dashboard/js/render-prs.js

@@ -12,8 +12,8 @@ function prRow(pr) {
   const reviewSource = sq.status || effectiveReviewStatus || 'pending';
   const reviewClass = reviewSource === 'approved' ? 'approved' : (reviewSource === 'changes-requested' || reviewSource === 'rejected') ? 'rejected' : reviewSource === 'waiting' ? 'building' : 'draft';
   const reviewLabel = sq.status === 'waiting' ? 'reviewing (minions)' : sq.status ? sq.status + ' (minions)' : (effectiveReviewStatus || 'pending');
-  const buildClass = pr._buildStatusStale ? 'build-stale' : pr.buildStatus === 'passing' ? 'build-pass' : pr.buildStatus === 'failing' ? 'build-fail' : pr.buildStatus === 'running' ? 'building' : 'no-build';
-  const buildLabel = (pr.buildStatus || 'none') + (pr._buildStatusStale ? ' (stale)' : '');
+  const buildClass = pr.buildFixEscalated ? 'build-escalated' : pr._buildStatusStale ? 'build-stale' : pr.buildStatus === 'passing' ? 'build-pass' : pr.buildStatus === 'failing' ? 'build-fail' : pr.buildStatus === 'running' ? 'building' : 'no-build';
+  const buildLabel = pr.buildFixEscalated ? 'escalated (' + (pr.buildFixAttempts || '?') + ' fixes)' : (pr.buildStatus || 'none') + (pr._buildStatusStale ? ' (stale)' : '');
   const statusClass = pr.status === 'merged' ? 'merged' : pr.status === 'abandoned' ? 'rejected' : pr.status === 'active' ? 'active' : 'draft';
   const statusLabel = pr.status || 'active';
   const url = pr.url || '#';

package/dashboard/styles.css

@@ -257,6 +257,7 @@
   .pr-badge.build-fail { background: rgba(248,81,73,0.15); color: var(--red); border: 1px solid var(--red); }
   .pr-badge.no-build { background: var(--surface); color: var(--muted); border: 1px solid var(--border); }
   .pr-badge.build-stale { background: rgba(210,153,34,0.15); color: var(--orange); border: 1px dashed var(--orange); }
+  .pr-badge.build-escalated { background: rgba(248,81,73,0.25); color: var(--red); border: 2px solid var(--red); font-weight: 600; }
   .error-details-btn { font-size: var(--text-xs); padding: var(--space-1) var(--space-3); margin-left: var(--space-2); background: rgba(248,81,73,0.15); color: var(--red); border: 1px solid var(--red); border-radius: var(--radius-lg); cursor: pointer; font-weight: 600; text-transform: uppercase; letter-spacing: 0.3px; }
   .error-details-btn:hover { background: rgba(248,81,73,0.3); }
   .pr-empty { color: var(--muted); font-style: italic; font-size: var(--text-md); padding: var(--space-6) 0; }

package/dashboard.js

@@ -3533,6 +3533,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           idleAlertMinutes: [1], shutdownTimeout: [30000], restartGracePeriod: [60000],
           meetingRoundTimeout: [60000],
           versionCheckInterval: [60000],
+          maxBuildFixAttempts: [1, 10],
         };
         for (const [key, [min, max]] of Object.entries(numericFields)) {
           if (e[key] !== undefined) {

package/engine/ado.js

@@ -254,6 +254,8 @@ async function pollPrStatus(config) {
           delete pr.buildFailReason;
           delete pr.buildErrorLog;
           delete pr._buildFailNotified;
+          delete pr.buildFixAttempts;
+          delete pr.buildFixEscalated;
         }
         await engine().handlePostMerge(pr, project, config, newStatus);
       }
@@ -365,6 +367,8 @@ async function pollPrStatus(config) {
       if (buildStatus !== 'failing') {
         delete pr._buildFailNotified;
         delete pr.buildErrorLog;
+        // Reset build fix retry counter on recovery — allows fresh auto-fix cycles if build breaks again
+        if (pr.buildFixAttempts) { delete pr.buildFixAttempts; delete pr.buildFixEscalated; }
       }
       updated = true;
 

package/engine/github.js

@@ -294,6 +294,8 @@ async function pollPrStatus(config) {
           delete pr.buildFailReason;
           delete pr.buildErrorLog;
           delete pr._buildFailNotified;
+          delete pr.buildFixAttempts;
+          delete pr.buildFixEscalated;
         }
         await engine().handlePostMerge(pr, project, config, newStatus);
       }
@@ -393,6 +395,8 @@ async function pollPrStatus(config) {
           if (buildStatus !== 'failing') {
             delete pr._buildFailNotified;
             delete pr.buildErrorLog;
+            // Reset build fix retry counter on recovery — allows fresh auto-fix cycles if build breaks again
+            if (pr.buildFixAttempts) { delete pr.buildFixAttempts; delete pr.buildFixEscalated; }
           }
           updated = true;
 

package/engine/routing.js

@@ -121,16 +121,26 @@ function resolveAgent(workType, config, authorAgent = null) {
     return true;
   };
 
-  // Check preferred and fallback first (routing table order)
-  if (preferred && isAvailable(preferred)) { _claimedAgents.add(preferred); return preferred; }
-  if (fallback && isAvailable(fallback)) { _claimedAgents.add(fallback); return fallback; }
+  // Helper: pick any idle agent sorted by error rate
+  const pickAnyIdle = (exclude = []) => {
+    const excludeSet = new Set(exclude.filter(Boolean));
+    const idle = Object.keys(agents)
+      .filter(id => !excludeSet.has(id) && isAvailable(id))
+      .sort((a, b) => getAgentErrorRate(a) - getAgentErrorRate(b));
+    if (idle[0]) { _claimedAgents.add(idle[0]); return idle[0]; }
+    return null;
+  };
 
-  // Fall back to any idle agent, preferring lower error rates
-  const idle = Object.keys(agents)
-    .filter(id => id !== preferred && id !== fallback && isAvailable(id))
-    .sort((a, b) => getAgentErrorRate(a) - getAgentErrorRate(b));
+  // Resolve _any_ token — pick any available agent (#480)
+  if (preferred === '_any_') { const pick = pickAnyIdle(); if (pick) return pick; }
+  else if (preferred && isAvailable(preferred)) { _claimedAgents.add(preferred); return preferred; }
 
-  if (idle[0]) { _claimedAgents.add(idle[0]); return idle[0]; }
+  if (fallback === '_any_') { const pick = pickAnyIdle([preferred]); if (pick) return pick; }
+  else if (fallback && isAvailable(fallback)) { _claimedAgents.add(fallback); return fallback; }
+
+  // Fall back to any idle agent, preferring lower error rates
+  const anyIdle = pickAnyIdle([preferred, fallback]);
+  if (anyIdle) return anyIdle;
 
   // No idle configured agent — try temp agent if enabled
   if (config.engine?.allowTempAgents) {

package/engine/shared.js

@@ -525,6 +525,7 @@ const ENGINE_DEFAULTS = {
   logBufferSize: 50, // flush immediately when buffer exceeds this many entries
   lockRetries: 2, // retry lock acquisition this many times after initial timeout (total attempts = 1 + lockRetries)
   lockRetryBackoffMs: 500, // base backoff between lock retries (doubles each attempt: 500ms, 1s, 2s, ...)
+  maxBuildFixAttempts: 3, // max consecutive auto-fix dispatch cycles per PR before escalation to human
 };
 
 // ─── Status & Type Constants ─────────────────────────────────────────────────

package/engine.js

@@ -1498,6 +1498,29 @@ async function discoverFromPrs(config, project) {
 
     // PRs with build failures — route to author (has session context from implementing)
     if (pr.status === PR_STATUS.ACTIVE && pr.buildStatus === 'failing') {
+      const maxBuildFix = config.engine?.maxBuildFixAttempts ?? ENGINE_DEFAULTS.maxBuildFixAttempts;
+
+      // Check if max retry cap reached — escalate to human instead of dispatching another fix
+      if ((pr.buildFixAttempts || 0) >= maxBuildFix) {
+        if (!pr.buildFixEscalated) {
+          writeInboxAlert(`build-fix-escalated-${pr.agent || 'unassigned'}-${pr.id}`,
+            `# Build Fix Escalation\n\n` +
+            `**PR ${pr.id}** on branch \`${pr.branch || 'unknown'}\` has failed **${pr.buildFixAttempts}** consecutive auto-fix attempts.\n` +
+            `**Last failure:** ${pr.buildFailReason || 'Check CI pipeline for details'}\n\n` +
+            `Auto-fix dispatch has been suspended. Please investigate manually.\n`
+          );
+          try {
+            const prPath = projectPrPath(project);
+            mutatePullRequests(prPath, prs => {
+              const target = prs.find(p => p.id === pr.id);
+              if (target) target.buildFixEscalated = true;
+            });
+          } catch (e) { log('warn', 'mark build fix escalated: ' + e.message); }
+          log('warn', `PR ${pr.id}: build fix escalated after ${pr.buildFixAttempts} attempts — suspending auto-dispatch`);
+        }
+        continue;
+      }
+
       const key = `build-fix-${project?.name || 'default'}-${pr.id}`;
       if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) continue;
       const agentId = resolveAgent('fix', config, pr.agent);
@@ -1512,7 +1535,17 @@ async function discoverFromPrs(config, project) {
         pr_id: pr.id, pr_branch: pr.branch || '',
         review_note: reviewNote,
       }, `Fix build failure on PR ${pr.id}`, { dispatchKey: key, source: 'pr', pr, branch: pr.branch, project: projMeta });
-      if (item) { newWork.push(item); setCooldown(key); }
+      if (item) {
+        newWork.push(item); setCooldown(key);
+        // Increment build fix attempts counter
+        try {
+          const prPath = projectPrPath(project);
+          mutatePullRequests(prPath, prs => {
+            const target = prs.find(p => p.id === pr.id);
+            if (target) target.buildFixAttempts = (target.buildFixAttempts || 0) + 1;
+          });
+        } catch (e) { log('warn', 'increment build fix attempts: ' + e.message); }
+      }
 
       // Notify the author agent about the build failure
       if (pr.agent && !pr._buildFailNotified) {
@@ -1556,7 +1589,7 @@ function discoverFromWorkItems(config, project) {
   const items = safeJson(projectWorkItemsPath(project)) || [];
   const cooldownMs = (src.cooldownMinutes || 0) * 60 * 1000;
   const newWork = [];
-  const prdSyncQueue = [];
+  // PRD sync for dispatched status deferred to spawnAgent success (#480)
   const skipped = { gated: 0, noAgent: 0 };
   let needsWrite = false;
   const selfHealKeys = new Set(); // Collect keys for batched self-heal (1 lock instead of N)
@@ -1603,10 +1636,11 @@ function discoverFromWorkItems(config, project) {
       needsWrite = true;
     }
     if (isAlreadyDispatched(key)) {
-      if (item.status === WI_STATUS.PENDING) { item.status = WI_STATUS.DISPATCHED; needsWrite = true; }
-      if (!item.dispatched_to) {
-        const existing = getDispatch().active?.find(d => d.meta?.dispatchKey === key);
-        if (existing?.agent) { item.dispatched_to = existing.agent; needsWrite = true; }
+      // Only self-heal to DISPATCHED if actually in dispatch.active (agent spawned) (#480)
+      const existingActive = getDispatch().active?.find(d => d.meta?.dispatchKey === key);
+      if (existingActive) {
+        if (item.status === WI_STATUS.PENDING) { item.status = WI_STATUS.DISPATCHED; needsWrite = true; }
+        if (!item.dispatched_to && existingActive.agent) { item.dispatched_to = existingActive.agent; needsWrite = true; }
       }
       if (item._pendingReason !== 'already_dispatched') { item._pendingReason = 'already_dispatched'; needsWrite = true; }
       skipped.gated++; continue;
@@ -1691,12 +1725,11 @@ function discoverFromWorkItems(config, project) {
       continue;
     }
 
-    // Mark item as dispatched BEFORE adding to newWork (prevents race on next tick)
-    item.status = WI_STATUS.DISPATCHED;
-    item.dispatched_at = ts();
-    item.dispatched_to = agentId;
+    // Don't mark dispatched here — item stays pending until spawnAgent succeeds.
+    // spawnAgent() atomically stamps dispatched_to/dispatched_at/status via locked write (#480).
+    // isAlreadyDispatched(key) prevents re-discovery on subsequent ticks.
     delete item._pendingReason;
-    prdSyncQueue.push({ id: item.id, sourcePlan: item.sourcePlan });
+    needsWrite = true;
 
     newWork.push({
       type: workType,
@@ -1738,12 +1771,9 @@ function discoverFromWorkItems(config, project) {
     }
   }
 
-  // Write back updated statuses (always, since we mark items dispatched before newWork check)
-  if (newWork.length > 0 || needsWrite) {
+  // Write back updated statuses (pendingReason clears, checkpoint counts, decompose flags, etc.)
+  if (needsWrite) {
     mutateWorkItems(projectWorkItemsPath(project), () => items);
-    if (newWork.length > 0) {
-      for (const s of prdSyncQueue) syncPrdItemStatus(s.id, 'dispatched', s.sourcePlan);
-    }
   }
 
   const skipTotal = skipped.gated + skipped.noAgent;
@@ -2030,13 +2060,14 @@ function discoverCentralWorkItems(config) {
     const key = `central-work-${item.id}`;
     // Self-heal: if already dispatched but work item is still pending, fix the status
     if (isAlreadyDispatched(key)) {
-      const m = {};
-      if (item.status === WI_STATUS.PENDING) { m.status = WI_STATUS.DISPATCHED; }
-      if (!item.dispatched_to) {
-        const existing = getDispatch().active?.find(d => d.meta?.dispatchKey === key);
-        if (existing?.agent) { m.dispatched_to = existing.agent; }
+      // Only self-heal to DISPATCHED if actually in dispatch.active (agent spawned) (#480)
+      const existingActive = getDispatch().active?.find(d => d.meta?.dispatchKey === key);
+      if (existingActive) {
+        const m = {};
+        if (item.status === WI_STATUS.PENDING) { m.status = WI_STATUS.DISPATCHED; }
+        if (!item.dispatched_to && existingActive.agent) { m.dispatched_to = existingActive.agent; }
+        if (Object.keys(m).length > 0) mutations.set(item.id, m);
       }
-      if (Object.keys(m).length > 0) mutations.set(item.id, m);
       continue;
     }
     if (isOnCooldown(key, 0)) continue;
@@ -2109,15 +2140,13 @@ function discoverCentralWorkItems(config) {
         });
       }
 
+      // Don't mark dispatched here — spawnAgent stamps status atomically (#480)
       mutations.set(item.id, {
-        status: WI_STATUS.DISPATCHED,
-        dispatched_at: ts(),
-        dispatched_to: idleAgents.map(a => a.id).join(', '),
         scope: 'fan-out',
         fanOutAgents: idleAgents.map(a => a.id),
       });
       setCooldown(key);
-      log('info', `Fan-out: ${item.id} dispatched to ${idleAgents.length} agents: ${idleAgents.map(a => a.name).join(', ')}`);
+      log('info', `Fan-out: ${item.id} queued for ${idleAgents.length} agents: ${idleAgents.map(a => a.name).join(', ')}`);
 
     } else {
       // ─── Normal: single agent dispatch ──────────────────────────────
@@ -2215,12 +2244,7 @@ function discoverCentralWorkItems(config) {
         continue;
       }
 
-      const dispatchMutation = {
-        status: WI_STATUS.DISPATCHED,
-        dispatched_at: ts(),
-        dispatched_to: agentId,
-      };
-      mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, dispatchMutation));
+      // Don't mark dispatched here — spawnAgent stamps status atomically (#480)
 
       newWork.push({
         type: workType,
@@ -2675,6 +2699,11 @@ async function tickInner() {
         }
       } else {
         dispatched.add(item.id);
+        // Sync PRD item status after successful spawn (#480)
+        if (item.meta?.item?.sourcePlan) {
+          try { syncPrdItemStatus(item.meta.item.id, WI_STATUS.DISPATCHED, item.meta.item.sourcePlan); }
+          catch (e) { log('warn', `prd sync after spawn: ${e.message}`); }
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.555",
+  "version": "0.1.557",
   "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/routing.md

@@ -10,7 +10,7 @@ How the engine decides who handles what. Parsed by engine.js — keep the table
 | implement | dallas | ralph |
 | implement:large | rebecca | dallas |
 | review | ripley | lambert |
-| fix | _author_ | dallas |
+| fix | _author_ | _any_ |
 | plan | ripley | rebecca |
 | plan-to-prd | lambert | rebecca |
 | explore | ripley | rebecca |
@@ -22,6 +22,7 @@ How the engine decides who handles what. Parsed by engine.js — keep the table
 
 Notes:
 - `_author_` means route to the PR author
+- `_any_` means route to any available idle agent (lowest error rate first)
 - `implement:large` is for items with `estimated_complexity: "large"`
 - Engine falls back to any idle agent if both preferred and fallback are busy