@yemi33/minions 0.1.99 → 0.1.100

package/CHANGELOG.md

@@ -1,12 +1,17 @@
 # Changelog
 
-## 0.1.99 (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

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/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);
 }
 

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.99",
+  "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"