@yemi33/minions 0.1.533 → 0.1.535

package/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
-## 0.1.533 (2026-04-07)
+## 0.1.535 (2026-04-07)
+
+### Features
+- Convert engine.js safeWrite calls to mutateWorkItems/mutatePullRequests (#416)
 
 ### Fixes
+-  update pipeline work item status on dispatch (#443)
 - convert blocking spawnSync/execSync to async execAsync (#447)
 
 ## 0.1.532 (2026-04-07)

package/engine/pipeline.js

@@ -184,7 +184,6 @@ function executeTaskStage(stage, stageState, run, config) {
       createdIds.push(id);
     }
   });
-
   return { status: PIPELINE_STATUS.RUNNING, artifacts: { workItems: createdIds } };
 }
 
@@ -278,7 +277,7 @@ async function executePlanStage(stage, stageState, run, config) {
 
   safeWrite(filePath, content);
 
-  // Create plan-to-prd work item
+  // Create plan-to-prd work item — atomic write to prevent race with dispatch status updates
   const wiPath = path.join(__dirname, '..', 'work-items.json');
   const wiId = `PL-${run.runId.slice(4, 12)}-${stage.id}-prd`;
   mutateWorkItems(wiPath, workItems => {

package/engine.js

@@ -92,6 +92,8 @@ const safeJson = shared.safeJson;
 const safeRead = shared.safeRead;
 const safeWrite = shared.safeWrite;
 const mutateJsonFileLocked = shared.mutateJsonFileLocked;
+const mutateWorkItems = shared.mutateWorkItems;
+const mutatePullRequests = shared.mutatePullRequests;
 const withFileLock = shared.withFileLock;
 
 // ─── Dispatch Management (extracted to engine/dispatch.js) ───────────────────
@@ -1005,15 +1007,15 @@ function autoCleanPrdWorkItems(prdFile, config) {
   const deletedIds = [];
   for (const wiPath of wiPaths) {
     try {
-      const items = safeJson(wiPath);
-      if (!items) continue;
-      const filtered = items.filter(w => {
-        if (w.sourcePlan === prdFile && (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.FAILED)) {
-          deletedIds.push(w.id); return false;
-        }
-        return true;
+      mutateWorkItems(wiPath, items => {
+        const filtered = items.filter(w => {
+          if (w.sourcePlan === prdFile && (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.FAILED)) {
+            deletedIds.push(w.id); return false;
+          }
+          return true;
+        });
+        if (filtered.length < items.length) return filtered;
       });
-      if (filtered.length < items.length) safeWrite(wiPath, filtered);
     } catch (e) { log('warn', 'auto-clean PRD work items: ' + e.message); }
   }
   if (deletedIds.length > 0) {
@@ -1237,71 +1239,71 @@ function materializePlansAsWorkItems(config) {
     let totalCreated = 0;
     for (const [projName, { project, items: projItems }] of itemsByProject) {
       const wiPath = project ? projectWorkItemsPath(project) : path.join(MINIONS_DIR, 'work-items.json');
-      const existingItems = safeJson(wiPath) || [];
       let created = 0;
       const newlyCreatedIds = new Set(); // tracks IDs created in this pass for reconciliation scoping
 
-      for (const item of projItems) {
-        // Skip if already materialized — work item ID = PRD item ID, check all projects
-        let alreadyExists = existingItems.some(w => w.id === item.id);
-        if (!alreadyExists) {
-          for (const p of allProjects) {
-            if (p.name === projName) continue;
-            const otherItems = safeJson(projectWorkItemsPath(p)) || [];
-            if (otherItems.some(w => w.id === item.id)) { alreadyExists = true; break; }
+      mutateWorkItems(wiPath, existingItems => {
+        for (const item of projItems) {
+          // Skip if already materialized — work item ID = PRD item ID, check all projects
+          let alreadyExists = existingItems.some(w => w.id === item.id);
+          if (!alreadyExists) {
+            for (const p of allProjects) {
+              if (p.name === projName) continue;
+              const otherItems = safeJson(projectWorkItemsPath(p)) || [];
+              if (otherItems.some(w => w.id === item.id)) { alreadyExists = true; break; }
+            }
           }
+          if (alreadyExists) continue;
+          // Skip items involved in dependency cycles
+          if (cycleSet.has(item.id)) continue;
+
+          const id = item.id; // Work item ID = PRD item ID — no indirection
+          const complexity = item.estimated_complexity || 'medium';
+          const criteria = (item.acceptance_criteria || []).map(c => `- ${c}`).join('\n');
+
+          const newItem = {
+            id,
+            title: `Implement: ${item.name}`,
+            type: complexity === 'large' ? 'implement:large' : 'implement',
+            priority: item.priority || 'medium',
+            description: `${item.description || ''}\n\n**Plan:** ${file}\n**Plan Item:** ${item.id}\n**Complexity:** ${complexity}${criteria ? '\n\n**Acceptance Criteria:**\n' + criteria : ''}`,
+            status: 'pending',
+            created: ts(),
+            createdBy: 'engine:plan-discovery',
+            sourcePlan: file,
+            depends_on: item.depends_on || [],
+            branchStrategy: plan.branch_strategy || 'parallel',
+            featureBranch: plan.feature_branch || null,
+            project: item.project || plan.project || null,
+          };
+          existingItems.push(newItem);
+          newlyCreatedIds.add(id);
+          created++;
         }
-        if (alreadyExists) continue;
-        // Skip items involved in dependency cycles
-        if (cycleSet.has(item.id)) continue;
-
-        const id = item.id; // Work item ID = PRD item ID — no indirection
-        const complexity = item.estimated_complexity || 'medium';
-        const criteria = (item.acceptance_criteria || []).map(c => `- ${c}`).join('\n');
-
-        const newItem = {
-          id,
-          title: `Implement: ${item.name}`,
-          type: complexity === 'large' ? 'implement:large' : 'implement',
-          priority: item.priority || 'medium',
-          description: `${item.description || ''}\n\n**Plan:** ${file}\n**Plan Item:** ${item.id}\n**Complexity:** ${complexity}${criteria ? '\n\n**Acceptance Criteria:**\n' + criteria : ''}`,
-          status: 'pending',
-          created: ts(),
-          createdBy: 'engine:plan-discovery',
-          sourcePlan: file,
-          depends_on: item.depends_on || [],
-          branchStrategy: plan.branch_strategy || 'parallel',
-          featureBranch: plan.feature_branch || null,
-          project: item.project || plan.project || null,
-        };
-        existingItems.push(newItem);
-        newlyCreatedIds.add(id);
-        created++;
-      }
 
-      if (created > 0) {
-        // Reconciliation: exact prdItems match only, scoped to newly created items
-        const allPrsForReconcile = allProjects.flatMap(p => safeJson(projectPrPath(p)) || []);
-        const reconciled = reconcileItemsWithPrs(existingItems, allPrsForReconcile, { onlyIds: newlyCreatedIds });
-        if (reconciled > 0) log('info', `Plan reconciliation: marked ${reconciled} item(s) as done → ${projName}`);
-
-        // PRD removal sync: cancel pending work items whose PRD item was removed from the plan
-        const currentPrdIds = new Set(plan.missing_features.map(f => f.id));
-        let cancelled = 0;
-        for (const wi of existingItems) {
-          if (wi.status !== WI_STATUS.PENDING || wi.sourcePlan !== file) continue;
-          if (!currentPrdIds.has(wi.id)) {
-            wi.status = WI_STATUS.CANCELLED;
-            wi.cancelledAt = ts();
-            wi.cancelReason = `PRD item removed from ${file}`;
-            cancelled++;
+        if (created > 0) {
+          // Reconciliation: exact prdItems match only, scoped to newly created items
+          const allPrsForReconcile = allProjects.flatMap(p => safeJson(projectPrPath(p)) || []);
+          const reconciled = reconcileItemsWithPrs(existingItems, allPrsForReconcile, { onlyIds: newlyCreatedIds });
+          if (reconciled > 0) log('info', `Plan reconciliation: marked ${reconciled} item(s) as done → ${projName}`);
+
+          // PRD removal sync: cancel pending work items whose PRD item was removed from the plan
+          const currentPrdIds = new Set(plan.missing_features.map(f => f.id));
+          let cancelled = 0;
+          for (const wi of existingItems) {
+            if (wi.status !== WI_STATUS.PENDING || wi.sourcePlan !== file) continue;
+            if (!currentPrdIds.has(wi.id)) {
+              wi.status = WI_STATUS.CANCELLED;
+              wi.cancelledAt = ts();
+              wi.cancelReason = `PRD item removed from ${file}`;
+              cancelled++;
+            }
           }
-        }
-        if (cancelled > 0) log('info', `Plan sync: cancelled ${cancelled} item(s) removed from ${file} → ${projName}`);
+          if (cancelled > 0) log('info', `Plan sync: cancelled ${cancelled} item(s) removed from ${file} → ${projName}`);
 
-        safeWrite(wiPath, existingItems);
-        log('info', `Plan discovery: created ${created} work item(s) from ${file} → ${projName}`);
-      }
+          log('info', `Plan discovery: created ${created} work item(s) from ${file} → ${projName}`);
+        }
+      });
       totalCreated += created;
     }
 
@@ -1336,11 +1338,11 @@ function clearPendingHumanFeedbackFlag(projectMeta, prId) {
   if (!prId) return;
   try {
     const prsPath = projectPrPath(projectMeta);
-    const prs = safeJson(prsPath) || [];
-    const target = prs.find(p => p.id === prId);
-    if (!target?.humanFeedback?.pendingFix) return;
-    target.humanFeedback.pendingFix = false;
-    safeWrite(prsPath, prs);
+    mutatePullRequests(prsPath, prs => {
+      const target = prs.find(p => p.id === prId);
+      if (!target?.humanFeedback?.pendingFix) return;
+      target.humanFeedback.pendingFix = false;
+    });
   } catch (e) { log('warn', 'clear pending human feedback flag: ' + e.message); }
 }
 
@@ -1488,12 +1490,12 @@ function discoverFromPrs(config, project) {
         // Mark notified to prevent duplicate alerts
         try {
           const prPath = projectPrPath(project);
-          const prs = safeJson(prPath) || [];
-          const target = prs.find(p => p.id === pr.id);
-          if (target) {
-            target._buildFailNotified = true;
-            safeWrite(prPath, prs);
-          }
+          mutatePullRequests(prPath, prs => {
+            const target = prs.find(p => p.id === pr.id);
+            if (target) {
+              target._buildFailNotified = true;
+            }
+          });
         } catch (e) { log('warn', 'mark build fail notified: ' + e.message); }
       }
     }
@@ -1738,14 +1740,13 @@ function discoverFromWorkItems(config, project) {
   }
 
   // Write back updated statuses (always, since we mark items dispatched before newWork check)
-  if (newWork.length > 0) {
-    const workItemsPath = projectWorkItemsPath(project);
-    safeWrite(workItemsPath, items);
-    for (const s of prdSyncQueue) syncPrdItemStatus(s.id, 'dispatched', s.sourcePlan);
+  if (newWork.length > 0 || needsWrite) {
+    mutateWorkItems(projectWorkItemsPath(project), () => items);
+    if (newWork.length > 0) {
+      for (const s of prdSyncQueue) syncPrdItemStatus(s.id, 'dispatched', s.sourcePlan);
+    }
   }
 
-  if (needsWrite) safeWrite(projectWorkItemsPath(project), items);
-
   const skipTotal = skipped.gated + skipped.noAgent;
   if (skipTotal > 0) {
     log('debug', `Work item discovery (${project?.name}): skipped ${skipTotal} items (${skipped.gated} gated, ${skipped.noAgent} no agent)`);
@@ -1839,53 +1840,50 @@ function materializeSpecsAsWorkItems(config, project) {
   if (recentSpecs.length === 0) return;
 
   const wiPath = projectWorkItemsPath(project);
-  const existingItems = safeJson(wiPath) || [];
   let created = 0;
 
-  for (const pr of mergedPrs) {
-    const prBranch = (pr.branch || '').toLowerCase();
-    const matchedSpecs = recentSpecs.filter(doc => {
-      const msg = doc.message.toLowerCase();
-      // Match any doc whose commit message references this PR's branch
-      return prBranch && msg.includes(prBranch.split('/').pop());
-    });
-
-    if (matchedSpecs.length === 0) {
-      tracker.processedPrs[pr.id] = { processedAt: ts(), matched: false };
-      continue;
-    }
+  mutateWorkItems(wiPath, existingItems => {
+    for (const pr of mergedPrs) {
+      const prBranch = (pr.branch || '').toLowerCase();
+      const matchedSpecs = recentSpecs.filter(doc => {
+        const msg = doc.message.toLowerCase();
+        // Match any doc whose commit message references this PR's branch
+        return prBranch && msg.includes(prBranch.split('/').pop());
+      });
 
-    for (const doc of matchedSpecs) {
-      if (existingItems.some(i => i.sourceSpec === doc.file)) continue;
+      if (matchedSpecs.length === 0) {
+        tracker.processedPrs[pr.id] = { processedAt: ts(), matched: false };
+        continue;
+      }
 
-      const info = extractSpecInfo(doc.file, root);
-      if (!info) continue;
+      for (const doc of matchedSpecs) {
+        if (existingItems.some(i => i.sourceSpec === doc.file)) continue;
 
-      const newId = 'SP-' + shared.uid();
+        const info = extractSpecInfo(doc.file, root);
+        if (!info) continue;
 
-      existingItems.push({
-        id: newId,
-        type: 'implement',
-        title: `Implement: ${info.title}`,
-        description: `Implementation work from merged spec.\n\n**Spec:** \`${doc.file}\`\n**Source PR:** ${pr.id} — ${pr.title || ''}\n**PR URL:** ${pr.url || 'N/A'}\n\n## Summary\n\n${info.summary}\n\nRead the full spec at \`${doc.file}\` before starting.`,
-        priority: info.priority,
-        status: 'queued',
-        created: ts(),
-        createdBy: 'engine:spec-discovery',
-        sourceSpec: doc.file,
-        sourcePr: pr.id
-      });
-      created++;
-      log('info', `Spec discovery: created ${newId} "${info.title}" from PR ${pr.id} in ${project.name}`);
-    }
+        const newId = 'SP-' + shared.uid();
 
-    tracker.processedPrs[pr.id] = { processedAt: ts(), matched: true, specs: matchedSpecs.map(d => d.file) };
-  }
+        existingItems.push({
+          id: newId,
+          type: 'implement',
+          title: `Implement: ${info.title}`,
+          description: `Implementation work from merged spec.\n\n**Spec:** \`${doc.file}\`\n**Source PR:** ${pr.id} — ${pr.title || ''}\n**PR URL:** ${pr.url || 'N/A'}\n\n## Summary\n\n${info.summary}\n\nRead the full spec at \`${doc.file}\` before starting.`,
+          priority: info.priority,
+          status: 'queued',
+          created: ts(),
+          createdBy: 'engine:spec-discovery',
+          sourceSpec: doc.file,
+          sourcePr: pr.id
+        });
+        created++;
+        log('info', `Spec discovery: created ${newId} "${info.title}" from PR ${pr.id} in ${project.name}`);
+      }
 
-  if (created > 0) {
-    safeWrite(wiPath, existingItems);
-  }
-  safeWrite(trackerPath, tracker);
+      tracker.processedPrs[pr.id] = { processedAt: ts(), matched: true, specs: matchedSpecs.map(d => d.file) };
+    }
+  });
+  mutateJsonFileLocked(trackerPath, () => tracker, { defaultValue: {} });
 }
 
 /**
@@ -1939,13 +1937,26 @@ function discoverCentralWorkItems(config) {
   const items = safeJson(centralPath) || [];
   const projects = getProjects(config);
   const newWork = [];
+  // Collect mutations to apply atomically inside lock callback (avoids TOCTOU)
+  const mutations = new Map(); // item.id → { field: value, ... }
 
   for (const item of items) {
     try {
     if (item.status !== WI_STATUS.QUEUED && item.status !== WI_STATUS.PENDING) continue;
 
     const key = `central-work-${item.id}`;
-    if (isAlreadyDispatched(key) || isOnCooldown(key, 0)) continue;
+    // 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; }
+      }
+      if (Object.keys(m).length > 0) mutations.set(item.id, m);
+      continue;
+    }
+    if (isOnCooldown(key, 0)) continue;
 
     const workType = item.type || 'implement';
     const isFanOut = item.scope === 'fan-out';
@@ -2029,11 +2040,13 @@ function discoverCentralWorkItems(config) {
         });
       }
 
-      item.status = WI_STATUS.DISPATCHED;
-      item.dispatched_at = ts();
-      item.dispatched_to = idleAgents.map(a => a.id).join(', ');
-      item.scope = 'fan-out';
-      item.fanOutAgents = idleAgents.map(a => a.id);
+      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(', ')}`);
 
@@ -2085,11 +2098,10 @@ function discoverCentralWorkItems(config) {
           const cpCount = (item._checkpointCount || 0) + 1;
           if (cpCount > 3) {
             log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as needs-human-review`);
-            item.status = WI_STATUS.NEEDS_REVIEW;
-            item._checkpointCount = cpCount;
+            mutations.set(item.id, { status: WI_STATUS.NEEDS_REVIEW, _checkpointCount: cpCount });
             continue;
           }
-          item._checkpointCount = cpCount;
+          mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { _checkpointCount: cpCount }));
           const cpSummary = [
             `## Checkpoint (Resume #${cpCount}/3)`,
             '',
@@ -2117,7 +2129,7 @@ function discoverCentralWorkItems(config) {
         vars.notes_content = '';
         try { vars.notes_content = fs.readFileSync(path.join(MINIONS_DIR, 'notes.md'), 'utf8'); } catch { /* optional */ }
         // Track expected plan filename in meta for chainPlanToPrd
-        item._planFileName = planFileName;
+        mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { _planFileName: planFileName }));
       }
 
       // Inject plan-to-prd variables — read the plan file content for the playbook
@@ -2172,6 +2184,13 @@ 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));
+
       newWork.push({
         type: workType,
         agent: agentId,
@@ -2179,18 +2198,25 @@ function discoverCentralWorkItems(config) {
         agentRole,
         task: item.title || item.description?.slice(0, 80) || item.id,
         prompt,
-        meta: { dispatchKey: key, source: 'central-work-item', item, planFileName: item.planFile || item._planFileName || null, branch: item.branch || item.featureBranch || `work/${item.id}` }
+        meta: { dispatchKey: key, source: 'central-work-item', item, planFileName: item.planFile || mutations.get(item.id)?._planFileName || null, branch: item.branch || item.featureBranch || `work/${item.id}` }
       });
 
-      item.status = WI_STATUS.DISPATCHED;
-      item.dispatched_at = ts();
-      item.dispatched_to = agentId;
       setCooldown(key);
     }
     } catch (err) { log('warn', `discoverCentralWorkItems: skipping ${item.id}: ${err.message}`); }
   }
 
-  if (newWork.length > 0) safeWrite(centralPath, items);
+  if (mutations.size > 0) {
+    // True atomic read-modify-write — applies mutations to fresh locked data
+    mutateJsonFileLocked(centralPath, (freshItems) => {
+      if (!Array.isArray(freshItems)) freshItems = [];
+      for (const fi of freshItems) {
+        const m = mutations.get(fi.id);
+        if (m) Object.assign(fi, m);
+      }
+      return freshItems;
+    }, { defaultValue: [] });
+  }
   return newWork;
 }
 
@@ -2238,24 +2264,33 @@ function discoverWork(config) {
     if (scheduledWork.length > 0) {
       const { createMeeting, getMeetings } = require('./engine/meeting');
       const centralPath = path.join(MINIONS_DIR, 'work-items.json');
-      const items = safeJson(centralPath) || [];
-      let added = 0;
+      // Separate meetings (no work-items write) from task items
+      const taskItems = [];
       for (const item of scheduledWork) {
         if (item.type === WORK_TYPE.MEETING) {
-          // Create a real multi-agent meeting instead of a single-agent work item
           const sched = (config.schedules || []).find(s => s.id === item._scheduleId);
           const participants = (sched && sched.participants) || [];
           const meeting = createMeeting({ title: item.title, agenda: item.description, participants });
           log('info', `Scheduled meeting created: ${item._scheduleId} → ${meeting.id} (${participants.length} participants)`);
         } else {
-          if (!items.some(i => i._scheduleId === item._scheduleId && i.status !== WI_STATUS.DONE && i.status !== WI_STATUS.FAILED)) {
-            items.push(item);
-            added++;
-            log('info', `Scheduled task fired: ${item._scheduleId} → ${item.title}`);
-          }
+          taskItems.push(item);
         }
       }
-      if (added > 0) safeWrite(centralPath, items);
+      if (taskItems.length > 0) {
+        // Atomic write — prevents race with dispatch status updates on central work-items.json
+        mutateJsonFileLocked(centralPath, (items) => {
+          if (!Array.isArray(items)) items = [];
+          let added = 0;
+          for (const item of taskItems) {
+            if (!items.some(i => i._scheduleId === item._scheduleId && i.status !== WI_STATUS.DONE && i.status !== WI_STATUS.FAILED)) {
+              items.push(item);
+              added++;
+              log('info', `Scheduled task fired: ${item._scheduleId} → ${item.title}`);
+            }
+          }
+          return items;
+        }, { defaultValue: [] });
+      }
     }
   } catch (e) { log('warn', 'discover scheduled work: ' + e.message); }
 
@@ -2435,78 +2470,77 @@ async function tickInner() {
         for (const project of projects) {
           try {
             const wiPath = projectWorkItemsPath(project);
-            const items = safeJson(wiPath) || [];
-            let changed = false;
-            const failedIds = new Set(items.filter(w => w.status === WI_STATUS.FAILED).map(w => w.id));
-            const pendingWithBlockedDeps = items.filter(w =>
-              w.status === WI_STATUS.PENDING && (w.depends_on || []).some(d => failedIds.has(d))
-            );
-
-            if (pendingWithBlockedDeps.length > 0) {
-              // Auto-retry failed items that are blocking others (transient errors)
-              for (const item of items) {
-                if (item.status !== WI_STATUS.FAILED || isItemCompleted(item)) continue;
-                // Only retry if something depends on this item
-                const isBlocking = items.some(w => w.status === WI_STATUS.PENDING && (w.depends_on || []).includes(item.id));
-                if (!isBlocking) continue;
-
-                log('info', `Stall recovery: auto-retrying ${item.id} (blocking ${pendingWithBlockedDeps.filter(w => (w.depends_on || []).includes(item.id)).length} items)`);
-                item.status = WI_STATUS.PENDING;
-                item._retryCount = 0;
-                delete item.failReason;
-                delete item.failedAt;
-                delete item.dispatched_at;
-                delete item.dispatched_to;
-                changed = true;
-
-                // Clear completed dispatch entries so isAlreadyDispatched doesn't block re-dispatch
-                try {
-                    const key = `work-${project.name}-${item.id}`;
-                    mutateDispatch((dp) => {
-                      dp.completed = dp.completed.filter(d => d.meta?.dispatchKey !== key);
-                      return dp;
-                    });
-                  } catch (e) { log('warn', 'stall recovery clear dispatch: ' + e.message); }
-
-                // Clear cooldown so item isn't blocked by exponential backoff
-                try {
-                  const key = `work-${project.name}-${item.id}`;
-                  if (dispatchCooldowns.has(key)) {
-                    dispatchCooldowns.delete(key);
-                    saveCooldowns();
-                  }
-                } catch (e) { log('warn', 'stall recovery clear cooldown: ' + e.message); }
-              }
-            }
-
-            // Un-fail dependent items that were cascade-failed
-            if (changed) {
-              const retriedIds = new Set(items.filter(w => w.status === WI_STATUS.PENDING && w._retryCount === 0).map(w => w.id));
-              for (const dep of items) {
-                if (dep.status === WI_STATUS.FAILED && !isItemCompleted(dep) && dep.failReason === 'Dependency failed — cannot proceed') {
-                  const blockers = (dep.depends_on || []).filter(d => retriedIds.has(d));
-                  if (blockers.length > 0) {
-                    log('info', `Stall recovery: un-failing ${dep.id} (blocker ${blockers.join(',')} retried)`);
-                    dep.status = WI_STATUS.PENDING;
-                    dep._retryCount = 0;
-                    delete dep.failReason;
-                    delete dep.failedAt;
-                    delete dep.dispatched_at;
-                    delete dep.dispatched_to;
-                    // Clear dispatch entries for this dependent too
-                    try {
-                      const key = `work-${project.name}-${dep.id}`;
+            mutateWorkItems(wiPath, items => {
+              let changed = false;
+              const failedIds = new Set(items.filter(w => w.status === WI_STATUS.FAILED).map(w => w.id));
+              const pendingWithBlockedDeps = items.filter(w =>
+                w.status === WI_STATUS.PENDING && (w.depends_on || []).some(d => failedIds.has(d))
+              );
+
+              if (pendingWithBlockedDeps.length > 0) {
+                // Auto-retry failed items that are blocking others (transient errors)
+                for (const item of items) {
+                  if (item.status !== WI_STATUS.FAILED || isItemCompleted(item)) continue;
+                  // Only retry if something depends on this item
+                  const isBlocking = items.some(w => w.status === WI_STATUS.PENDING && (w.depends_on || []).includes(item.id));
+                  if (!isBlocking) continue;
+
+                  log('info', `Stall recovery: auto-retrying ${item.id} (blocking ${pendingWithBlockedDeps.filter(w => (w.depends_on || []).includes(item.id)).length} items)`);
+                  item.status = WI_STATUS.PENDING;
+                  item._retryCount = 0;
+                  delete item.failReason;
+                  delete item.failedAt;
+                  delete item.dispatched_at;
+                  delete item.dispatched_to;
+                  changed = true;
+
+                  // Clear completed dispatch entries so isAlreadyDispatched doesn't block re-dispatch
+                  try {
+                      const key = `work-${project.name}-${item.id}`;
                       mutateDispatch((dp) => {
                         dp.completed = dp.completed.filter(d => d.meta?.dispatchKey !== key);
                         return dp;
                       });
-                    } catch (e) { log('warn', 'stall recovery clear dependent dispatch: ' + e.message); }
-                  }
+                    } catch (e) { log('warn', 'stall recovery clear dispatch: ' + e.message); }
+
+                  // Clear cooldown so item isn't blocked by exponential backoff
+                  try {
+                    const key = `work-${project.name}-${item.id}`;
+                    if (dispatchCooldowns.has(key)) {
+                      dispatchCooldowns.delete(key);
+                      saveCooldowns();
+                    }
+                  } catch (e) { log('warn', 'stall recovery clear cooldown: ' + e.message); }
                 }
               }
-            }
 
-            if (changed) safeWrite(wiPath, items);
+              // Un-fail dependent items that were cascade-failed
+              if (changed) {
+                const retriedIds = new Set(items.filter(w => w.status === WI_STATUS.PENDING && w._retryCount === 0).map(w => w.id));
+                for (const dep of items) {
+                  if (dep.status === WI_STATUS.FAILED && !isItemCompleted(dep) && dep.failReason === 'Dependency failed — cannot proceed') {
+                    const blockers = (dep.depends_on || []).filter(d => retriedIds.has(d));
+                    if (blockers.length > 0) {
+                      log('info', `Stall recovery: un-failing ${dep.id} (blocker ${blockers.join(',')} retried)`);
+                      dep.status = WI_STATUS.PENDING;
+                      dep._retryCount = 0;
+                      delete dep.failReason;
+                      delete dep.failedAt;
+                      delete dep.dispatched_at;
+                      delete dep.dispatched_to;
+                      // Clear dispatch entries for this dependent too
+                      try {
+                        const key = `work-${project.name}-${dep.id}`;
+                        mutateDispatch((dp) => {
+                          dp.completed = dp.completed.filter(d => d.meta?.dispatchKey !== key);
+                          return dp;
+                        });
+                      } catch (e) { log('warn', 'stall recovery clear dependent dispatch: ' + e.message); }
+                    }
+                  }
+                }
+              }
+            });
           } catch (e) { log('warn', 'stall recovery process project: ' + e.message); }
         }
       }
@@ -2591,19 +2625,19 @@ async function tickInner() {
               ? path.join(ENGINE_DIR, '..', 'work-items.json')
               : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
             if (wiPath) {
-              const items = safeJson(wiPath) || [];
-              const wi = items.find(i => i.id === item.meta.item.id);
-              if (wi && wi.status === WI_STATUS.DISPATCHED) {
-                // completeDispatch didn't update the work item — re-queue manually
-                wi.status = WI_STATUS.PENDING;
-                wi._retryCount = (wi._retryCount || 0) + 1;
-                wi._lastRetryReason = 'spawnAgent returned null';
-                wi._lastRetryAt = ts();
-                delete wi.dispatched_at;
-                delete wi.dispatched_to;
-                safeWrite(wiPath, items);
-                log('info', `Re-queued ${item.meta.item.id} as pending (retry ${wi._retryCount})`);
-              }
+              mutateWorkItems(wiPath, items => {
+                const wi = items.find(i => i.id === item.meta.item.id);
+                if (wi && wi.status === WI_STATUS.DISPATCHED) {
+                  // completeDispatch didn't update the work item — re-queue manually
+                  wi.status = WI_STATUS.PENDING;
+                  wi._retryCount = (wi._retryCount || 0) + 1;
+                  wi._lastRetryReason = 'spawnAgent returned null';
+                  wi._lastRetryAt = ts();
+                  delete wi.dispatched_at;
+                  delete wi.dispatched_to;
+                  log('info', `Re-queued ${item.meta.item.id} as pending (retry ${wi._retryCount})`);
+                }
+              });
             }
           } catch (e) { log('warn', `Failed to re-queue work item after spawn failure: ${e.message}`); }
         }

package/package.json

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