@yemi33/minions 0.1.98 → 0.1.100

package/CHANGELOG.md

@@ -1,10 +1,21 @@
 # Changelog
 
-## 0.1.98 (2026-04-01)
+## 0.1.100 (2026-04-01)
 
 ### Engine
+- engine.js
 - engine/ado.js
+- engine/cleanup.js
+- engine/consolidation.js
+- engine/dispatch.js
 - engine/github.js
+- engine/lifecycle.js
+- engine/preflight.js
+- engine/queries.js
+- engine/shared.js
+
+### Other
+- test/unit.test.js
 
 ## 0.1.97 (2026-04-01)
 

package/engine/cleanup.js

@@ -272,6 +272,7 @@ function runCleanup(config, verbose = false) {
             return allWiIds.has(itemId);
           });
         }
+        return dp;
       });
     }
   } catch (e) { log('warn', 'prune orphaned dispatches: ' + e.message); }

package/engine/consolidation.js

@@ -179,8 +179,8 @@ function consolidateWithLLM(items, existingNotes, files, config) {
 
   proc.on('close', (code) => {
     clearTimeout(timeout);
-    safeUnlink(promptPath);
-    safeUnlink(sysPromptPath);
+    try { safeUnlink(promptPath); } catch (err) { log('warn', `Temp file cleanup failed: ${promptPath} — ${err.message}`); }
+    try { safeUnlink(sysPromptPath); } catch (err) { log('warn', `Temp file cleanup failed: ${sysPromptPath} — ${err.message}`); }
 
     const parsed = parseStreamJsonOutput(stdout);
     const extractedText = parsed.text;
@@ -231,8 +231,8 @@ function consolidateWithLLM(items, existingNotes, files, config) {
   proc.on('error', (err) => {
     clearTimeout(timeout);
     log('warn', `LLM consolidation spawn error: ${err.message} — falling back to regex`);
-    safeUnlink(promptPath);
-    safeUnlink(sysPromptPath);
+    try { safeUnlink(promptPath); } catch (unlinkErr) { log('warn', `Temp file cleanup failed: ${promptPath} — ${unlinkErr.message}`); }
+    try { safeUnlink(sysPromptPath); } catch (unlinkErr) { log('warn', `Temp file cleanup failed: ${sysPromptPath} — ${unlinkErr.message}`); }
     consolidateWithRegex(items, files);
     _clearProcessingState();
   });
@@ -296,13 +296,15 @@ function consolidateWithRegex(items, files) {
   const deduped = [];
   for (const insight of allInsights) {
     const fpWords = insight.fingerprint.split(' ').filter(w => w.length > 4).slice(0, 5);
-    if (fpWords.length >= 3 && fpWords.every(w => existingNotes.includes(w))) continue;
+    // Use word-boundary regex to avoid substring false positives (e.g. 'fix' matching 'prefix')
+    if (fpWords.length >= 3 && fpWords.every(w => new RegExp(`\\b${w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(existingNotes))) continue;
     const existing = seen.get(insight.fingerprint);
     if (existing) { if (!existing.sources.includes(insight.agent)) existing.sources.push(insight.agent); continue; }
     let isDup = false;
     for (const [fp, entry] of seen) {
-      const a = new Set(fp.split(' ')), b = new Set(insight.fingerprint.split(' '));
-      // Require at least 3 words in both fingerprints for meaningful similarity check
+      // Filter to meaningful words (>4 chars) to avoid short-word false positives like 'fix' vs 'prefix'
+      const a = new Set(fp.split(' ').filter(w => w.length > 2)), b = new Set(insight.fingerprint.split(' ').filter(w => w.length > 2));
+      // Require at least 3 meaningful words in both fingerprints for similarity check
       if (a.size >= 3 && b.size >= 3 && [...a].filter(w => b.has(w)).length / Math.max(a.size, b.size) > 0.7) {
         if (!entry.sources.includes(insight.agent)) entry.sources.push(insight.agent); isDup = true; break;
       }
@@ -352,7 +354,9 @@ function classifyToKnowledgeBase(items) {
   if (!fs.existsSync(KNOWLEDGE_DIR)) fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
 
   const categoryDirs = {};
-  for (const cat of KB_CATEGORIES) {
+  // Include 'general' as fallback category even if not in KB_CATEGORIES
+  const allCategories = KB_CATEGORIES.includes('general') ? KB_CATEGORIES : [...KB_CATEGORIES, 'general'];
+  for (const cat of allCategories) {
     categoryDirs[cat] = path.join(KNOWLEDGE_DIR, cat);
     if (!fs.existsSync(categoryDirs[cat])) fs.mkdirSync(categoryDirs[cat], { recursive: true });
   }
@@ -360,7 +364,12 @@ function classifyToKnowledgeBase(items) {
   let classified = 0;
   for (const item of items) {
     const content = item.content || '';
-    const category = classifyInboxItem(item.name, content);
+    const rawCategory = classifyInboxItem(item.name, content);
+    // Fallback to 'general' if the classified category isn't in our known category map
+    const category = categoryDirs[rawCategory] ? rawCategory : 'general';
+    if (rawCategory !== category) {
+      log('warn', `Unknown KB category '${rawCategory}' for ${item.name} — falling back to 'general'`);
+    }
 
     const agentMatch = item.name.match(/^(\w+)-/);
     const agent = agentMatch ? agentMatch[1] : 'unknown';

package/engine/dispatch.js

@@ -38,6 +38,7 @@ function addToDispatch(item) {
   item.created_at = ts();
   mutateDispatch((dispatch) => {
     dispatch.pending.push(item);
+    return dispatch;
   });
   log('info', `Queued dispatch: ${item.id} (${item.type} → ${item.agent})`);
   return item.id;
@@ -79,7 +80,7 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
       if (idx >= 0) item = dispatch.pending.splice(idx, 1)[0];
     }
 
-    if (!item) return;
+    if (!item) return dispatch;
     item.completed_at = ts();
     item.result = result;
     if (reason) item.reason = reason;
@@ -89,6 +90,7 @@ function completeDispatch(id, result = 'success', reason = '', resultSummary = '
       dispatch.completed = dispatch.completed.slice(-99);
     }
     dispatch.completed.push(item);
+    return dispatch;
   });
 
   if (item) {

package/engine/lifecycle.js

@@ -393,7 +393,12 @@ function chainPlanToPrd(dispatchItem, meta, config) {
   log('info', `Plan chaining: queuing plan-to-prd for next tick (chained from ${dispatchItem.id})`);
   const wiPath = path.join(MINIONS_DIR, 'work-items.json');
   let items = [];
-  try { items = JSON.parse(fs.readFileSync(wiPath, 'utf8')); } catch {}
+  try {
+    items = JSON.parse(fs.readFileSync(wiPath, 'utf8'));
+  } catch (err) {
+    log('warn', `Plan chaining: failed to parse ${wiPath}, falling back to empty list: ${err.message}`);
+    try { fs.copyFileSync(wiPath, wiPath + '.bak'); } catch (_) { /* backup best-effort */ }
+  }
   items.push({
     id: 'W-' + shared.uid(),
     title: `Convert plan to PRD: ${meta?.item?.title || planFile.name}`,
@@ -580,7 +585,7 @@ function syncPrsFromOutput(output, agentId, meta, config) {
       dirtyTargets.set(targetName, { prs: safeJson(prPath) || [], prPath });
     }
     const entry = dirtyTargets.get(targetName);
-    if (entry.prs.some(p => p.id === fullId || String(p.id).includes(prId))) continue;
+    if (entry.prs.some(p => p.id === fullId || String(p.id) === String(prId))) continue;
 
     let title = meta?.item?.title || '';
     const titleMatch = output.match(new RegExp(`${prId}[^\\n]*?[—–-]\\s*([^\\n]+)`, 'i'));
@@ -651,7 +656,7 @@ function updatePrAfterReview(agentId, pr, project) {
   }
 
   shared.safeWrite(project ? shared.projectPrPath(project) : path.join(path.resolve(MINIONS_DIR, '..'), '.minions', 'pull-requests.json'), prs);
-  log('info', `Updated ${pr.id} → minions review: ${minionsVerdict} by ${reviewerName}`);
+  log('info', `Updated ${pr.id} → minions review: ${target.reviewStatus} by ${reviewerName}`);
   createReviewFeedbackForAuthor(agentId, { ...pr, ...target }, config);
 }
 

package/engine/preflight.js

@@ -25,10 +25,11 @@ function findClaudeBinary() {
   // Fallback: parse the shell wrapper
   try {
     const which = execSync('bash -c "which claude"', { encoding: 'utf8', windowsHide: true, timeout: 5000 }).trim();
-    const wrapper = execSync(`bash -c "cat '${which}'"`, { encoding: 'utf8', windowsHide: true, timeout: 5000 });
+    const whichNative = which.replace(/^\/c\//, 'C:/').replace(/\//g, path.sep);
+    const wrapper = fs.readFileSync(whichNative, 'utf8');
     const m = wrapper.match(/node_modules\/@anthropic-ai\/claude-code\/cli\.js/);
     if (m) {
-      const basedir = path.dirname(which.replace(/^\/c\//, 'C:/').replace(/\//g, path.sep));
+      const basedir = path.dirname(whichNative);
       const resolved = path.join(basedir, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
       if (fs.existsSync(resolved)) return resolved;
     }

package/engine/queries.js

@@ -540,8 +540,8 @@ function getPrdInfo(config) {
       const planFiles = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
       for (const pf of planFiles) {
         try {
-          const plan = JSON.parse(fs.readFileSync(path.join(dir, pf), 'utf8'));
-          if (!plan.missing_features) continue;
+          const plan = safeJson(path.join(dir, pf));
+          if (!plan || !plan.missing_features) continue;
           const stat = fs.statSync(path.join(dir, pf));
           if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
           // Staleness: compare source plan mtime to recorded sourcePlanModifiedAt
@@ -577,13 +577,13 @@ function getPrdInfo(config) {
   for (const project of projects) {
     try {
       const workItems = safeJson(projectWorkItemsPath(project)) || [];
-      for (const wi of workItems) { if (wi.sourcePlan) wiById[wi.id] = wi; }
+      for (const wi of workItems) { if (!wi.id) { console.warn(`[queries] Skipping work item without id in ${project.name}:`, JSON.stringify(wi).slice(0, 120)); continue; } if (wi.sourcePlan) wiById[wi.id] = wi; }
     } catch { /* optional */ }
   }
   // Also check central work-items.json
   try {
     const centralWi = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-    for (const wi of centralWi) { if (wi.sourcePlan && !wiById[wi.id]) wiById[wi.id] = wi; }
+    for (const wi of centralWi) { if (!wi.id) { console.warn('[queries] Skipping central work item without id:', JSON.stringify(wi).slice(0, 120)); continue; } if (wi.sourcePlan && !wiById[wi.id]) wiById[wi.id] = wi; }
   } catch { /* optional */ }
 
   // PR-to-PRD linking — primary source is pr-links.json (single-writer, never clobbered by polling)
@@ -595,7 +595,7 @@ function getPrdInfo(config) {
   const prLinks = shared.getPrLinks(); // { "PR-xxxx": "P-xxxx" }
   for (const [prId, itemId] of Object.entries(prLinks)) {
     const pr = prById[prId];
-    const project = projects.find(p => p.name === pr?._project) || projects[0];
+    const project = projects.find(p => p.name === pr?._project) || projects[0] || null;
     const url = pr?.url || (project?.prUrlBase ? project.prUrlBase + prId.replace('PR-', '') : '');
     if (!prdToPr[itemId]) prdToPr[itemId] = [];
     prdToPr[itemId].push({ id: prId, url, title: pr?.title || '', status: pr?.status || 'active', _project: pr?._project || '' });

package/engine/shared.js

@@ -25,7 +25,7 @@ function log(level, msg, meta = {}) {
   let logData = safeJson(LOG_PATH) || [];
   if (!Array.isArray(logData)) logData = logData.entries || [];
   logData.push(entry);
-  if (logData.length > 2000) logData.splice(0, logData.length - 2000);
+  if (logData.length >= 2500) logData.splice(0, logData.length - 2000);
   safeWrite(LOG_PATH, logData);
 }
 
@@ -43,11 +43,13 @@ function safeJson(p) {
   try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
 }
 
+let _tmpCounter = 0;
+
 function safeWrite(p, data) {
   const dir = path.dirname(p);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   const content = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
-  const tmp = p + '.tmp.' + process.pid;
+  const tmp = p + '.tmp.' + process.pid + '.' + (++_tmpCounter);
   try {
     fs.writeFileSync(tmp, content);
     // Atomic rename — retry on Windows EPERM (file locking)
@@ -58,7 +60,7 @@ function safeWrite(p, data) {
       } catch (e) {
         if (e.code === 'EPERM' && attempt < 4) {
           const delay = 50 * (attempt + 1); // 50, 100, 150, 200ms
-          try { const ab = new SharedArrayBuffer(4); Atomics.wait(new Int32Array(ab), 0, 0, delay); } catch { /* fallback busy-wait */ const start = Date.now(); while (Date.now() - start < delay) {} }
+          sleepMs(delay);
           continue;
         }
         // Final attempt failed — throw to let caller retry
@@ -85,11 +87,13 @@ function sleepMs(ms) {
     const ab = new SharedArrayBuffer(4);
     Atomics.wait(new Int32Array(ab), 0, 0, ms);
   } catch {
-    const start = Date.now();
-    while (Date.now() - start < ms) {}
+    // Fallback: synchronous sleep via child process — avoids busy-wait blocking the event loop
+    _spawnSync(process.execPath, ['-e', `setTimeout(()=>{},${Math.max(0, Math.floor(ms))})`], { windowsHide: true });
   }
 }
 
+const LOCK_STALE_MS = 60000; // 60 seconds — force-remove locks older than this
+
 function withFileLock(lockPath, fn, {
   timeoutMs = 5000,
   retryDelayMs = 25
@@ -104,6 +108,14 @@ function withFileLock(lockPath, fn, {
       break;
     } catch (err) {
       if (err.code !== 'EEXIST') throw err;
+      // Check for stale lock — if lock file is older than LOCK_STALE_MS, force-remove it
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+          try { fs.unlinkSync(lockPath); } catch { /* race: another process removed it */ }
+          continue; // retry immediately after removing stale lock
+        }
+      } catch { /* lock file disappeared between EEXIST and stat — retry will succeed */ }
       sleepMs(retryDelayMs);
     }
   }
@@ -372,6 +384,23 @@ function getAdoOrgBase(project) {
     : `https://dev.azure.com/${project.adoOrg}`;
 }
 
+// ── Path Sanitization ───────────────────────────────────────────────────────
+
+/**
+ * Resolve a user-supplied path relative to a base directory and verify the
+ * result stays within the base. Throws if the resolved path escapes baseDir.
+ * Use to prevent path-traversal attacks on any user-facing file endpoint.
+ */
+function sanitizePath(baseDir, userInput) {
+  const resolvedBase = path.resolve(baseDir);
+  const resolvedFull = path.resolve(resolvedBase, userInput);
+  // Append path.sep so "/foo" doesn't match "/foobar"
+  if (!resolvedFull.startsWith(resolvedBase + path.sep) && resolvedFull !== resolvedBase) {
+    throw new Error(`Path traversal blocked: ${userInput} resolves outside ${baseDir}`);
+  }
+  return resolvedFull;
+}
+
 // ── Branch Sanitization ──────────────────────────────────────────────────────
 
 function sanitizeBranch(name) {
@@ -452,7 +481,10 @@ module.exports = {
   addPrLink,
   nextWorkItemId,
   getAdoOrgBase,
+  sanitizePath,
   sanitizeBranch,
   parseSkillFrontmatter,
+  sleepMs,
+  LOCK_STALE_MS,
 };
 

package/engine.js

@@ -708,13 +708,14 @@ function spawnAgent(dispatchItem, config) {
   // Move pending -> active under a lock to avoid cross-process lost updates (engine/dashboard)
   mutateDispatch((dispatch) => {
     const idx = dispatch.pending.findIndex(d => d.id === id);
-    if (idx < 0) return;
+    if (idx < 0) return dispatch;
     const item = dispatch.pending.splice(idx, 1)[0];
     item.started_at = startedAt;
     delete item.skipReason;
     if (!dispatch.active.some(d => d.id === id)) {
       dispatch.active.push(item);
     }
+    return dispatch;
   });
 
   return proc;
@@ -1382,9 +1383,8 @@ function discoverFromWorkItems(config, project) {
     // This protects against persisted state drift from old runtime versions.
     try {
       mutateDispatch((dp) => {
-        const before = Array.isArray(dp.completed) ? dp.completed.length : 0;
         dp.completed = Array.isArray(dp.completed) ? dp.completed.filter(d => d.meta?.dispatchKey !== key) : [];
-        return dp.completed.length !== before ? dp : undefined;
+        return dp;
       });
       dispatchCooldowns.delete(key);
     } catch (e) { log('warn', 'self-heal dispatch state: ' + e.message); }
@@ -1973,19 +1973,29 @@ function discoverWork(config) {
 
   // Periodic plan completion sweep — catch PRDs that completed while engine was down
   // or where checkPlanCompletion missed the completion event
-  try {
-    const lifecycle = require('./engine/lifecycle');
-    const prdDir = path.join(MINIONS_DIR, 'prd');
-    if (fs.existsSync(prdDir)) {
-      for (const f of fs.readdirSync(prdDir).filter(f => f.endsWith('.json'))) {
-        const plan = safeJson(path.join(prdDir, f));
-        if (!plan?.missing_features || plan.status === 'completed') continue;
-        if (plan.status !== 'approved' && plan.status !== 'active') continue;
-        // Simulate the meta object checkPlanCompletion expects
-        lifecycle.checkPlanCompletion({ item: { sourcePlan: f } }, config);
+  // Throttled to every 10 ticks (~5 min) to reduce call volume (P3 decision)
+  if (tickCount % 10 === 0) {
+    try {
+      const lifecycle = require('./engine/lifecycle');
+      const prdDir = path.join(MINIONS_DIR, 'prd');
+      if (fs.existsSync(prdDir)) {
+        for (const f of fs.readdirSync(prdDir).filter(f => f.endsWith('.json'))) {
+          if (completedPlanCache.has(f)) continue;
+          const plan = safeJson(path.join(prdDir, f));
+          if (!plan?.missing_features || plan.status === 'completed') {
+            if (plan?.status === 'completed') completedPlanCache.add(f);
+            continue;
+          }
+          if (plan.status !== 'approved' && plan.status !== 'active') continue;
+          // Simulate the meta object checkPlanCompletion expects
+          lifecycle.checkPlanCompletion({ item: { sourcePlan: f } }, config);
+          // If plan transitioned to completed, cache it
+          const after = safeJson(path.join(prdDir, f));
+          if (after?.status === 'completed') completedPlanCache.add(f);
+        }
       }
-    }
-  } catch (e) { log('warn', 'plan completion sweep: ' + e.message); }
+    } catch (e) { log('warn', 'plan completion sweep: ' + e.message); }
+  }
 
   // Gate reviews and fixes: do not dispatch until all implement items are complete
   const hasIncompleteImplements = projects.some(project => {
@@ -2023,6 +2033,10 @@ function discoverWork(config) {
 
 let tickCount = 0;
 
+// In-memory cache of plan filenames confirmed completed — avoids redundant
+// checkPlanCompletion calls.  Cleared automatically on engine restart.
+const completedPlanCache = new Set();
+
 let tickRunning = false;
 
 async function tick() {
@@ -2086,9 +2100,15 @@ async function tickInner() {
     try {
       const prdFiles = safeReadDir(PRD_DIR).filter(f => f.endsWith('.json'));
       for (const file of prdFiles) {
+        if (completedPlanCache.has(file)) continue;
         const plan = safeJson(path.join(PRD_DIR, file));
         if (plan && plan.missing_features && plan.status !== 'completed') {
           checkPlanCompletion({ item: { sourcePlan: file } }, config);
+          // If plan transitioned to completed, cache it
+          const after = safeJson(path.join(PRD_DIR, file));
+          if (after?.status === 'completed') completedPlanCache.add(file);
+        } else if (plan?.status === 'completed') {
+          completedPlanCache.add(file);
         }
       }
     } catch (err) { log('warn', `Plan completion check error: ${err?.message || err}`); }
@@ -2146,9 +2166,8 @@ async function tickInner() {
                 try {
                     const key = `work-${project.name}-${item.id}`;
                     mutateDispatch((dp) => {
-                      const before = dp.completed.length;
                       dp.completed = dp.completed.filter(d => d.meta?.dispatchKey !== key);
-                      if (dp.completed.length !== before) return dp;
+                      return dp;
                     });
                   } catch (e) { log('warn', 'stall recovery clear dispatch: ' + e.message); }
 
@@ -2182,6 +2201,7 @@ async function tickInner() {
                       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); }
                   }
@@ -2226,6 +2246,7 @@ async function tickInner() {
   mutateDispatch((dp) => {
     dp.pending = dispatch.pending;
     dp.active = dispatch.active || dp.active;
+    return dp;
   });
 
   // Only dispatch to agents that aren't already busy (one task per agent at a time).
@@ -2244,8 +2265,39 @@ async function tickInner() {
   const dispatched = new Set();
   for (const item of toDispatch) {
     if (!dispatched.has(item.id)) {
-      spawnAgent(item, config);
-      dispatched.add(item.id);
+      const proc = spawnAgent(item, config);
+      if (proc === null) {
+        // spawnAgent failed (e.g., worktree creation error). It already called
+        // completeDispatch internally which handles retry logic, but log at the
+        // dispatch-loop level for visibility and handle any edge cases where
+        // completeDispatch wasn't called.
+        log('error', `spawnAgent returned null for ${item.id} (${item.type} → ${item.agent}) — spawn failed`);
+        // Defensive: ensure the work item is re-queued if completeDispatch didn't fire
+        if (item.meta?.item?.id) {
+          try {
+            const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
+              ? path.join(ENGINE_DIR, '..', 'work-items.json')
+              : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
+            if (wiPath) {
+              const items = safeJson(wiPath) || [];
+              const wi = items.find(i => i.id === item.meta.item.id);
+              if (wi && wi.status === 'dispatched') {
+                // completeDispatch didn't update the work item — re-queue manually
+                wi.status = 'pending';
+                wi._retryCount = (wi._retryCount || 0) + 1;
+                wi._lastRetryReason = 'spawnAgent returned null';
+                wi._lastRetryAt = ts();
+                delete wi.dispatched_at;
+                delete wi.dispatched_to;
+                safeWrite(wiPath, items);
+                log('info', `Re-queued ${item.meta.item.id} as pending (retry ${wi._retryCount})`);
+              }
+            }
+          } catch (e) { log('warn', `Failed to re-queue work item after spawn failure: ${e.message}`); }
+        }
+      } else {
+        dispatched.add(item.id);
+      }
     }
   }
 
@@ -2268,7 +2320,7 @@ async function tickInner() {
     }
   }
   if (skipReasonChanged) {
-    mutateDispatch((dp) => { dp.pending = postDispatch.pending; });
+    mutateDispatch((dp) => { dp.pending = postDispatch.pending; return dp; });
   }
 }
 

package/package.json

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