@yemi33/minions 0.1.100 → 0.1.102

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## 0.1.100 (2026-04-01)
+## 0.1.102 (2026-04-01)
+
+### Engine
+- engine/scheduler.js
+
+### Other
+- test/unit.test.js
+
+## 0.1.101 (2026-04-01)
 
 ### Engine
 - engine.js
@@ -14,6 +22,9 @@
 - 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/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+)-/);
@@ -412,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/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/scheduler.js

@@ -61,11 +61,11 @@ function parseCronField(field, min, max) {
 function parseCronExpr(expr) {
   if (!expr || typeof expr !== 'string') return null;
   const parts = expr.trim().split(/\s+/);
-  if (parts.length < 2 || parts.length > 3) return null;
+  if (parts.length !== 3) return null;
 
   const minuteMatcher = parseCronField(parts[0], 0, 59);
   const hourMatcher = parseCronField(parts[1], 0, 23);
-  const dowMatcher = parts[2] ? parseCronField(parts[2], 0, 6) : () => true;
+  const dowMatcher = parseCronField(parts[2], 0, 6);
 
   return {
     matches(date) {

package/engine/shared.js

@@ -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/package.json

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