@yemi33/minions 0.1.99 → 0.1.101

package/CHANGELOG.md

@@ -1,14 +1,22 @@
 # Changelog
 
-## 0.1.99 (2026-04-01)
+## 0.1.101 (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
 
+### Dashboard
+- dashboard.js
+
 ### Other
 - test/unit.test.js
 

package/dashboard.js

@@ -34,14 +34,19 @@ function reloadConfig() {
 const PLANS_DIR = path.join(MINIONS_DIR, 'plans');
 
 // Resolve a plan/PRD file path: .json files live in prd/, .md files in plans/
+// Validates that the file stays within the expected directory to prevent path traversal.
 function resolvePlanPath(file) {
   if (file.endsWith('.json')) {
+    // Validate against both prd/ and prd/archive/
+    shared.sanitizePath(file, PRD_DIR);
     const active = path.join(PRD_DIR, file);
     if (fs.existsSync(active)) return active;
     const archived = path.join(PRD_DIR, 'archive', file);
     if (fs.existsSync(archived)) return archived;
     return active;
   }
+  // Validate against both plans/ and plans/archive/
+  shared.sanitizePath(file, PLANS_DIR);
   const active = path.join(PLANS_DIR, file);
   if (fs.existsSync(active)) return active;
   const archived = path.join(PLANS_DIR, 'archive', file);
@@ -743,12 +748,13 @@ function spawnEngine() {
 }
 
 function killEnginePid(pid) {
-  const { execSync } = require('child_process');
+  const { execFileSync } = require('child_process');
   try {
+    const safePid = shared.validatePid(pid);
     if (process.platform === 'win32') {
-      execSync(`taskkill /PID ${pid} /F /T`, { stdio: 'pipe', timeout: 5000 });
+      execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000 });
     } else {
-      process.kill(pid, 'SIGKILL');
+      process.kill(safePid, 'SIGKILL');
     }
   } catch { /* process may be dead */ }
 }
@@ -783,6 +789,7 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
+      shared.sanitizePath(body.file, PRD_DIR);
 
       // Find the PRD — check active and archive
       const prdDir = path.join(MINIONS_DIR, 'prd');
@@ -1255,11 +1262,14 @@ const server = http.createServer(async (req, res) => {
         try {
           const status = JSON.parse(safeRead(statusPath) || '{}');
           if (status.pid) {
-            if (process.platform === 'win32') {
-              try { require('child_process').execSync('taskkill /PID ' + status.pid + ' /F /T', { stdio: 'pipe', timeout: 5000 }); } catch { /* process may be dead */ }
-            } else {
-              try { process.kill(status.pid, 'SIGTERM'); } catch { /* process may be dead */ }
-            }
+            try {
+              const safePid = shared.validatePid(status.pid);
+              if (process.platform === 'win32') {
+                require('child_process').execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000 });
+              } else {
+                process.kill(safePid, 'SIGTERM');
+              }
+            } catch { /* process may be dead or invalid PID */ }
           }
           status.status = 'idle';
           delete status.currentTask;
@@ -1418,10 +1428,9 @@ const server = http.createServer(async (req, res) => {
     const cat = match[1];
     const file = decodeURIComponent(match[2]);
     // Prevent path traversal
-    if (file.includes('..') || file.includes('\0') || file.includes('/') || file.includes('\\')) {
-      return jsonReply(res, 400, { error: 'invalid file name' });
-    }
-    const content = safeRead(path.join(MINIONS_DIR, 'knowledge', cat, file));
+    const kbCatDir = path.join(MINIONS_DIR, 'knowledge', cat);
+    try { shared.sanitizePath(file, kbCatDir); } catch { return jsonReply(res, 400, { error: 'invalid file name' }); }
+    const content = safeRead(path.join(kbCatDir, file));
     if (content === null) return jsonReply(res, 404, { error: 'not found' });
     res.setHeader('Content-Type', 'text/plain; charset=utf-8');
     res.setHeader('Access-Control-Allow-Origin', '*');
@@ -1853,11 +1862,14 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
                 try {
                   const agentStatus = JSON.parse(safeRead(statusPath) || '{}');
                   if (agentStatus.pid) {
-                    if (process.platform === 'win32') {
-                      try { require('child_process').execSync('taskkill /PID ' + agentStatus.pid + ' /F /T', { stdio: 'pipe', timeout: 5000 }); } catch { /* process may be dead */ }
-                    } else {
-                      try { process.kill(agentStatus.pid, 'SIGTERM'); } catch { /* process may be dead */ }
-                    }
+                    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 });
+                      } else {
+                        process.kill(safePid, 'SIGTERM');
+                      }
+                    } catch { /* process may be dead or invalid PID */ }
                   }
                   agentStatus.status = 'idle';
                   delete agentStatus.currentTask;
@@ -1906,7 +1918,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file is required' });
-      if (body.file.includes('..') || body.file.includes('\0')) return jsonReply(res, 400, { error: 'invalid file path' });
+      shared.sanitizePath(body.file, PRD_DIR);
 
       const prdPath = path.join(PRD_DIR, body.file);
       const plan = safeJson(prdPath);
@@ -1975,6 +1987,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       if (!body.file.endsWith('.md')) return jsonReply(res, 400, { error: 'only .md plans can be executed' });
+      shared.sanitizePath(body.file, PLANS_DIR);
       const planPath = path.join(MINIONS_DIR, 'plans', body.file);
       if (!fs.existsSync(planPath)) return jsonReply(res, 404, { error: 'plan file not found' });
 
@@ -2081,9 +2094,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
-      if (body.file.includes('..') || body.file.includes('\0') || body.file.includes('/') || body.file.includes('\\')) {
-        return jsonReply(res, 400, { error: 'invalid filename' });
-      }
+      shared.sanitizePath(body.file, body.file.endsWith('.json') ? PRD_DIR : PLANS_DIR);
       const planPath = resolvePlanPath(body.file);
       if (!fs.existsSync(planPath)) return jsonReply(res, 404, { error: 'plan not found' });
       // Read PRD content before deleting to get source_plan for cleanup
@@ -2143,9 +2154,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
-      if (body.file.includes('..') || body.file.includes('\0') || body.file.includes('/') || body.file.includes('\\')) {
-        return jsonReply(res, 400, { error: 'invalid filename' });
-      }
+      shared.sanitizePath(body.file, body.file.endsWith('.json') ? PRD_DIR : PLANS_DIR);
       const planPath = resolvePlanPath(body.file);
       if (!fs.existsSync(planPath)) return jsonReply(res, 404, { error: 'plan not found' });
 
@@ -2493,8 +2502,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       let currentContent = body.document;
       let fullPath = null;
       if (canEdit) {
+        try { shared.sanitizePath(body.filePath, MINIONS_DIR); } catch { return jsonReply(res, 400, { error: 'path must be under minions directory' }); }
         fullPath = path.resolve(MINIONS_DIR, body.filePath);
-        if (!fullPath.startsWith(path.resolve(MINIONS_DIR))) return jsonReply(res, 400, { error: 'path must be under minions directory' });
         const diskContent = safeRead(fullPath);
         if (diskContent !== null) currentContent = diskContent;
       }
@@ -2554,11 +2563,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
                           try {
                             const agentStatus = JSON.parse(safeRead(statusPath) || '{}');
                             if (agentStatus.pid) {
-                              if (process.platform === 'win32') {
-                                try { require('child_process').execSync('taskkill /PID ' + agentStatus.pid + ' /F /T', { stdio: 'pipe', timeout: 5000 }); } catch { /* process may be dead */ }
-                              } else {
-                                try { process.kill(agentStatus.pid, 'SIGTERM'); } catch { /* process may be dead */ }
-                              }
+                              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 });
+                                } else {
+                                  process.kill(safePid, 'SIGTERM');
+                                }
+                              } catch { /* process may be dead or invalid PID */ }
                             }
                             agentStatus.status = 'idle';
                             delete agentStatus.currentTask;
@@ -2607,7 +2619,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const body = await readBody(req);
       const { name } = body;
       if (!name) return jsonReply(res, 400, { error: 'name required' });
-      if (name.includes('..') || name.includes('\0')) return jsonReply(res, 400, { error: 'Invalid file name' });
+      shared.sanitizePath(name, path.join(MINIONS_DIR, 'notes', 'inbox'));
 
       const inboxPath = path.join(MINIONS_DIR, 'notes', 'inbox', name);
       const content = safeRead(inboxPath);

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

@@ -6,6 +6,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const shared = require('./shared');
 const { safeRead, safeWrite, safeUnlink, runFile, cleanChildEnv,
   parseStreamJsonOutput, classifyInboxItem, KB_CATEGORIES, log, dateStamp } = shared;
@@ -116,6 +117,23 @@ function consolidateWithLLM(items, existingNotes, files, config) {
   _consolidationStartedAt = Date.now();
   for (const f of files) _processingFiles.add(f);
 
+  // ─── Content-hash circuit breaker: skip LLM if >80% items are near-duplicates
+  const dupCheck = checkDuplicateHash(items);
+  if (dupCheck.isDuplicate) {
+    log('info', `Skipped LLM consolidation: ${dupCheck.count}/${dupCheck.total} items are duplicates (hash: ${dupCheck.hash.slice(0, 8)})`);
+    // Archive duplicate files directly
+    if (!fs.existsSync(ARCHIVE_DIR)) fs.mkdirSync(ARCHIVE_DIR, { recursive: true });
+    for (const f of files) {
+      try {
+        fs.renameSync(path.join(INBOX_DIR, f), shared.uniquePath(path.join(ARCHIVE_DIR, `${dateStamp()}-${f}`)));
+      } catch (err) { log('warn', `Inbox archive (dup skip): ${err.message}`); }
+    }
+    for (const f of files) _processingFiles.delete(f);
+    _consolidationInFlight = false;
+    _consolidationStartedAt = 0;
+    return;
+  }
+
   const kbPaths = items.map(item => {
     const cat = classifyInboxItem(item.name, item.content);
     const agentMatch = item.name.match(/^(\w+)-/);
@@ -179,8 +197,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 +249,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 +314,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 +372,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 +382,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';
@@ -403,8 +430,30 @@ function archiveInboxFiles(files) {
   }
 }
 
+/**
+ * Check if >80% of items share the same content hash (first 200 chars + length).
+ * Returns { isDuplicate, hash, count, total } or { isDuplicate: false }.
+ * Exported for testing.
+ */
+function checkDuplicateHash(items) {
+  if (!items || items.length === 0) return { isDuplicate: false };
+  const hashCounts = new Map();
+  for (const item of items) {
+    const content = item.content || '';
+    const hash = crypto.createHash('sha256').update(content.slice(0, 200) + ':' + content.length).digest('hex');
+    hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
+  }
+  for (const [hash, count] of hashCounts) {
+    if (count / items.length > 0.8) {
+      return { isDuplicate: true, hash, count, total: items.length };
+    }
+  }
+  return { isDuplicate: false };
+}
+
 module.exports = {
   consolidateInbox,
   classifyToKnowledgeBase,
+  checkDuplicateHash,
 };
 

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

@@ -6,8 +6,8 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeRead, safeJson, safeWrite, execSilent, projectPrPath, getPrLinks, addPrLink,
-  log, ts, dateStamp } = shared;
+const { safeRead, safeJson, safeWrite, safeReadDir, execSilent, projectPrPath, getPrLinks, addPrLink,
+  mutateJsonFileLocked, log, ts, dateStamp } = shared;
 const { trackEngineUsage } = require('./llm');
 const queries = require('./queries');
 const { getConfig, getInboxFiles, getNotes, getPrs, getDispatch,
@@ -21,7 +21,12 @@ function checkPlanCompletion(meta, config) {
   const planPath = path.join(PRD_DIR, planFile);
   const plan = safeJson(planPath);
   if (!plan?.missing_features) return;
-  if (plan.status === 'completed') return;
+  if (plan.status === 'completed') {
+    // Idempotency guard: if we already sent the completion notification, skip entirely.
+    // If _completionNotified is NOT set, fall through — crash recovery path:
+    // engine crashed after setting status=completed but before creating verify/PR items.
+    if (plan._completionNotified) return;
+  }
 
   const projects = shared.getProjects(config);
 
@@ -132,10 +137,26 @@ function checkPlanCompletion(meta, config) {
     ...uniquePrs.map(pr => `- ${pr.id}: ${pr.title || ''} ${pr.url || ''}`),
   ].filter(Boolean).join('\n');
 
-  // Write summary to notes/inbox
-  const summaryFile = `prd-completion-${planFile.replace('.json', '')}-${ts().slice(0, 10)}.md`;
-  shared.safeWrite(shared.uniquePath(path.join(MINIONS_DIR, 'notes', 'inbox', summaryFile)), summary);
-  log('info', `PRD completion summary written to notes/inbox/${summaryFile}`);
+  // Write summary to notes/inbox (slug+date dedup — same pattern as writeInboxAlert in dispatch.js)
+  const summarySlug = `prd-completion-${planFile.replace('.json', '')}`;
+  const summaryFile = `${summarySlug}-${dateStamp()}.md`;
+  const inboxDir = path.join(MINIONS_DIR, 'notes', 'inbox');
+  const existing = safeReadDir(inboxDir).find(f => f.startsWith(`${summarySlug}-${dateStamp()}`));
+  if (!existing) {
+    shared.safeWrite(path.join(inboxDir, summaryFile), summary);
+    log('info', `PRD completion summary written to notes/inbox/${summaryFile}`);
+  } else {
+    log('info', `PRD completion summary already exists for today: ${existing}, skipping inbox write`);
+  }
+
+  // Persist _completionNotified flag atomically BEFORE creating work items.
+  // This prevents duplicate inbox notes on re-entry. Work item creation below has its own
+  // existingPrItem/existingVerify guards, so the flag does NOT block crash recovery of those.
+  plan._completionNotified = true;
+  mutateJsonFileLocked(planPath, (data) => {
+    data._completionNotified = true;
+    return data;
+  });
 
   // Resolve the primary project for writing new work items (PR, verify)
   const projectName = plan.project;

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);
 }
 
@@ -387,18 +387,37 @@ function getAdoOrgBase(project) {
 // ── 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.
+ * Validate that a user-supplied filename stays within the given base directory.
+ * Rejects path traversal (../, encoded variants), null bytes, and absolute paths.
+ * Returns the resolved absolute path or throws with a descriptive message.
  */
-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}`);
+function sanitizePath(file, baseDir) {
+  if (!file || typeof file !== 'string') throw new Error('file parameter is required');
+  // Reject null bytes
+  if (file.includes('\0')) throw new Error('invalid file path: null byte');
+  // Reject obvious traversal patterns (including URL-encoded variants)
+  const decoded = decodeURIComponent(file);
+  if (decoded.includes('..') || file.includes('..')) throw new Error('invalid file path: directory traversal');
+  // Reject absolute paths (Unix and Windows)
+  if (path.isAbsolute(file) || /^[a-zA-Z]:/.test(file)) throw new Error('invalid file path: absolute path not allowed');
+  const resolved = path.resolve(baseDir, file);
+  const normalizedBase = path.resolve(baseDir);
+  if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
+    throw new Error('invalid file path: outside allowed directory');
   }
-  return resolvedFull;
+  return resolved;
+}
+
+/**
+ * Validate that a PID value is a positive integer. Returns the numeric PID.
+ * Throws if the value could be used for command injection.
+ */
+function validatePid(pid) {
+  const s = String(pid);
+  if (!/^\d+$/.test(s)) throw new Error('Invalid PID: must be numeric');
+  const n = parseInt(s, 10);
+  if (n <= 0 || !Number.isFinite(n)) throw new Error('Invalid PID: must be a positive integer');
+  return n;
 }
 
 // ── Branch Sanitization ──────────────────────────────────────────────────────
@@ -483,6 +502,7 @@ module.exports = {
   getAdoOrgBase,
   sanitizePath,
   sanitizeBranch,
+  validatePid,
   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.99",
+  "version": "0.1.101",
   "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"