@yemi33/minions 0.1.526 → 0.1.528

package/CHANGELOG.md

@@ -1,9 +1,18 @@
 # 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
+- Replace direct safeJson reads of work-items.json with getWorkItems() (#424)
+
 ## 0.1.526 (2026-04-07)
 
 ### Features
-- Replace new Date().toISOString() with ts() from shared.js (#411)
 - Add Concurrency & Lock Ordering section to CLAUDE.md (#409)
 -  9 test isolation verification tests — run last to detect pollution
 

package/dashboard/js/render-work-items.js

@@ -175,8 +175,8 @@ async function submitWorkItemEdit(id, source, e) {
   const refsRaw = document.getElementById('wi-edit-refs')?.value || '';
   const references = refsRaw.split('\n').filter(function(l) { return l.trim(); }).map(function(l) {
     var parts = l.split('|').map(function(s) { return s.trim(); });
-    return { url: parts[0], title: parts[1] || parts[0], type: parts[2] || 'link' };
-  });
+    return { url: parts[0] || '', title: parts[1] || parts[0] || '', type: parts[2] || 'link' };
+  }).filter(function(r) { return r.url; });
   const acRaw = document.getElementById('wi-edit-ac')?.value || '';
   const acceptanceCriteria = acRaw.split('\n').filter(function(l) { return l.trim(); });
   if (!title) { if (btn) { btn.disabled = false; btn.textContent = 'Save'; } alert('Title is required'); return; }
@@ -387,8 +387,8 @@ async function _submitCreateWorkItem(e) {
   const refsRaw = document.getElementById('wi-new-refs')?.value || '';
   const references = refsRaw.split('\n').filter(l => l.trim()).map(l => {
     const parts = l.split('|').map(s => s.trim());
-    return { url: parts[0], title: parts[1] || parts[0], type: parts[2] || 'link' };
-  });
+    return { url: parts[0] || '', title: parts[1] || parts[0] || '', type: parts[2] || 'link' };
+  }).filter(r => r.url);
 
   try {
     const body = { title, description: desc, type, priority };

package/dashboard.js

@@ -192,8 +192,8 @@ async function checkNpmVersion() {
     _npmVersionCache = { latest: version || null, checkedAt: new Date().toISOString() };
     _npmVersionCacheTs = now;
   } catch (e) {
-    console.error('[version-check] npm view failed:', e.message?.split('\n')[0]);
-    _npmVersionCache = _npmVersionCache || { latest: null, checkedAt: null, error: e.message?.split('\n')[0] || 'check failed' };
+    console.error('[version-check] npm view failed:', e.message?.split('\n')?.[0]);
+    _npmVersionCache = _npmVersionCache || { latest: null, checkedAt: null, error: e.message?.split('\n')?.[0] || 'check failed' };
   }
   return _npmVersionCache;
 }
@@ -3816,7 +3816,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       // Determine project
       reloadConfig();
       const projects = shared.getProjects(CONFIG);
-      const targetProject = projectName ? projects.find(p => p.name?.toLowerCase() === projectName.toLowerCase()) : projects[0];
+      const targetProject = projectName ? projects.find(p => p.name?.toLowerCase() === projectName.toLowerCase()) : (projects[0] || null);
       const prPath = targetProject ? shared.projectPrPath(targetProject) : path.join(MINIONS_DIR, 'pull-requests.json');
 
       // Extract PR number from URL

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;
 
@@ -308,15 +308,9 @@ function runCleanup(config, verbose = false) {
     // Collect all work item IDs across all sources
     const allWiIds = new Set();
     try {
-      const central = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-      central.forEach(w => allWiIds.add(w.id));
-    } catch (e) { log('warn', 'read central work items for orphan check: ' + e.message); }
-    for (const project of projects) {
-      try {
-        const projItems = safeJson(projectWorkItemsPath(project)) || [];
-        projItems.forEach(w => allWiIds.add(w.id));
-      } catch (e) { log('warn', 'read project work items for orphan check: ' + e.message); }
-    }
+      const allItems = queries.getWorkItems();
+      allItems.forEach(w => allWiIds.add(w.id));
+    } catch (e) { log('warn', 'read work items for orphan check: ' + e.message); }
 
     let changed = false;
     for (const queue of ['pending', 'active']) {
@@ -460,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); }
@@ -478,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;
@@ -126,14 +126,8 @@ 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 = lifecycle().resolveWorkItemPath(item.meta);
-        if (wiPath) {
-          const items = safeJson(wiPath);
-          if (items && Array.isArray(items)) {
-            const wi = items.find(i => i.id === item.meta.item.id);
-            if (wi) retries = wi._retryCount || 0;
-          }
-        }
+        const wi = queries.getWorkItems().find(i => i.id === item.meta.item.id);
+        if (wi) retries = wi._retryCount || 0;
       } catch (e) { log('warn', 'read retry count: ' + e.message); }
       const maxRetries = ENGINE_DEFAULTS.maxRetries;
       if (retryableFailure && retries < maxRetries) {
@@ -152,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 {
@@ -178,13 +171,8 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
           const config = getConfig();
           const failedId = item.meta.item.id;
           const blockedItems = [];
-          for (const p of getProjects(config)) {
-            const items = safeJson(projectWorkItemsPath(p)) || [];
-            items.filter(w => w.status === WI_STATUS.PENDING && (w.depends_on || []).includes(failedId))
-              .forEach(w => blockedItems.push(`- \`${w.id}\` — ${w.title}`));
-          }
-          const centralItems = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-          centralItems.filter(w => w.status === WI_STATUS.PENDING && (w.depends_on || []).includes(failedId))
+          const allItems = queries.getWorkItems(config);
+          allItems.filter(w => w.status === WI_STATUS.PENDING && (w.depends_on || []).includes(failedId))
             .forEach(w => blockedItems.push(`- \`${w.id}\` — ${w.title}`));
 
           writeInboxAlert(`failed-${failedId}`,

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');
@@ -30,20 +30,7 @@ function checkPlanCompletion(meta, config) {
   const projects = shared.getProjects(config);
 
   // Collect work items from ALL projects + central (PRD items can be in either)
-  let allWorkItems = [];
-  for (const p of projects) {
-    try {
-      const wi = safeJson(shared.projectWorkItemsPath(p)) || [];
-      allWorkItems = allWorkItems.concat(wi);
-    } catch { /* optional */ }
-  }
-  // Also check central work-items.json (for no-project setups)
-  try {
-    const central = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-    for (const w of central) {
-      if (!allWorkItems.some(existing => existing.id === w.id)) allWorkItems.push(w);
-    }
-  } catch { /* optional */ }
+  const allWorkItems = queries.getWorkItems(config);
   const planItems = allWorkItems.filter(w => w.sourcePlan === planFile && w.itemType !== 'pr' && w.itemType !== 'verify');
   if (planItems.length === 0) return;
 
@@ -158,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) {
@@ -168,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);
     }
   }
 
@@ -257,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}`);
   }
 
@@ -330,19 +318,7 @@ function archivePlan(planFile, plan, projects, config) {
     if (plan.feature_branch) branchSlugs.add(shared.sanitizeBranch(plan.feature_branch).toLowerCase());
 
     // Collect work items for this plan
-    let allWorkItems = [];
-    for (const p of projects) {
-      try {
-        const wi = safeJson(shared.projectWorkItemsPath(p)) || [];
-        allWorkItems = allWorkItems.concat(wi);
-      } catch { /* optional */ }
-    }
-    try {
-      const central = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-      for (const w of central) {
-        if (!allWorkItems.some(existing => existing.id === w.id)) allWorkItems.push(w);
-      }
-    } catch { /* optional */ }
+    const allWorkItems = queries.getWorkItems(config);
     const planItems = allWorkItems.filter(w => w.sourcePlan === planFile);
     const doneItems = planItems.filter(w => DONE_STATUSES.has(w.status));
 
@@ -836,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/engine/playbook.js

@@ -133,7 +133,7 @@ function resolveTaskContext(item, config) {
       try {
         const plans = fs.readdirSync(path.join(MINIONS_DIR, 'plans')).filter(f => f.endsWith('.md') || f.endsWith('.json'));
         // Check work-items to find which plan file this agent created
-        const workItems = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
+        const workItems = queries.getWorkItems();
         const agentPlanItems = workItems.filter(w =>
           w.type === WORK_TYPE.PLAN && w.dispatched_to === agent.id && w.status === WI_STATUS.DONE && w._planFileName
         ).sort((a, b) => (b.completedAt || '').localeCompare(a.completedAt || ''));

package/engine/shared.js

@@ -738,6 +738,34 @@ function killImmediate(proc) {
   }
 }
 
+// ─── Work Items & Pull Requests Mutation Helpers ────────────────────────────
+
+/**
+ * Atomic read-modify-write for work-items JSON files.
+ * Wraps mutateJsonFileLocked with defaultValue of [].
+ * @param {string} filePath - Path to the work-items JSON file
+ * @param {Function} mutator - Receives the array, mutates in place or returns new value
+ */
+function mutateWorkItems(filePath, mutator) {
+  return mutateJsonFileLocked(filePath, (data) => {
+    if (!Array.isArray(data)) data = [];
+    return mutator(data) || data;
+  }, { defaultValue: [] });
+}
+
+/**
+ * Atomic read-modify-write for pull-requests JSON files.
+ * Wraps mutateJsonFileLocked with defaultValue of [].
+ * @param {string} filePath - Path to the pull-requests JSON file
+ * @param {Function} mutator - Receives the array, mutates in place or returns new value
+ */
+function mutatePullRequests(filePath, mutator) {
+  return mutateJsonFileLocked(filePath, (data) => {
+    if (!Array.isArray(data)) data = [];
+    return mutator(data) || data;
+  }, { defaultValue: [] });
+}
+
 module.exports = {
   MINIONS_DIR,
   PR_LINKS_PATH,
@@ -753,6 +781,8 @@ module.exports = {
   safeUnlink,
   withFileLock,
   mutateJsonFileLocked,
+  mutateWorkItems,
+  mutatePullRequests,
   uid,
   uniquePath,
   writeToInbox,

package/engine.js

@@ -149,16 +149,8 @@ function resolveDependencyBranches(depIds, sourcePlan, project, config) {
   const projects = shared.getProjects(config);
 
   // Find work items for each dependency plan item
-  const depWorkItems = [];
-  for (const p of projects) {
-    const wiPath = shared.projectWorkItemsPath(p);
-    const items = safeJson(wiPath) || [];
-    for (const wi of items) {
-      if (depIds.includes(wi.id)) {
-        depWorkItems.push(wi);
-      }
-    }
-  }
+  const allItems = queries.getWorkItems(config);
+  const depWorkItems = allItems.filter(wi => depIds.includes(wi.id));
 
   // Find PR branches for each dependency work item
   for (const p of projects) {
@@ -837,13 +829,7 @@ function areDependenciesMet(item, config) {
   const projects = getProjects(config);
 
   // Collect work items from ALL projects (dependencies can be cross-project)
-  let allWorkItems = [];
-  for (const p of projects) {
-    try {
-      const wi = safeJson(projectWorkItemsPath(p)) || [];
-      allWorkItems = allWorkItems.concat(wi);
-    } catch (e) { log('warn', 'read project work items for deps: ' + e.message); }
-  }
+  const allWorkItems = queries.getWorkItems(config);
   // PRD item statuses that count as "done" for dep resolution
   const PRD_MET_STATUSES = DONE_STATUSES;
 
@@ -1195,13 +1181,7 @@ function materializePlansAsWorkItems(config) {
     const statusFilter = ['missing', 'planned'];
     // Also materialize in-pr/done items that never got a work item (race with PR status sync)
     const allExistingWiIds = new Set();
-    for (const p of allProjects) {
-      for (const w of (safeJson(projectWorkItemsPath(p)) || [])) {
-        if (w.id) allExistingWiIds.add(w.id);
-      }
-    }
-    // Also check central work-items.json
-    for (const w of (safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [])) {
+    for (const w of queries.getWorkItems()) {
       if (w.id) allExistingWiIds.add(w.id);
     }
     const items = plan.missing_features.filter(f =>
@@ -2307,10 +2287,9 @@ function discoverWork(config) {
   }
 
   // Gate reviews and fixes: do not dispatch until all implement items are complete
-  const hasIncompleteImplements = projects.some(project => {
-    const items = safeJson(projectWorkItemsPath(project)) || [];
-    return items.some(i => ['queued', 'pending', 'dispatched'].includes(i.status) && (i.type || '').startsWith('implement'));
-  });
+  const hasIncompleteImplements = queries.getWorkItems(config).some(i =>
+    ['queued', 'pending', 'dispatched'].includes(i.status) && (i.type || '').startsWith('implement')
+  );
   if (hasIncompleteImplements) {
     if (allReviews.length > 0) {
       log('info', `Gating ${allReviews.length} reviews — implement items still in progress`);

package/package.json

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