@yemi33/minions 0.1.292 → 0.1.294

package/CHANGELOG.md

@@ -1,12 +1,15 @@
 # Changelog
 
-## 0.1.292 (2026-04-03)
+## 0.1.294 (2026-04-03)
 
 ### Features
+- fix dashboard.js race conditions, input validation, and watcher leaks
+- fix cleanup.js — worktree TOCTOU, readdirSync isolation, KB restore verify
 - harden shared.js — backup verification, lock TOCTOU, docs
 -  all doc-chats use Sonnet with full tools (agent change)
 
 ### Fixes
+-  address review feedback on PR-122
 -  add behavioral tests for CRITICAL propagation and stale lock ENOENT
 -  CRITICAL errors in safeJson now propagate to callers
 -  defer plan archiving until verify completes, add 20 verify tests

package/dashboard.js

@@ -1172,28 +1172,25 @@ const server = http.createServer(async (req, res) => {
       if (!body.source || !body.itemId) return jsonReply(res, 400, { error: 'source and itemId required' });
       const planPath = resolvePlanPath(body.source);
       if (!fs.existsSync(planPath)) return jsonReply(res, 404, { error: 'plan file not found' });
-      const plan = safeJson(planPath);
-      const item = (plan.missing_features || []).find(f => f.id === body.itemId);
-      if (!item) return jsonReply(res, 404, { error: 'item not found in plan' });
-
-      // Update allowed fields
-      if (body.name !== undefined) item.name = body.name;
-      if (body.description !== undefined) item.description = body.description;
-      if (body.priority !== undefined) item.priority = body.priority;
-      if (body.estimated_complexity !== undefined) item.estimated_complexity = body.estimated_complexity;
-      if (body.status !== undefined) item.status = body.status;
-
-      // Re-read plan before writing to minimize race window with engine
-      const freshPlan = safeJson(planPath) || plan;
-      const freshItem = (freshPlan.missing_features || []).find(f => f.id === body.itemId);
-      if (freshItem) {
-        if (body.name !== undefined) freshItem.name = body.name;
-        if (body.description !== undefined) freshItem.description = body.description;
-        if (body.priority !== undefined) freshItem.priority = body.priority;
-        if (body.estimated_complexity !== undefined) freshItem.estimated_complexity = body.estimated_complexity;
-        if (body.status !== undefined) freshItem.status = body.status;
-      }
-      safeWrite(planPath, freshPlan);
+      // Pre-check: verify item exists before taking the lock
+      const preCheck = safeJson(planPath);
+      const preItem = (preCheck.missing_features || []).find(f => f.id === body.itemId);
+      if (!preItem) return jsonReply(res, 404, { error: 'item not found in plan' });
+
+      // Atomically read-modify-write under file lock
+      let item;
+      mutateJsonFileLocked(planPath, (plan) => {
+        const target = (plan.missing_features || []).find(f => f.id === body.itemId);
+        if (target) {
+          if (body.name !== undefined) target.name = body.name;
+          if (body.description !== undefined) target.description = body.description;
+          if (body.priority !== undefined) target.priority = body.priority;
+          if (body.estimated_complexity !== undefined) target.estimated_complexity = body.estimated_complexity;
+          if (body.status !== undefined) target.status = body.status;
+          item = target;
+        }
+        return plan;
+      }, { defaultValue: preCheck });
 
       // Feature 3: Sync edits to materialized work item if still pending
       let workItemSynced = false;
@@ -1365,24 +1362,31 @@ const server = http.createServer(async (req, res) => {
 
     fs.watchFile(liveLogPath, { interval: 500 }, watcher);
 
+    // Cleanup helper to prevent handle leaks
+    const cleanup = () => {
+      try { clearInterval(doneCheck); } catch { /* optional */ }
+      try { fs.unwatchFile(liveLogPath, watcher); } catch { /* optional */ }
+    };
+
     // Check if agent is still active (poll every 5s)
     const doneCheck = setInterval(() => {
-      const dispatch = getDispatchQueue();
-      const isActive = (dispatch.active || []).some(d => d.agent === agentId);
-      if (!isActive) {
-        watcher(); // flush final content
-        res.write(`event: done\ndata: complete\n\n`);
-        clearInterval(doneCheck);
-        fs.unwatchFile(liveLogPath, watcher);
-        res.end();
+      try {
+        const dispatch = getDispatchQueue();
+        const isActive = (dispatch.active || []).some(d => d.agent === agentId);
+        if (!isActive) {
+          watcher(); // flush final content
+          res.write(`event: done\ndata: complete\n\n`);
+          cleanup();
+          res.end();
+        }
+      } catch (e) {
+        cleanup();
+        try { res.end(); } catch { /* optional */ }
       }
     }, 5000);
 
     // Cleanup on client disconnect
-    req.on('close', () => {
-      clearInterval(doneCheck);
-      fs.unwatchFile(liveLogPath, watcher);
-    });
+    req.on('close', cleanup);
 
     return;
   }
@@ -1398,7 +1402,9 @@ const server = http.createServer(async (req, res) => {
     } else {
       // Return last N bytes via ?tail=N param (default last 8KB)
       const params = new URL(req.url, 'http://localhost').searchParams;
-      const tailBytes = parseInt(params.get('tail')) || 8192;
+      const rawTail = parseInt(params.get('tail'));
+      if (params.has('tail') && isNaN(rawTail)) return jsonReply(res, 400, { error: 'tail must be a number' });
+      const tailBytes = isNaN(rawTail) ? 8192 : Math.max(1, Math.min(10000, rawTail));
       res.end(content.length > tailBytes ? content.slice(-tailBytes) : content);
     }
     return;
@@ -1425,7 +1431,7 @@ const server = http.createServer(async (req, res) => {
   async function handleNotesSave(req, res) {
     try {
       const body = await readBody(req);
-      if (!body.content && body.content !== '') return jsonReply(res, 400, { error: 'content required' });
+      if (body.content == null) return jsonReply(res, 400, { error: 'content required' });
       const file = body.file || 'notes.md';
       // Only allow saving notes.md (prevent arbitrary file writes)
       if (file !== 'notes.md') return jsonReply(res, 400, { error: 'only notes.md can be edited' });
@@ -1819,74 +1825,72 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
         wiPaths.push(shared.projectWorkItemsPath(proj));
       }
       const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
-      const dispatch = JSON.parse(safeRead(dispatchPath) || '{}');
       const killedAgents = new Set();
       const resetItemIds = new Set();
 
-      for (const wiPath of wiPaths) {
-        try {
-          const items = safeJson(wiPath);
-          if (!items) continue;
-          let changed = false;
-          for (const w of items) {
-            if (w.sourcePlan !== body.file) continue;
-            // Keep completed items as-is, reset everything else to pending.
-            if (w.status === 'done' || w.status === 'implemented' || w.status === 'complete' || w.status === 'in-pr') continue;
-
-            if (w.status === 'dispatched') {
-              // Kill the agent working on this item, if any.
-              const activeEntry = (dispatch.active || []).find(d => d.meta?.item?.id === w.id || d.meta?.dispatchKey?.includes(w.id));
-              if (activeEntry) {
-                const statusPath = path.join(MINIONS_DIR, 'agents', activeEntry.agent, 'status.json');
-                try {
-                  const agentStatus = JSON.parse(safeRead(statusPath) || '{}');
-                  if (agentStatus.pid) {
-                    try {
-                      const safePid = shared.validatePid(agentStatus.pid);
-                      if (process.platform === 'win32') {
-                        require('child_process').execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
-                      } else {
-                        process.kill(safePid, 'SIGTERM');
-                      }
-                    } catch { /* process may be dead or invalid PID */ }
-                  }
-                  agentStatus.status = 'idle';
-                  delete agentStatus.currentTask;
-                  delete agentStatus.dispatched;
-                  safeWrite(statusPath, agentStatus);
-                } catch (e) { console.error('agent reset:', e.message); }
-                killedAgents.add(activeEntry.agent);
+      // Read dispatch inside the lock so PID list is consistent with state being modified
+      mutateJsonFileLocked(dispatchPath, (dispatch) => {
+        for (const wiPath of wiPaths) {
+          try {
+            const items = safeJson(wiPath);
+            if (!items) continue;
+            let changed = false;
+            for (const w of items) {
+              if (w.sourcePlan !== body.file) continue;
+              // Keep completed items as-is, reset everything else to pending.
+              if (w.status === 'done' || w.status === 'implemented' || w.status === 'complete' || w.status === 'in-pr') continue;
+
+              if (w.status === 'dispatched') {
+                // Kill the agent working on this item, if any.
+                const activeEntry = (dispatch.active || []).find(d => d.meta?.item?.id === w.id || d.meta?.dispatchKey?.includes(w.id));
+                if (activeEntry) {
+                  const statusPath = path.join(MINIONS_DIR, 'agents', activeEntry.agent, 'status.json');
+                  try {
+                    const agentStatus = JSON.parse(safeRead(statusPath) || '{}');
+                    if (agentStatus.pid) {
+                      try {
+                        const safePid = shared.validatePid(agentStatus.pid);
+                        if (process.platform === 'win32') {
+                          require('child_process').execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
+                        } else {
+                          process.kill(safePid, 'SIGTERM');
+                        }
+                      } catch { /* process may be dead or invalid PID */ }
+                    }
+                    agentStatus.status = 'idle';
+                    delete agentStatus.currentTask;
+                    delete agentStatus.dispatched;
+                    safeWrite(statusPath, agentStatus);
+                  } catch (e) { console.error('agent reset:', e.message); }
+                  killedAgents.add(activeEntry.agent);
+                }
               }
-            }
 
-            if (w.status !== 'pending') reset++;
-            w.status = 'pending';
-            delete w._pausedBy;
-            delete w._resumedAt;
-            delete w.dispatched_at;
-            delete w.dispatched_to;
-            delete w.failReason;
-            delete w.failedAt;
-            changed = true;
-            if (w.id) resetItemIds.add(w.id);
-          }
-          if (changed) safeWrite(wiPath, items);
-        } catch (e) { console.error('reset work items:', e.message); }
-      }
+              if (w.status !== 'pending') reset++;
+              w.status = 'pending';
+              delete w._pausedBy;
+              delete w._resumedAt;
+              delete w.dispatched_at;
+              delete w.dispatched_to;
+              delete w.failReason;
+              delete w.failedAt;
+              changed = true;
+              if (w.id) resetItemIds.add(w.id);
+            }
+            if (changed) safeWrite(wiPath, items);
+          } catch (e) { console.error('reset work items:', e.message); }
+        }
 
-      // Remove dispatch active entries for reset items or killed agents.
-      if (resetItemIds.size > 0 || killedAgents.size > 0) {
-        mutateJsonFileLocked(dispatchPath, (dp) => {
-          dp.active = Array.isArray(dp.active) ? dp.active : [];
-          dp.active = dp.active.filter(d => {
-            const itemId = d.meta?.item?.id;
-            if (itemId && resetItemIds.has(itemId)) return false;
-            if (killedAgents.has(d.agent)) return false;
-            return true;
-          });
-          return dp;
-        }, { defaultValue: { pending: [], active: [], completed: [] } });
-      }
+        // Remove dispatch active entries for reset items or killed agents.
+        dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
+        dispatch.active = dispatch.active.filter(d => {
+          const itemId = d.meta?.item?.id;
+          if (itemId && resetItemIds.has(itemId)) return false;
+          if (killedAgents.has(d.agent)) return false;
+          return true;
+        });
+        return dispatch;
+      }, { defaultValue: { pending: [], active: [], completed: [] } });
 
       invalidateStatusCache();
       return jsonReply(res, 200, { ok: true, status: 'paused', resetWorkItems: reset });

package/engine/cleanup.js

@@ -28,6 +28,17 @@ function engine() { if (!_engine) _engine = require('../engine'); return _engine
 let _dispatch = null;
 function dispatchModule() { if (!_dispatch) _dispatch = require('./dispatch'); return _dispatch; }
 
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Check if a worktree directory name matches a branch via sanitized slug comparison.
+ * Eliminates 3x duplication of the branch matching logic (review feedback: Rebecca).
+ */
+function worktreeDirMatchesBranch(dirLower, branch) {
+  const branchSlug = sanitizeBranch(branch).toLowerCase();
+  return dirLower === branchSlug || dirLower.includes(branchSlug + '-') || dirLower.endsWith('-' + branchSlug);
+}
+
 // ─── Cleanup Orchestrator ────────────────────────────────────────────────────
 
 function runCleanup(config, verbose = false) {
@@ -37,27 +48,33 @@ function runCleanup(config, verbose = false) {
 
   // 1. Clean stale temp prompt/sysprompt files and orphaned safeWrite .tmp.* files (older than 1 hour)
   const oneHourAgo = Date.now() - 3600000;
-  try {
-    const tmpDir = path.join(ENGINE_DIR, 'tmp');
-    const scanDirs = [ENGINE_DIR, ...(fs.existsSync(tmpDir) ? [tmpDir] : [])];
-    for (const dir of scanDirs) {
-      for (const f of fs.readdirSync(dir)) {
-        const isPromptTemp = f.startsWith('prompt-') || f.startsWith('sysprompt-') || f.startsWith('tmp-sysprompt-');
-        const isSafeWriteTemp = /\.tmp\.\d+\.\d+$/.test(f);
-        if (isPromptTemp || isSafeWriteTemp) {
-          const fp = path.join(dir, f);
-          try {
-            const stat = fs.statSync(fp);
-            if (stat.mtimeMs < oneHourAgo) {
-              fs.unlinkSync(fp);
-              cleaned.tempFiles++;
-              if (isSafeWriteTemp) log('info', `Cleaned orphaned temp file: ${f}`);
-            }
-          } catch { /* cleanup */ }
-        }
+  const tmpDir = path.join(ENGINE_DIR, 'tmp');
+  const scanDirs = [ENGINE_DIR, ...(fs.existsSync(tmpDir) ? [tmpDir] : [])];
+  for (const dir of scanDirs) {
+    // Each directory gets its own try-catch so one failure doesn't abort other directories (Bug #27)
+    let dirEntries;
+    try {
+      dirEntries = fs.readdirSync(dir);
+    } catch (e) {
+      log('warn', `cleanup temp files: failed to read ${dir} — ${e.message}`);
+      continue;
+    }
+    for (const f of dirEntries) {
+      const isPromptTemp = f.startsWith('prompt-') || f.startsWith('sysprompt-') || f.startsWith('tmp-sysprompt-');
+      const isSafeWriteTemp = /\.tmp\.\d+\.\d+$/.test(f);
+      if (isPromptTemp || isSafeWriteTemp) {
+        const fp = path.join(dir, f);
+        try {
+          const stat = fs.statSync(fp);
+          if (stat.mtimeMs < oneHourAgo) {
+            fs.unlinkSync(fp);
+            cleaned.tempFiles++;
+            if (isSafeWriteTemp) log('info', `Cleaned orphaned temp file: ${f}`);
+          }
+        } catch { /* cleanup */ }
       }
     }
-  } catch (e) { log('warn', 'cleanup temp files: ' + e.message); }
+  }
 
   // 2. Clean live-output.log for idle agents (not currently working)
   for (const [agentId] of Object.entries(config.agents || {})) {
@@ -134,8 +151,7 @@ function runCleanup(config, verbose = false) {
         // Use sanitized exact match on the branch portion of the dir name (format: {slug}-{branch}-{suffix})
         const dirLower = dir.toLowerCase();
         for (const branch of mergedBranches) {
-          const branchSlug = sanitizeBranch(branch).toLowerCase();
-          if (dirLower === branchSlug || dirLower.includes(branchSlug + '-') || dirLower.endsWith('-' + branchSlug)) {
+          if (worktreeDirMatchesBranch(dirLower, branch)) {
             shouldClean = true;
             break;
           }
@@ -202,8 +218,38 @@ function runCleanup(config, verbose = false) {
       }
 
       // Remove all marked worktrees
+      // Re-read PR status immediately before deletion — a PR can be reopened between
+      // the initial status check and the actual deletion (Bug #15: TOCTOU race)
+      const freshPrs = safeJson(projectPrPath(project)) || [];
+      const freshMergedBranches = new Set();
+      for (const pr of freshPrs) {
+        if (pr.status === 'merged' || pr.status === 'abandoned' || pr.status === 'completed') {
+          if (pr.branch) freshMergedBranches.add(pr.branch);
+        }
+      }
+
       for (const entry of wtEntries) {
         if (entry.shouldClean) {
+          // Verify the branch is still merged/closed — skip if PR was reopened since initial check
+          const entryDirLower = entry.dir.toLowerCase();
+          let stillMerged = false;
+          for (const branch of freshMergedBranches) {
+            if (worktreeDirMatchesBranch(entryDirLower, branch)) {
+              stillMerged = true;
+              break;
+            }
+          }
+          // If originally marked due to merged branch but PR was reopened, skip deletion
+          if (!stillMerged) {
+            // Check if it was marked for age/cap cleanup (not branch-based) — those are still valid
+            const wasMarkedByBranch = [...mergedBranches].some(branch => worktreeDirMatchesBranch(entryDirLower, branch));
+            if (wasMarkedByBranch) {
+              if (verbose) console.log(`  Skipping worktree ${entry.dir}: PR was reopened since initial check`);
+              log('info', `Worktree deletion skipped — PR reopened: ${entry.dir}`);
+              continue;
+            }
+          }
+
           try {
             exec(`git worktree remove "${entry.wtPath}" --force`, { cwd: root, stdio: 'pipe', timeout: 30000 });
             cleaned.worktrees++;
@@ -312,7 +358,14 @@ function runCleanup(config, verbose = false) {
     const sweptDir = path.join(MINIONS_DIR, 'knowledge', '_swept');
     if (fs.existsSync(sweptDir)) {
       const sevenDaysAgo = Date.now() - 7 * 86400000;
-      for (const f of fs.readdirSync(sweptDir)) {
+      let sweptEntries;
+      try {
+        sweptEntries = fs.readdirSync(sweptDir);
+      } catch (e) {
+        log('warn', `cleanup swept KB: failed to read ${sweptDir} — ${e.message}`);
+        sweptEntries = [];
+      }
+      for (const f of sweptEntries) {
         try {
           const fp = path.join(sweptDir, f);
           if (fs.statSync(fp).mtimeMs < sevenDaysAgo) {
@@ -334,7 +387,11 @@ function runCleanup(config, verbose = false) {
       let current = 0;
       for (const cat of cats) {
         const d = path.join(knowledgeDir, cat);
-        if (fs.existsSync(d)) current += fs.readdirSync(d).length;
+        try {
+          if (fs.existsSync(d)) current += fs.readdirSync(d).length;
+        } catch (e) {
+          log('warn', `KB watchdog: failed to read ${cat} directory — ${e.message}`);
+        }
       }
       if (current < checkpoint.count) {
         log('warn', `KB watchdog: file count dropped ${checkpoint.count} → ${current}, restoring from git`);
@@ -343,8 +400,29 @@ function runCleanup(config, verbose = false) {
           if (!trackedCheck) {
             log('warn', 'KB watchdog: knowledge/ is not tracked in git HEAD — skipping restore');
           } else {
-            execSilent('git checkout HEAD -- knowledge', { cwd: MINIONS_DIR });
-            log('info', 'KB watchdog: restored knowledge/ from git HEAD');
+            // Bug #29: Check exit code and verify restore succeeded
+            let restoreOutput;
+            try {
+              restoreOutput = execSilent('git checkout HEAD -- knowledge', { cwd: MINIONS_DIR });
+            } catch (restoreErr) {
+              log('warn', `KB watchdog: git checkout exited with error — ${restoreErr.message}`);
+              restoreOutput = null;
+            }
+            if (restoreOutput !== null) {
+              // Verify the restore actually recovered files
+              let postRestoreCount = 0;
+              for (const cat of cats) {
+                const d = path.join(knowledgeDir, cat);
+                try {
+                  if (fs.existsSync(d)) postRestoreCount += fs.readdirSync(d).length;
+                } catch { /* count what we can */ }
+              }
+              if (postRestoreCount < checkpoint.count) {
+                log('warn', `KB watchdog: restore incomplete — expected ${checkpoint.count} files, got ${postRestoreCount}`);
+              } else {
+                log('info', `KB watchdog: restored knowledge/ from git HEAD (${postRestoreCount} files)`);
+              }
+            }
           }
         } catch (err) {
           log('error', `KB watchdog: git restore failed — ${err.message}`);
@@ -393,7 +471,14 @@ function runCleanup(config, verbose = false) {
   } catch (e) { log('warn', 'migrate central legacy statuses: ' + e.message); }
   // PRD items (missing_features[].status)
   try {
-    const prdFiles = fs.readdirSync(PRD_DIR).filter(f => f.endsWith('.json'));
+    let prdDirEntries;
+    try {
+      prdDirEntries = fs.readdirSync(PRD_DIR);
+    } catch (e) {
+      log('warn', `migrate PRD statuses: failed to read ${PRD_DIR} — ${e.message}`);
+      prdDirEntries = [];
+    }
+    const prdFiles = prdDirEntries.filter(f => f.endsWith('.json'));
     for (const pf of prdFiles) {
       const prdPath = path.join(PRD_DIR, pf);
       const prd = safeJson(prdPath);
@@ -419,4 +504,5 @@ function runCleanup(config, verbose = false) {
 
 module.exports = {
   runCleanup,
+  worktreeDirMatchesBranch,  // exported for testing
 };

package/package.json

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