@yemi33/minions 0.1.291 → 0.1.293

package/CHANGELOG.md

@@ -1,11 +1,16 @@
 # Changelog
 
-## 0.1.291 (2026-04-03)
+## 0.1.293 (2026-04-03)
 
 ### Features
+- 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
 -  enforce worktree isolation — 4 code paths fixed
 - ' not 'Evaluate:'

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/engine/shared.js

@@ -52,14 +52,37 @@ function safeJson(p) {
       const backupData = JSON.parse(fs.readFileSync(backupPath, 'utf8'));
       // Backup is valid — restore it to the primary file (atomic via safeWrite)
       console.log(`[safeJson] restored ${path.basename(p)} from .backup sidecar`);
-      try { safeWrite(p, backupData); } catch { /* best-effort restore */ }
+      try {
+        safeWrite(p, backupData);
+        // Verify the restored file matches expected content
+        const verifyData = JSON.parse(fs.readFileSync(p, 'utf8'));
+        if (JSON.stringify(verifyData) !== JSON.stringify(backupData)) {
+          const errMsg = `[safeJson] CRITICAL: backup restore verification failed for ${p} — written data does not match backup`;
+          console.error(errMsg);
+          throw new Error(errMsg);
+        }
+      } catch (restoreErr) {
+        // Re-throw CRITICAL errors so they propagate to callers
+        if (restoreErr.message && restoreErr.message.includes('CRITICAL')) throw restoreErr;
+        const errMsg = `[safeJson] CRITICAL: backup restore failed for ${p}: ${restoreErr.message}`;
+        console.error(errMsg);
+        throw new Error(errMsg);
+      }
       return backupData;
-    } catch {
+    } catch (outerErr) {
+      // Let CRITICAL errors propagate — callers must know about data integrity failures
+      if (outerErr.message && outerErr.message.includes('CRITICAL')) throw outerErr;
       return null;
     }
   }
 }
 
+/**
+ * Monotonic counter for generating unique temp file names within this process.
+ * Assumes single-thread execution (no worker_threads). If worker_threads are
+ * introduced, this must be replaced with an atomic or thread-safe counter to
+ * avoid temp file name collisions.
+ */
 let _tmpCounter = 0;
 
 function safeWrite(p, data) {
@@ -129,10 +152,19 @@ function withFileLock(lockPath, fn, {
       try {
         const stat = fs.statSync(lockPath);
         if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-          try { fs.unlinkSync(lockPath); } catch { /* race: another process removed it */ }
-          continue; // retry immediately after removing stale lock
+          try {
+            fs.unlinkSync(lockPath);
+          } catch (unlinkErr) {
+            // ENOENT: another process deleted the lock between stat and unlink — safe to retry
+            if (unlinkErr.code !== 'ENOENT') throw unlinkErr;
+          }
+          sleepMs(retryDelayMs); // avoid busy-loop on contention
+          continue;
         }
-      } catch { /* lock file disappeared between EEXIST and stat — retry will succeed */ }
+      } catch (staleErr) {
+        // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed
+        if (staleErr.code !== 'ENOENT') throw staleErr;
+      }
       sleepMs(retryDelayMs);
     }
   }

package/package.json

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