@yemi33/minions 0.1.908 → 0.1.910

package/CHANGELOG.md

@@ -1,13 +1,21 @@
 # Changelog
 
-## 0.1.908 (2026-04-13)
+## 0.1.910 (2026-04-13)
 
 ### Features
+- replace magic string 'active' with PR_STATUS.ACTIVE in lifecycle.js (#969)
+- fix dashboard plan-pause nested lock violation (#968)
+- add missing branch_name to central dispatch vars (#967)
+- fix dispatch.js mutator fallback to use nullish coalescing (#966)
+- fix stall recovery nested lock violation (#965)
+- fix pending-rebases.json race condition with file locking (#964)
+- add missing resolveWorkItemPath import in engine.js (#963)
 - bump plan-to-prd max turns from 20 to 35
 - add weekly dead code & deprecated cleanup pipeline
 - add red dot notification on CC tab when response completes (#934) (#946)
 
 ### Fixes
+- pass sysPromptPath instead of steerPromptPath as system prompt in steering resume (#962)
 -  PRD item display dispatched/in-progress status conflation (closes #950) (#955)
 - remove KB watchdog — checkpoint never written, restore never worked
 - make KB sweep endpoint async with status polling (#933)

package/dashboard.js

@@ -2366,77 +2366,101 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       safeWrite(planPath, plan);
 
       // Propagate pause to materialized work items across all projects:
-      // kill any active agent process and reset non-completed items back to pending.
-      let reset = 0;
+      // kill any active agent process and reset non-completed items to paused.
+      // Pattern: collect-then-release-then-act to avoid nested locks and long lock holds.
       const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
       for (const proj of PROJECTS) {
         wiPaths.push(shared.projectWorkItemsPath(proj));
       }
       const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
-      const killedAgents = new Set();
-      const resetItemIds = new Set();
 
-      // Read dispatch inside the lock so PID list is consistent with state being modified
-      mutateJsonFileLocked(dispatchPath, (dispatch) => {
-        for (const wiPath of wiPaths) {
+      // Step 1: Read work items (read-only, no lock) to find plan items that are dispatched.
+      const dispatchedItemIds = new Set();
+      for (const wiPath of wiPaths) {
+        try {
+          const items = safeJsonArr(wiPath);
+          for (const w of items) {
+            if (w.sourcePlan !== body.file) continue;
+            if (w.completedAt || DONE_STATUSES.has(w.status)) continue;
+            if (w.status === WI_STATUS.DISPATCHED && w.id) dispatchedItemIds.add(w.id);
+          }
+        } catch { /* file may not exist */ }
+      }
+
+      // Step 2: Read dispatch.json (read-only, no lock) to collect kill targets.
+      const killTargets = []; // { agent, pid, statusPath }
+      const dispatch = safeJsonObj(dispatchPath);
+      const activeEntries = Array.isArray(dispatch.active) ? dispatch.active : [];
+      for (const d of activeEntries) {
+        const itemId = d.meta?.item?.id;
+        const matchesById = itemId && dispatchedItemIds.has(itemId);
+        const matchesByKey = d.meta?.dispatchKey && [...dispatchedItemIds].some(id => d.meta.dispatchKey.includes(id));
+        if (matchesById || matchesByKey) {
+          const statusPath = path.join(MINIONS_DIR, 'agents', d.agent, 'status.json');
           try {
-            mutateWorkItems(wiPath, items => {
-              let changed = false;
-              for (const w of items) {
-                if (w.sourcePlan !== body.file) continue;
-                // Keep completed items as-is, reset everything else to pending.
-                if (w.completedAt || DONE_STATUSES.has(w.status)) continue;
-
-                if (w.status === WI_STATUS.DISPATCHED) {
-                  // Kill the agent working on this item, if any.
-                  const activeEntry = (dispatch.active || []).find(d => d.meta?.item?.id === w.id || d.meta?.dispatchKey?.includes(w.id));
-                  if (activeEntry) {
-                    const statusPath = path.join(MINIONS_DIR, 'agents', activeEntry.agent, 'status.json');
-                    try {
-                      const agentStatus = safeJsonObj(statusPath);
-                      if (agentStatus.pid) {
-                        try {
-                          const safePid = shared.validatePid(agentStatus.pid);
-                          if (process.platform === 'win32') {
-                            require('child_process').execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
-                          } else {
-                            process.kill(safePid, 'SIGTERM');
-                          }
-                        } catch { /* process may be dead or invalid PID */ }
-                      }
-                      agentStatus.status = 'idle';
-                      delete agentStatus.currentTask;
-                      delete agentStatus.dispatched;
-                      safeWrite(statusPath, agentStatus);
-                    } catch (e) { console.error('agent reset:', e.message); }
-                    killedAgents.add(activeEntry.agent);
-                  }
-                }
+            const agentStatus = safeJsonObj(statusPath);
+            killTargets.push({ agent: d.agent, pid: agentStatus.pid || null, statusPath });
+          } catch { killTargets.push({ agent: d.agent, pid: null, statusPath }); }
+        }
+      }
 
-                if (w.status !== WI_STATUS.PAUSED) reset++;
-                w.status = WI_STATUS.PAUSED;
-                w._pausedBy = 'prd-pause';
-                delete w._resumedAt;
-                delete w.dispatched_at;
-                delete w.dispatched_to;
-                delete w.failReason;
-                delete w.failedAt;
-                changed = true;
-                if (w.id) resetItemIds.add(w.id);
-              }
-            });
-          } catch (e) { console.error('reset work items:', e.message); }
+      // Step 3: Kill agent processes OUTSIDE any lock (expensive, may take seconds).
+      const killedAgents = new Set();
+      for (const target of killTargets) {
+        if (target.pid) {
+          try {
+            const safePid = shared.validatePid(target.pid);
+            if (process.platform === 'win32') {
+              require('child_process').execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
+            } else {
+              process.kill(safePid, 'SIGTERM');
+            }
+          } catch { /* process may be dead or invalid PID */ }
         }
+        // Reset agent status file (no lock needed — agent-specific file).
+        try {
+          const agentStatus = safeJsonObj(target.statusPath);
+          agentStatus.status = 'idle';
+          delete agentStatus.currentTask;
+          delete agentStatus.dispatched;
+          safeWrite(target.statusPath, agentStatus);
+        } catch (e) { console.error('agent reset:', e.message); }
+        killedAgents.add(target.agent);
+      }
+
+      // Step 4: Mutate work-items.json per path — pause items (each lock held briefly, no nesting).
+      let reset = 0;
+      const resetItemIds = new Set();
+      for (const wiPath of wiPaths) {
+        try {
+          mutateWorkItems(wiPath, items => {
+            for (const w of items) {
+              if (w.sourcePlan !== body.file) continue;
+              if (w.completedAt || DONE_STATUSES.has(w.status)) continue;
+              if (w.status !== WI_STATUS.PAUSED) reset++;
+              w.status = WI_STATUS.PAUSED;
+              w._pausedBy = 'prd-pause';
+              delete w._resumedAt;
+              delete w.dispatched_at;
+              delete w.dispatched_to;
+              delete w.failReason;
+              delete w.failedAt;
+              if (w.id) resetItemIds.add(w.id);
+            }
+          });
+        } catch (e) { console.error('reset work items:', e.message); }
+      }
 
-        // Remove dispatch active entries for reset items or killed agents.
-        dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
-        dispatch.active = dispatch.active.filter(d => {
+      // Step 5: Re-acquire dispatch lock to clean up active entries (brief lock, no nesting).
+      mutateJsonFileLocked(dispatchPath, (dispatchData) => {
+        dispatchData.active = Array.isArray(dispatchData.active) ? dispatchData.active : [];
+        dispatchData.active = dispatchData.active.filter(d => {
           const itemId = d.meta?.item?.id;
           if (itemId && resetItemIds.has(itemId)) return false;
           if (killedAgents.has(d.agent)) return false;
           return true;
         });
-        return dispatch;
+        return dispatchData;
       }, { defaultValue: { pending: [], active: [], completed: [] } });
 
       invalidateStatusCache();

package/engine/dispatch.js

@@ -30,7 +30,7 @@ function mutateDispatch(mutator) {
     dispatch.pending = Array.isArray(dispatch.pending) ? dispatch.pending : [];
     dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
     dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
-    return mutator(dispatch) || dispatch;
+    return mutator(dispatch) ?? dispatch;
   }, { defaultValue: defaultDispatch });
   // Invalidate the read cache so next getDispatch() sees fresh data
   try { require('./queries').invalidateDispatchCache(); } catch {}

package/engine/lifecycle.js

@@ -962,7 +962,7 @@ function findDependentActivePrs(mergedItemId, config) {
   for (const p of projects) {
     const prs = safeJson(projectPrPath(p)) || [];
     for (const pr of prs) {
-      if (!pr.branch || pr.status !== 'active') continue;
+      if (!pr.branch || pr.status !== PR_STATUS.ACTIVE) continue;
       const linked = (pr.prdItems || []).some(id => dependentWis.some(wi => wi.id === id));
       if (linked && !results.some(r => r.pr.id === pr.id)) {
         const wi = dependentWis.find(w => (pr.prdItems || []).includes(w.id));
@@ -1020,25 +1020,31 @@ async function rebaseBranchOntoMain(pr, project, config) {
 const PENDING_REBASES_PATH = path.join(ENGINE_DIR, 'pending-rebases.json');
 
 function queuePendingRebase(pr, project, mergedItemId) {
-  const pending = safeJson(PENDING_REBASES_PATH) || [];
-  if (pending.some(e => e.prId === pr.id)) return; // already queued
-  pending.push({ prId: pr.id, branch: pr.branch, projectName: project.name, mergedItemId, queuedAt: ts(), attempts: 0 });
-  safeWrite(PENDING_REBASES_PATH, pending);
+  mutateJsonFileLocked(PENDING_REBASES_PATH, (pending) => {
+    if (pending.some(e => e.prId === pr.id)) return; // already queued
+    pending.push({ prId: pr.id, branch: pr.branch, projectName: project.name, mergedItemId, queuedAt: ts(), attempts: 0 });
+  }, { defaultValue: [] });
 }
 
 async function processPendingRebases(config) {
-  const pending = safeJson(PENDING_REBASES_PATH) || [];
-  if (pending.length === 0) return;
+  // Atomically drain the queue under lock so concurrent queuePendingRebase calls
+  // during processing don't lose entries (they append to the now-empty file).
+  let snapshot = [];
+  mutateJsonFileLocked(PENDING_REBASES_PATH, (data) => {
+    snapshot = [...data];
+    return []; // drain file
+  }, { defaultValue: [] });
+  if (snapshot.length === 0) return;
 
   const remaining = [];
-  for (const entry of pending) {
+  for (const entry of snapshot) {
     if (isBranchActive(entry.branch)) { remaining.push(entry); continue; }
 
     const project = shared.getProjects(config).find(p => p.name === entry.projectName);
     if (!project) continue;
 
     const prs = safeJson(projectPrPath(project)) || [];
-    const pr = prs.find(p => p.id === entry.prId && p.status === 'active');
+    const pr = prs.find(p => p.id === entry.prId && p.status === PR_STATUS.ACTIVE);
     if (!pr) continue; // PR closed/merged since queuing
 
     const result = await rebaseBranchOntoMain(pr, project, config);
@@ -1052,7 +1058,12 @@ async function processPendingRebases(config) {
       }
     }
   }
-  safeWrite(PENDING_REBASES_PATH, remaining);
+  // Merge remaining items back under lock — entries queued during processing are preserved
+  if (remaining.length > 0) {
+    mutateJsonFileLocked(PENDING_REBASES_PATH, (data) => {
+      data.push(...remaining);
+    }, { defaultValue: [] });
+  }
 }
 
 // ─── Post-Merge / Post-Close Hooks ───────────────────────────────────────────

package/engine.js

@@ -138,7 +138,7 @@ const { renderPlaybook, validatePlaybookVars, PLAYBOOK_REQUIRED_VARS,
 const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, reconcilePrdStatuses, handlePostMerge, checkPlanCompletion,
   syncPrsFromOutput, updatePrAfterReview, updatePrAfterFix, checkForLearnings, extractSkillsFromOutput,
   updateAgentHistory, updateMetrics, createReviewFeedbackForAuthor, parseAgentOutput, syncPrdFromPrs,
-  isItemCompleted, classifyFailure, processPendingRebases } = require('./engine/lifecycle');
+  isItemCompleted, classifyFailure, processPendingRebases, resolveWorkItemPath } = require('./engine/lifecycle');
 
 // ─── Agent Spawner ──────────────────────────────────────────────────────────
 
@@ -848,7 +848,7 @@ async function spawnAgent(dispatchItem, config) {
       const childEnv = shared.cleanChildEnv();
       let resumeProc;
       try {
-        resumeProc = runFile(process.execPath, [spawnScript, steerPromptPath, steerPromptPath, ...resumeArgs], {
+        resumeProc = runFile(process.execPath, [spawnScript, steerPromptPath, sysPromptPath, ...resumeArgs], {
           cwd,
           stdio: ['pipe', 'pipe', 'pipe'],
           env: childEnv,
@@ -2485,6 +2485,7 @@ function discoverCentralWorkItems(config) {
 
         const ap = assignedProject || (projects.length > 0 ? projects[0] : null);
         if (!ap) { log('warn', `Fan-out: skipping ${fanKey} — no projects configured`); continue; }
+        const fanBranch = `fan/${item.id}/${agent.id}`;
         const vars = {
           ...buildBaseVars(agent.id, config, ap),
           item_id: item.id,
@@ -2495,6 +2496,7 @@ function discoverCentralWorkItems(config) {
           additional_context: item.prompt ? `## Additional Context\n\n${item.prompt}` : '',
           scope_section: buildProjectContext(projects, assignedProject, true, agent.name, agent.role),
           project_path: ap?.localPath || '',
+          branch_name: fanBranch,
         };
 
         // Build common vars: references, acceptance criteria, notes (ASK only), task context
@@ -2519,7 +2521,7 @@ function discoverCentralWorkItems(config) {
           prompt,
           meta: {
             dispatchKey: fanKey, source: 'central-work-item-fanout', item, parentKey: key,
-            branch: `fan/${item.id}/${agent.id}`,
+            branch: fanBranch,
             deadline: item.timeout ? Date.now() + item.timeout : Date.now() + (config.engine?.fanOutTimeout || config.engine?.agentTimeout || DEFAULTS.agentTimeout)
           }
         });
@@ -2564,6 +2566,7 @@ function discoverCentralWorkItems(config) {
         additional_context: item.prompt ? `## Additional Context\n\n${item.prompt}` : '',
         scope_section: buildProjectContext(projects, null, false, agentName, agentRole),
         project_path: firstProject?.localPath || '',
+        branch_name: centralBranch,
       };
       const centralWtPath = firstProject?.localPath
         ? path.resolve(firstProject.localPath, config.engine?.worktreeRoot || '../worktrees', centralBranch)
@@ -2944,6 +2947,10 @@ async function tickInner() {
         for (const project of projects) {
           try {
             const wiPath = projectWorkItemsPath(project);
+            // Collect keys to clear AFTER work-items lock is released (avoid nested locks)
+            const dispatchKeysToClear = [];
+            const cooldownKeysToClear = [];
+
             mutateWorkItems(wiPath, items => {
               let changed = false;
               const failedIds = new Set(items.filter(w => w.status === WI_STATUS.FAILED).map(w => w.id));
@@ -2968,23 +2975,10 @@ async function tickInner() {
                   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); }
+                  // Collect dispatch + cooldown keys for clearing outside lock
+                  const key = `work-${project.name}-${item.id}`;
+                  dispatchKeysToClear.push(key);
+                  cooldownKeysToClear.push(key);
                 }
               }
 
@@ -3002,19 +2996,33 @@ async function tickInner() {
                       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); }
+                      // Collect dispatch key for clearing outside lock
+                      dispatchKeysToClear.push(`work-${project.name}-${dep.id}`);
                     }
                   }
                 }
               }
             });
+
+            // Clear dispatch entries AFTER work-items lock is released (no nested locks)
+            for (const key of dispatchKeysToClear) {
+              try {
+                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 cooldowns AFTER work-items lock is released
+            for (const key of cooldownKeysToClear) {
+              try {
+                if (dispatchCooldowns.has(key)) {
+                  dispatchCooldowns.delete(key);
+                  saveCooldowns();
+                }
+              } catch (e) { log('warn', 'stall recovery clear cooldown: ' + e.message); }
+            }
           } catch (e) { log('warn', 'stall recovery process project: ' + e.message); }
         }
       }

package/package.json

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