@yemi33/minions 0.1.527 → 0.1.528

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.528 (2026-04-07)
+
+### Features
+- Convert engine/ safeWrite calls on work-items.json to mutateWorkItems() (#415)
+
 ## 0.1.527 (2026-04-07)
 
 ### Features

package/engine/cleanup.js

@@ -9,7 +9,7 @@ const shared = require('./shared');
 const queries = require('./queries');
 
 const { exec, execSilent, log, ts } = shared;
-const { safeJson, safeWrite, safeReadDir, getProjects, projectWorkItemsPath, projectPrPath,
+const { safeJson, safeWrite, safeReadDir, mutateWorkItems, getProjects, projectWorkItemsPath, projectPrPath,
   sanitizeBranch, KB_CATEGORIES } = shared;
 const { getDispatch, getAgentStatus } = queries;
 
@@ -454,17 +454,17 @@ function runCleanup(config, verbose = false) {
   for (const project of projects) {
     try {
       const wiPath = projectWorkItemsPath(project);
-      const items = safeJson(wiPath) || [];
       let migrated = 0;
-      for (const item of items) {
-        if (LEGACY_DONE_ALIASES.has(item.status)) {
-          item.status = shared.WI_STATUS.DONE;
-          delete item._pendingReason;
-          migrated++;
+      mutateWorkItems(wiPath, items => {
+        for (const item of items) {
+          if (LEGACY_DONE_ALIASES.has(item.status)) {
+            item.status = shared.WI_STATUS.DONE;
+            delete item._pendingReason;
+            migrated++;
+          }
         }
-      }
+      });
       if (migrated > 0) {
-        safeWrite(wiPath, items);
         log('info', `Migrated ${migrated} legacy status(es) → done in ${project.name} work items`);
       }
     } catch (e) { log('warn', 'migrate legacy statuses: ' + e.message); }
@@ -472,17 +472,17 @@ function runCleanup(config, verbose = false) {
   // Central work items
   try {
     const centralPath = path.join(MINIONS_DIR, 'work-items.json');
-    const centralItems = safeJson(centralPath) || [];
     let migrated = 0;
-    for (const item of centralItems) {
-      if (LEGACY_DONE_ALIASES.has(item.status)) {
-        item.status = shared.WI_STATUS.DONE;
-        delete item._pendingReason;
-        migrated++;
+    mutateWorkItems(centralPath, items => {
+      for (const item of items) {
+        if (LEGACY_DONE_ALIASES.has(item.status)) {
+          item.status = shared.WI_STATUS.DONE;
+          delete item._pendingReason;
+          migrated++;
+        }
       }
-    }
+    });
     if (migrated > 0) {
-      safeWrite(centralPath, centralItems);
       log('info', `Migrated ${migrated} legacy status(es) → done in central work items`);
     }
   } catch (e) { log('warn', 'migrate central legacy statuses: ' + e.message); }

package/engine/cli.js

@@ -6,7 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeRead, safeJson, safeWrite, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT } = shared;
+const { safeRead, safeJson, safeWrite, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT } = shared;
 const queries = require('./queries');
 const { getConfig, getControl, getDispatch, getAgentStatus,
   MINIONS_DIR, ENGINE_DIR, AGENTS_DIR, PLANS_DIR, PRD_DIR, CONTROL_PATH, DISPATCH_PATH } = queries;
@@ -165,18 +165,18 @@ const commands = {
             if (sj?.sessionId) sessionId = sj.sessionId;
           } catch {}
           e.activeProcesses.set(item.id, { proc: { pid: agentPid > 0 ? agentPid : null }, agentId, startedAt: item.created_at, reattached: true, sessionId });
-          // Sync work item status to dispatched — direct file write to avoid lifecycle lazy init issues
+          // Sync work item status to dispatched — atomic write to avoid lifecycle lazy init issues
           if (item.meta?.item?.id && item.meta?.project?.localPath) {
             try {
               const wiPath = path.join(MINIONS_DIR, "projects", item.meta.project.name, "work-items.json");
-              const wiItems = safeJson(wiPath) || [];
-              const wi = wiItems.find(w => w.id === item.meta.item.id);
-              if (wi && wi.status !== WI_STATUS.DISPATCHED) {
-                wi.status = WI_STATUS.DISPATCHED;
-                wi.dispatched_to = wi.dispatched_to || agentId;
-                wi.dispatched_at = wi.dispatched_at || ts();
-                safeWrite(wiPath, wiItems);
-              }
+              mutateWorkItems(wiPath, items => {
+                const wi = items.find(w => w.id === item.meta.item.id);
+                if (wi && wi.status !== WI_STATUS.DISPATCHED) {
+                  wi.status = WI_STATUS.DISPATCHED;
+                  wi.dispatched_to = wi.dispatched_to || agentId;
+                  wi.dispatched_at = wi.dispatched_at || ts();
+                }
+              });
             } catch (err) { console.log(`    Warning: failed to sync work item status: ${err.message}`); }
           }
           reattached++;
@@ -264,19 +264,19 @@ const commands = {
             try {
               lifecycle.updateWorkItemStatus(item.meta, status, isSuccess ? '' : 'Completed while engine was down');
             } catch {
-              // Direct file write fallback
+              // Atomic file write fallback
               try {
                 const projName = item.meta.project?.name;
                 if (projName) {
                   const wiPath = path.join(MINIONS_DIR, 'projects', projName, 'work-items.json');
-                  const items = safeJson(wiPath) || [];
-                  const wi = items.find(w => w.id === item.meta.item.id);
-                  if (wi) {
-                    wi.status = status;
-                    if (isSuccess) { wi.completedAt = ts(); delete wi.failReason; }
-                    else { wi.failedAt = ts(); wi.failReason = 'Completed while engine was down'; }
-                    safeWrite(wiPath, items);
-                  }
+                  mutateWorkItems(wiPath, items => {
+                    const wi = items.find(w => w.id === item.meta.item.id);
+                    if (wi) {
+                      wi.status = status;
+                      if (isSuccess) { wi.completedAt = ts(); delete wi.failReason; }
+                      else { wi.failedAt = ts(); wi.failReason = 'Completed while engine was down'; }
+                    }
+                  });
                 }
               } catch (err) { e.log('warn', `Orphan WI fallback: ${err.message}`); }
             }
@@ -321,19 +321,17 @@ const commands = {
       }
       for (const wiPath of allWiPaths) {
         try {
-          const items = safeJson(wiPath) || [];
-          let changed = false;
-          for (const item of items) {
-            if (item.status === WI_STATUS.DISPATCHED && !activeIds.has(item.id)) {
-              item.status = WI_STATUS.PENDING;
-              delete item.dispatched_at;
-              delete item.dispatched_to;
-              changed = true;
-              fixes++;
-              e.log('info', `Recovery: reset stuck item ${item.id} from dispatched → pending`);
+          mutateWorkItems(wiPath, items => {
+            for (const item of items) {
+              if (item.status === WI_STATUS.DISPATCHED && !activeIds.has(item.id)) {
+                item.status = WI_STATUS.PENDING;
+                delete item.dispatched_at;
+                delete item.dispatched_to;
+                fixes++;
+                e.log('info', `Recovery: reset stuck item ${item.id} from dispatched → pending`);
+              }
             }
-          }
-          if (changed) safeWrite(wiPath, items);
+          });
         } catch (err) { e.log('warn', `Recovery WI reset: ${err.message}`); }
       }
 
@@ -691,24 +689,23 @@ const commands = {
       ? projects.find(p => p.name?.toLowerCase() === opts.project?.toLowerCase()) || projects[0]
       : projects[0];
     const wiPath = projectWorkItemsPath(targetProject);
-    const items = safeJson(wiPath) || [];
-
-    const item = {
-      id: `W${String(items.length + 1).padStart(3, '0')}`,
-      title: title,
-      type: opts.type || 'implement',
-      status: WI_STATUS.QUEUED,
-      priority: opts.priority || 'medium',
-      complexity: opts.complexity || 'medium',
-      description: opts.description || title,
-      agent: opts.agent || null,
-      branch: opts.branch || null,
-      prompt: opts.prompt || null,
-      created_at: e.ts()
-    };
-
-    items.push(item);
-    safeWrite(wiPath, items);
+    let item;
+    mutateWorkItems(wiPath, items => {
+      item = {
+        id: `W${String(items.length + 1).padStart(3, '0')}`,
+        title: title,
+        type: opts.type || 'implement',
+        status: WI_STATUS.QUEUED,
+        priority: opts.priority || 'medium',
+        complexity: opts.complexity || 'medium',
+        description: opts.description || title,
+        agent: opts.agent || null,
+        branch: opts.branch || null,
+        prompt: opts.prompt || null,
+        created_at: e.ts()
+      };
+      items.push(item);
+    });
 
     console.log(`Queued work item: ${item.id} — ${item.title} (project: ${targetProject.name || 'default'})`);
     console.log(`  Type: ${item.type} | Priority: ${item.priority} | Agent: ${item.agent || 'auto'}`);
@@ -903,16 +900,16 @@ const commands = {
               ? shared.projectWorkItemsPath({ localPath: item.meta.project.localPath, name: item.meta.project.name, workSources: config.projects?.find(p => p.name === item.meta.project.name)?.workSources })
               : null;
           if (wiPath) {
-            const items = safeJson(wiPath) || [];
-            const target = items.find(i => i.id === itemId);
-            if (target) {
-              target.status = WI_STATUS.PENDING;
-              delete target.dispatched_at;
-              delete target.dispatched_to;
-              delete target.failReason;
-              delete target.failedAt;
-              safeWrite(wiPath, items);
-            }
+            mutateWorkItems(wiPath, items => {
+              const target = items.find(i => i.id === itemId);
+              if (target) {
+                target.status = WI_STATUS.PENDING;
+                delete target.dispatched_at;
+                delete target.dispatched_to;
+                delete target.failReason;
+                delete target.failedAt;
+              }
+            });
           }
         }
       }

package/engine/dispatch.js

@@ -9,7 +9,7 @@ const shared = require('./shared');
 const queries = require('./queries');
 const { setCooldownFailure } = require('./cooldown');
 
-const { safeJson, safeWrite, safeReadDir, mutateJsonFileLocked,
+const { safeJson, safeWrite, safeReadDir, mutateJsonFileLocked, mutateWorkItems,
   getProjects, projectWorkItemsPath, log, ts, dateStamp,
   WI_STATUS, DISPATCH_RESULT, ENGINE_DEFAULTS } = shared;
 const { getConfig, getDispatch, DISPATCH_PATH, INBOX_DIR } = queries;
@@ -146,20 +146,19 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
         try {
           const wiPath = lifecycle().resolveWorkItemPath(item.meta);
           if (wiPath) {
-            const items = safeJson(wiPath);
-            if (!items || !Array.isArray(items)) throw new Error('work items unreadable');
-            const wi = items.find(i => i.id === item.meta.item.id);
-            if (wi && wi.status !== WI_STATUS.PAUSED && wi.status !== WI_STATUS.DONE && !wi.completedAt) {
-              wi._retryCount = retries + 1;
-              wi.status = WI_STATUS.PENDING;
-              wi._lastRetryReason = reason || '';
-              wi._lastRetryAt = ts();
-              delete wi.failReason;
-              delete wi.failedAt;
-              delete wi.dispatched_at;
-              delete wi.dispatched_to;
-              safeWrite(wiPath, items);
-            }
+            mutateWorkItems(wiPath, items => {
+              const wi = items.find(i => i.id === item.meta.item.id);
+              if (wi && wi.status !== WI_STATUS.PAUSED && wi.status !== WI_STATUS.DONE && !wi.completedAt) {
+                wi._retryCount = retries + 1;
+                wi.status = WI_STATUS.PENDING;
+                wi._lastRetryReason = reason || '';
+                wi._lastRetryAt = ts();
+                delete wi.failReason;
+                delete wi.failedAt;
+                delete wi.dispatched_at;
+                delete wi.dispatched_to;
+              }
+            });
           }
         } catch (e) { log('warn', 'increment retry counter: ' + e.message); }
       } else {

package/engine/lifecycle.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const shared = require('./shared');
-const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, execSilent, projectPrPath, getPrLinks, addPrLink,
+const { safeRead, safeJson, safeWrite, mutateJsonFileLocked, mutateWorkItems, execSilent, projectPrPath, getPrLinks, addPrLink,
   log, ts, dateStamp, WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT,
   ENGINE_DEFAULTS } = shared;
 const { trackEngineUsage } = require('./llm');
@@ -145,7 +145,6 @@ function checkPlanCompletion(meta, config) {
     return;
   }
   const wiPath = shared.projectWorkItemsPath(primaryProject);
-  const workItems = safeJson(wiPath) || [];
 
   // 3. For shared-branch plans, create PR work item
   if (plan.branch_strategy === 'shared-branch' && plan.feature_branch && wiPath) {
@@ -155,15 +154,16 @@ function checkPlanCompletion(meta, config) {
       const featureBranch = plan.feature_branch;
       const mainBranch = shared.resolveMainBranch(primaryProject.localPath, primaryProject.mainBranch);
       const itemSummary = doneItems.map(w => '- ' + w.id + ': ' + w.title.replace('Implement: ', '')).join('\n');
-      workItems.push({
-        id, title: `Create PR for plan: ${plan.plan_summary || planFile}`,
-        type: 'implement', priority: 'high',
-        description: `All plan items from \`${planFile}\` are complete on branch \`${featureBranch}\`.\n\n**Branch:** \`${featureBranch}\`\n**Target:** \`${mainBranch}\`\n\n## Completed Items\n${itemSummary}`,
-        status: WI_STATUS.PENDING, created: ts(), createdBy: 'engine:plan-completion',
-        sourcePlan: planFile, itemType: 'pr',
-        branch: featureBranch, branchStrategy: 'shared-branch', project: projectName,
+      mutateWorkItems(wiPath, workItems => {
+        workItems.push({
+          id, title: `Create PR for plan: ${plan.plan_summary || planFile}`,
+          type: 'implement', priority: 'high',
+          description: `All plan items from \`${planFile}\` are complete on branch \`${featureBranch}\`.\n\n**Branch:** \`${featureBranch}\`\n**Target:** \`${mainBranch}\`\n\n## Completed Items\n${itemSummary}`,
+          status: WI_STATUS.PENDING, created: ts(), createdBy: 'engine:plan-completion',
+          sourcePlan: planFile, itemType: 'pr',
+          branch: featureBranch, branchStrategy: 'shared-branch', project: projectName,
+        });
       });
-      shared.safeWrite(wiPath, workItems);
     }
   }
 
@@ -244,20 +244,21 @@ function checkPlanCompletion(meta, config) {
       prSummary,
     ].join('\n');
 
-    workItems.push({
-      id: verifyId,
-      title: `Verify plan: ${(plan.plan_summary || planFile).slice(0, 80)}`,
-      type: 'verify',
-      priority: 'high',
-      description,
-      status: WI_STATUS.PENDING,
-      created: ts(),
-      createdBy: 'engine:plan-verification',
-      sourcePlan: planFile,
-      itemType: 'verify',
-      project: projectName,
+    mutateWorkItems(wiPath, workItems => {
+      workItems.push({
+        id: verifyId,
+        title: `Verify plan: ${(plan.plan_summary || planFile).slice(0, 80)}`,
+        type: 'verify',
+        priority: 'high',
+        description,
+        status: WI_STATUS.PENDING,
+        created: ts(),
+        createdBy: 'engine:plan-verification',
+        sourcePlan: planFile,
+        itemType: 'verify',
+        project: projectName,
+      });
     });
-    shared.safeWrite(wiPath, workItems);
     log('info', `Created verification work item ${verifyId} for plan ${planFile}`);
   }
 
@@ -811,17 +812,18 @@ async function handlePostMerge(pr, project, config, newStatus) {
     for (const p of shared.getProjects(config)) wiPaths.push(shared.projectWorkItemsPath(p));
     for (const wiPath of wiPaths) {
       try {
-        const items = safeJson(wiPath);
-        if (!items) continue;
-        const item = items.find(i => i.id === mergedItemId);
-        if (item && item.status !== WI_STATUS.DONE) {
-          log('info', `Post-merge: marking work item ${mergedItemId} as done (was ${item.status}) for ${pr.id}`);
-          item.status = WI_STATUS.DONE;
-          item.completedAt = ts();
-          item._mergedVia = pr.id;
-          shared.safeWrite(wiPath, items);
-          break;
-        }
+        let found = false;
+        mutateWorkItems(wiPath, items => {
+          const item = items.find(i => i.id === mergedItemId);
+          if (item && item.status !== WI_STATUS.DONE) {
+            log('info', `Post-merge: marking work item ${mergedItemId} as done (was ${item.status}) for ${pr.id}`);
+            item.status = WI_STATUS.DONE;
+            item.completedAt = ts();
+            item._mergedVia = pr.id;
+            found = true;
+          }
+        });
+        if (found) break;
       } catch (err) { log('warn', `Post-merge work item update: ${err.message}`); }
     }
   }

package/engine/pipeline.js

@@ -7,7 +7,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeJson, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, ENGINE_DEFAULTS } = shared;
+const { safeJson, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, ENGINE_DEFAULTS } = shared;
 const http = require('http');
 const { parseCronExpr, shouldRunNow } = require('./scheduler');
 
@@ -159,32 +159,32 @@ function executeTaskStage(stage, stageState, run, config) {
   const items = stage.items || [{ title: stage.title, description: stage.description || '', type: stage.taskType || 'explore', agent: stage.agent }];
   const count = stage.count || items.length;
   const wiPath = path.join(__dirname, '..', 'work-items.json');
-  const workItems = safeJson(wiPath) || [];
   const createdIds = [];
 
-  for (let i = 0; i < count; i++) {
-    const item = items[i % items.length];
-    const id = `PL-${run.runId.slice(4, 12)}-${stage.id}-${i}`;
-    if (workItems.some(w => w.id === id)) { createdIds.push(id); continue; }
-    workItems.push({
-      id,
-      title: item.title || stage.title,
-      description: item.description || stage.description || '',
-      type: item.type || stage.taskType || 'explore',
-      priority: item.priority || stage.priority || 'medium',
-      // Only set agent if explicitly specified — otherwise engine routing assigns any available agent
-      ...(item.agent || stage.agent ? { agent: item.agent || stage.agent } : {}),
-      status: WI_STATUS.PENDING,
-      created: ts(),
-      createdBy: 'pipeline:' + run.pipelineId,
-      branch: `pipeline/${run.pipelineId}/${stage.id}`,
-      _pipelineRun: run.runId,
-      _pipelineStage: stage.id,
-    });
-    createdIds.push(id);
-  }
+  mutateWorkItems(wiPath, workItems => {
+    for (let i = 0; i < count; i++) {
+      const item = items[i % items.length];
+      const id = `PL-${run.runId.slice(4, 12)}-${stage.id}-${i}`;
+      if (workItems.some(w => w.id === id)) { createdIds.push(id); continue; }
+      workItems.push({
+        id,
+        title: item.title || stage.title,
+        description: item.description || stage.description || '',
+        type: item.type || stage.taskType || 'explore',
+        priority: item.priority || stage.priority || 'medium',
+        // Only set agent if explicitly specified — otherwise engine routing assigns any available agent
+        ...(item.agent || stage.agent ? { agent: item.agent || stage.agent } : {}),
+        status: WI_STATUS.PENDING,
+        created: ts(),
+        createdBy: 'pipeline:' + run.pipelineId,
+        branch: `pipeline/${run.pipelineId}/${stage.id}`,
+        _pipelineRun: run.runId,
+        _pipelineStage: stage.id,
+      });
+      createdIds.push(id);
+    }
+  });
 
-  safeWrite(wiPath, workItems);
   return { status: PIPELINE_STATUS.RUNNING, artifacts: { workItems: createdIds } };
 }
 
@@ -280,24 +280,24 @@ async function executePlanStage(stage, stageState, run, config) {
 
   // Create plan-to-prd work item
   const wiPath = path.join(__dirname, '..', 'work-items.json');
-  const workItems = safeJson(wiPath) || [];
   const wiId = `PL-${run.runId.slice(4, 12)}-${stage.id}-prd`;
-  if (!workItems.some(w => w.id === wiId)) {
-    workItems.push({
-      id: wiId,
-      title: `Convert plan to PRD: ${path.basename(filePath)}`,
-      type: WORK_TYPE.PLAN_TO_PRD,
-      priority: 'high',
-      status: WI_STATUS.PENDING,
-      planFile: path.basename(filePath),
-      created: ts(),
-      createdBy: 'pipeline:' + run.pipelineId,
-      branch: `pipeline/${run.pipelineId}/${stage.id}`,
-      _pipelineRun: run.runId,
-      _pipelineStage: stage.id,
-    });
-    safeWrite(wiPath, workItems);
-  }
+  mutateWorkItems(wiPath, workItems => {
+    if (!workItems.some(w => w.id === wiId)) {
+      workItems.push({
+        id: wiId,
+        title: `Convert plan to PRD: ${path.basename(filePath)}`,
+        type: WORK_TYPE.PLAN_TO_PRD,
+        priority: 'high',
+        status: WI_STATUS.PENDING,
+        planFile: path.basename(filePath),
+        created: ts(),
+        createdBy: 'pipeline:' + run.pipelineId,
+        branch: `pipeline/${run.pipelineId}/${stage.id}`,
+        _pipelineRun: run.runId,
+        _pipelineStage: stage.id,
+      });
+    }
+  });
 
   return {
     status: PIPELINE_STATUS.RUNNING,

package/package.json

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