@yemi33/minions 0.1.347 → 0.1.348

package/CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 
-## 0.1.347 (2026-04-04)
+## 0.1.348 (2026-04-04)
+
+### Fixes
+-  comprehensive status mutation guards — prevent done items from being reverted
 
 ### Other
 - docs: update CLAUDE.md with constants, best practices, latest architecture

package/dashboard.js

@@ -14,7 +14,7 @@ const shared = require('./engine/shared');
 const queries = require('./engine/queries');
 const os = require('os');
 
-const { safeRead, safeReadDir, safeWrite, safeJson, safeUnlink, mutateJsonFileLocked, getProjects: _getProjects } = shared;
+const { safeRead, safeReadDir, safeWrite, safeJson, safeUnlink, mutateJsonFileLocked, getProjects: _getProjects, DONE_STATUSES } = shared;
 const { getAgents, getAgentDetail, getPrdInfo, getWorkItems, getDispatchQueue,
   getSkills, getInbox, getNotesWithMeta, getPullRequests,
   getEngineLog, getMetrics, getKnowledgeBaseEntries, timeSince,
@@ -895,6 +895,11 @@ const server = http.createServer(async (req, res) => {
         if (!Array.isArray(items)) items = [];
         const item = items.find(i => i.id === id);
         if (!item) return items;
+        // Don't reset completed items unless explicitly forced
+        if ((item.status === 'done' || item.completedAt) && !body.force) {
+          found = 'already_done';
+          return items;
+        }
         found = true;
         item.status = 'pending';
         item._retryCount = 0; // Reset retry counter on manual retry
@@ -902,9 +907,11 @@ const server = http.createServer(async (req, res) => {
         delete item.dispatched_to;
         delete item.failReason;
         delete item.failedAt;
+        delete item.completedAt;
         delete item.fanOutAgents;
         return items;
       });
+      if (found === 'already_done') return jsonReply(res, 409, { error: 'item already completed — use force:true to retry' });
       if (!found) return jsonReply(res, 404, { error: 'item not found' });
 
       // Clear completed dispatch entries so the engine doesn't dedup this item
@@ -1800,20 +1807,19 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       }
       for (const wiPath of wiPaths) {
         try {
-          const items = safeJson(wiPath);
-          if (!items) continue;
-          let changed = false;
-          for (const w of items) {
-            if (w.sourcePlan === body.file && w.status === 'paused' && w._pausedBy === 'prd-pause') {
-              w.status = 'pending';
-              delete w._pausedBy;
-              w._resumedAt = new Date().toISOString();
-              resumedItemIds.push(w.id);
-              resumed++;
-              changed = true;
+          mutateJsonFileLocked(wiPath, (items) => {
+            if (!Array.isArray(items)) return items;
+            for (const w of items) {
+              if (w.sourcePlan === body.file && w.status === 'paused' && w._pausedBy === 'prd-pause') {
+                w.status = 'pending';
+                delete w._pausedBy;
+                w._resumedAt = new Date().toISOString();
+                resumedItemIds.push(w.id);
+                resumed++;
+              }
             }
-          }
-          if (changed) safeWrite(wiPath, items);
+            return items;
+          }, { defaultValue: [] });
         } catch (e) { console.error('resume work items:', e.message); }
       }
 
@@ -1864,7 +1870,7 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
             for (const w of items) {
               if (w.sourcePlan !== body.file) continue;
               // Keep completed items as-is, reset everything else to pending.
-              if (w.status === 'done' || w.status === 'implemented' || w.status === 'complete' || w.status === 'in-pr') continue;
+              if (w.completedAt || DONE_STATUSES.has(w.status)) continue;
 
               if (w.status === 'dispatched') {
                 // Kill the agent working on this item, if any.
@@ -2574,7 +2580,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
                     let changed = false;
                     for (const w of items) {
                       if (w.sourcePlan !== f) continue;
-                      if (w.status === 'done' || w.status === 'implemented' || w.status === 'complete' || w.status === 'in-pr') continue;
+                      if (w.completedAt || DONE_STATUSES.has(w.status)) continue;
                       if (w.status === 'dispatched') {
                         const activeEntry = (dispatch.active || []).find(d => d.meta?.item?.id === w.id || d.meta?.dispatchKey?.includes(w.id));
                         if (activeEntry) {

package/engine/dispatch.js

@@ -104,9 +104,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     if (processWorkItemFailure && result === DISPATCH_RESULT.ERROR && item.meta?.item?.id) {
       let retries = (item.meta.item._retryCount || 0);
       try {
-        const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
-          ? path.join(MINIONS_DIR, 'work-items.json')
-          : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
+        const wiPath = lifecycle().resolveWorkItemPath(item.meta);
         if (wiPath) {
           const items = safeJson(wiPath);
           if (items && Array.isArray(items)) {
@@ -130,9 +128,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
         }
         // Increment retry counter on the source work item
         try {
-          const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
-            ? path.join(MINIONS_DIR, 'work-items.json')
-            : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
+          const wiPath = lifecycle().resolveWorkItemPath(item.meta);
           if (wiPath) {
             const items = safeJson(wiPath);
             if (!items || !Array.isArray(items)) throw new Error('work items unreadable');

package/engine/lifecycle.js

@@ -477,6 +477,24 @@ function chainPlanToPrd(dispatchItem, meta, config) {
   shared.safeWrite(wiPath, items);
 }
 
+// ─── Work Item Path Resolution ───────────────────────────────────────────────
+
+/** Resolve the work-items.json path from dispatch meta. Reused by retry paths. */
+function resolveWorkItemPath(meta) {
+  if (meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout') {
+    return path.join(MINIONS_DIR, 'work-items.json');
+  }
+  if (meta.source === 'work-item' && meta.project?.name) {
+    return path.join(MINIONS_DIR, 'projects', meta.project.name, 'work-items.json');
+  }
+  return null;
+}
+
+/** Check if a work item is in a terminal completed state. */
+function isItemCompleted(item) {
+  return item.status === WI_STATUS.DONE || !!item.completedAt;
+}
+
 // ─── Work Item Status ────────────────────────────────────────────────────────
 const _VALID_WI_STATUSES = new Set(Object.values(WI_STATUS));
 function updateWorkItemStatus(meta, status, reason) {
@@ -488,19 +506,14 @@ function updateWorkItemStatus(meta, status, reason) {
     return;
   }
 
-  let wiPath;
-  if (meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout') {
-    wiPath = path.join(MINIONS_DIR, 'work-items.json');
-  } else if (meta.source === 'work-item' && meta.project?.name) {
-    wiPath = path.join(MINIONS_DIR, 'projects', meta.project.name, 'work-items.json');
-  }
+  const wiPath = resolveWorkItemPath(meta);
   if (!wiPath) return;
 
-  const items = safeJson(wiPath);
-  if (!items || !Array.isArray(items)) return;
+  mutateJsonFileLocked(wiPath, (items) => {
+    if (!items || !Array.isArray(items)) return items;
+    const target = items.find(i => i.id === itemId);
+    if (!target) return items;
 
-  const target = items.find(i => i.id === itemId);
-  if (target) {
     if (meta.source === 'central-work-item-fanout') {
       if (!target.agentResults) target.agentResults = {};
       const parts = (meta.dispatchKey || '').split('-');
@@ -538,13 +551,11 @@ function updateWorkItemStatus(meta, status, reason) {
         target.failedAt = ts();
       }
     }
+    return items;
+  }, { defaultValue: [] });
 
-    shared.safeWrite(wiPath, items);
-    log('info', `Work item ${itemId} → ${status}${reason ? ': ' + reason : ''}`);
-
-    // Sync status to PRD JSON so the two share the same value (work item is source of truth)
-    syncPrdItemStatus(itemId, status, meta.item?.sourcePlan);
-  }
+  log('info', `Work item ${itemId} → ${status}${reason ? ': ' + reason : ''}`);
+  syncPrdItemStatus(itemId, status, meta.item?.sourcePlan);
 }
 
 const _VALID_PRD_STATUSES = new Set([...Object.values(WI_STATUS), 'missing']);
@@ -1371,5 +1382,7 @@ module.exports = {
   parseAgentOutput,
   runPostCompletionHooks,
   syncPrdFromPrs,
+  resolveWorkItemPath,
+  isItemCompleted,
 };
 

package/engine/timeout.js

@@ -8,7 +8,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeRead, safeWrite, safeJson, getProjects, projectWorkItemsPath, log, ts,
+const { safeRead, safeWrite, safeJson, mutateJsonFileLocked, getProjects, projectWorkItemsPath, log, ts,
   ENGINE_DEFAULTS: DEFAULTS, WI_STATUS, DISPATCH_RESULT } = shared;
 const { getDispatch, getAgentStatus } = queries;
 const AGENTS_DIR = queries.AGENTS_DIR;
@@ -229,43 +229,43 @@ function checkTimeouts(config) {
     allWiPaths.push(projectWorkItemsPath(project));
   }
   for (const wiPath of allWiPaths) {
-    const items = safeJson(wiPath);
-    if (!items || !Array.isArray(items)) continue;
-    let changed = false;
-    for (const item of items) {
-      if (item.status !== WI_STATUS.DISPATCHED) continue;
-      // Check if any active dispatch references this item
-      // Dispatch keys include project name: work-{project}-{id} or central-work-{id}
-      const projectNames = getProjects(config).map(p => p.name);
-      const possibleKeys = [
-        `central-work-${item.id}`,
-        ...projectNames.map(p => `work-${p}-${item.id}`),
-      ];
-      const isActive = possibleKeys.some(k => activeKeys.has(k)) ||
-        (dispatchData.active || []).some(d => d.meta?.item?.id === item.id);
-      if (!isActive) {
-        // Don't revive items that were explicitly failed for non-retryable reasons
-        if (item.status === WI_STATUS.FAILED && item.failReason && !item.failReason.includes('Agent died')) continue;
-        const retries = (item._retryCount || 0);
-        const maxRetries = DEFAULTS.maxRetries;
-        if (retries < maxRetries) {
-          log('info', `Reconcile: work item ${item.id} agent died — auto-retry ${retries + 1}/${maxRetries}`);
-          item.status = WI_STATUS.PENDING;
-          item._retryCount = retries + 1;
-          delete item.dispatched_at;
-          delete item.dispatched_to;
-          delete item._pendingReason;
-        } else {
-          log('warn', `Reconcile: work item ${item.id} failed after ${retries} retries — marking as failed`);
-          item.status = WI_STATUS.FAILED;
-          item.failReason = `Agent died or was killed (${maxRetries} retries exhausted)`;
-          item.failedAt = ts();
-          delete item._pendingReason;
+    mutateJsonFileLocked(wiPath, (items) => {
+      if (!items || !Array.isArray(items)) return items;
+      let changed = false;
+      for (const item of items) {
+        if (item.status !== WI_STATUS.DISPATCHED) continue;
+        // Never revert completed items
+        if (item.completedAt || item.status === WI_STATUS.DONE) continue;
+        // Check if any active dispatch references this item
+        const projectNames = getProjects(config).map(p => p.name);
+        const possibleKeys = [
+          `central-work-${item.id}`,
+          ...projectNames.map(p => `work-${p}-${item.id}`),
+        ];
+        const isActive = possibleKeys.some(k => activeKeys.has(k)) ||
+          (dispatchData.active || []).some(d => d.meta?.item?.id === item.id);
+        if (!isActive) {
+          const retries = (item._retryCount || 0);
+          const maxRetries = DEFAULTS.maxRetries;
+          if (retries < maxRetries) {
+            log('info', `Reconcile: work item ${item.id} agent died — auto-retry ${retries + 1}/${maxRetries}`);
+            item.status = WI_STATUS.PENDING;
+            item._retryCount = retries + 1;
+            delete item.dispatched_at;
+            delete item.dispatched_to;
+            delete item._pendingReason;
+          } else {
+            log('warn', `Reconcile: work item ${item.id} failed after ${retries} retries — marking as failed`);
+            item.status = WI_STATUS.FAILED;
+            item.failReason = `Agent died or was killed (${maxRetries} retries exhausted)`;
+            item.failedAt = ts();
+            delete item._pendingReason;
+          }
+          changed = true;
         }
-        changed = true;
       }
-    }
-    if (changed) safeWrite(wiPath, items);
+      return items;
+    }, { defaultValue: [] });
   }
 }
 

package/engine.js

@@ -132,7 +132,8 @@ const { renderPlaybook, buildSystemPrompt, buildAgentContext, selectPlaybook,
 
 const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, handlePostMerge, checkPlanCompletion,
   syncPrsFromOutput, updatePrAfterReview, updatePrAfterFix, checkForLearnings, extractSkillsFromOutput,
-  updateAgentHistory, updateMetrics, createReviewFeedbackForAuthor, parseAgentOutput, syncPrdFromPrs } = require('./engine/lifecycle');
+  updateAgentHistory, updateMetrics, createReviewFeedbackForAuthor, parseAgentOutput, syncPrdFromPrs,
+  isItemCompleted } = require('./engine/lifecycle');
 
 // ─── Agent Spawner ──────────────────────────────────────────────────────────
 
@@ -1381,7 +1382,7 @@ function discoverFromWorkItems(config, project) {
   for (const item of items) {
     try {
     // Re-evaluate failed items: if deps have recovered, reset to pending
-    if (item.status === WI_STATUS.FAILED && item.failReason === 'Dependency failed — cannot proceed') {
+    if (item.status === WI_STATUS.FAILED && !isItemCompleted(item) && item.failReason === 'Dependency failed — cannot proceed') {
       const depStatus = areDependenciesMet(item, config);
       if (depStatus === true) {
         item.status = WI_STATUS.PENDING;
@@ -1396,7 +1397,7 @@ function discoverFromWorkItems(config, project) {
     // Dependency gate: skip items whose depends_on are not yet met; propagate failure
     if (item.depends_on && item.depends_on.length > 0) {
       const depStatus = areDependenciesMet(item, config);
-      if (depStatus === 'failed') {
+      if (depStatus === 'failed' && !isItemCompleted(item)) {
         item.status = WI_STATUS.FAILED;
         item.failReason = 'Dependency failed — cannot proceed';
         delete item._pendingReason;
@@ -2272,7 +2273,7 @@ async function tickInner() {
             if (pendingWithBlockedDeps.length > 0) {
               // Auto-retry failed items that are blocking others (transient errors)
               for (const item of items) {
-                if (item.status !== 'failed') continue;
+                if (item.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;
@@ -2310,7 +2311,7 @@ async function tickInner() {
             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 && dep.failReason === 'Dependency failed — cannot proceed') {
+                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)`);

package/package.json

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