@yemi33/minions 0.1.2145 → 0.1.2146

package/engine/cleanup.js

@@ -634,6 +634,15 @@ async function runCleanup(config, verbose = false) {
         if (registered.has(full)) continue;
         let stat; try { stat = fs.statSync(full); } catch { continue; }
         if (stat.mtimeMs >= _twoHoursAgo) continue;
+        // W-mq5rwwss000f30a7 — even an "orphan" dir (one git doesn't know
+        // about) may still host a live agent if dispatch persistence ran
+        // before `git worktree add` finished. Skip when a live dispatch
+        // claims it.
+        if (shared.isWorktreePathLive(full)) {
+          log('info', `Cleanup: skip orphan worktree dir ${full} — live dispatch claims it`);
+          shared._writeWorktreeSkipLiveInboxNote(full, 'cleanup.orphanWorktreeDirSweep');
+          continue;
+        }
         try {
           fs.rmSync(full, { recursive: true, force: true });
           cleaned.orphanWorktreeDirs++;

package/engine/shared.js

@@ -6576,13 +6576,126 @@ function _purgeReservedFiles(dirPath) {
   }
 }
 
-function removeWorktree(wtPath, gitRoot, worktreeRoot) {
+// ── Live-worktree guard (W-mq5rwwss000f30a7) ─────────────────────────────────
+// Single source of truth for "is some non-terminal dispatch currently using
+// this worktree?" Every code path that wants to wipe / reset / recycle /
+// quarantine a worktree MUST call isWorktreePathLive() first and skip on
+// true. Without this guard the engine has wiped agents mid-task four times
+// in a row (W-mq5n1zx5000hcfb5 post-mortem) by reaping a worktree whose
+// dispatch was still active.
+//
+// Fail-open semantics: when SQLite is unreachable or the query throws, the
+// helper returns true (assume live). Better to leak a worktree than nuke
+// an agent's unpushed work.
+
+function _normalizeWorktreePath(p) {
+  if (!p || typeof p !== 'string') return '';
+  let resolved;
+  try { resolved = path.resolve(p); }
+  catch { return ''; }
+  resolved = resolved.replace(/\\/g, '/').replace(/\/+$/g, '');
+  if (process.platform === 'win32') resolved = resolved.toLowerCase();
+  return resolved;
+}
+
+function isWorktreePathLive(worktreePath, opts = {}) {
+  if (!worktreePath) return false;
+  const target = _normalizeWorktreePath(worktreePath);
+  if (!target) return false;
+  const excludeDispatchId = opts.excludeDispatchId ? String(opts.excludeDispatchId) : null;
+  let db = opts.db || null;
+  if (!db) {
+    try { db = require('./db').getDb(); }
+    catch (e) {
+      log('warn', `isWorktreePathLive: SQL unavailable for ${worktreePath} (${e.message}) — fail-open (assume live)`);
+      return true;
+    }
+  }
+  if (!db) {
+    log('warn', `isWorktreePathLive: no db handle for ${worktreePath} — fail-open (assume live)`);
+    return true;
+  }
+  let rows;
+  try {
+    rows = db.prepare(`
+      SELECT id,
+             json_extract(data, '$.worktreePath') AS top_wt,
+             json_extract(data, '$.meta.worktreePath') AS meta_wt
+      FROM dispatches
+      WHERE status IN ('pending', 'active')
+    `).all();
+  } catch (e) {
+    log('warn', `isWorktreePathLive: query threw for ${worktreePath} (${e.message}) — fail-open (assume live)`);
+    return true;
+  }
+  for (const row of rows || []) {
+    if (excludeDispatchId && String(row.id) === excludeDispatchId) continue;
+    if (row.top_wt && _normalizeWorktreePath(row.top_wt) === target) return true;
+    if (row.meta_wt && _normalizeWorktreePath(row.meta_wt) === target) return true;
+  }
+  return false;
+}
+
+// Drop a deduped inbox note when a wipe site skips due to the live guard so
+// operators can see when the guard fires. Filename is keyed on basename +
+// UTC date — a single skip per worktree per day produces one note; further
+// skips that day silently no-op.
+function _writeWorktreeSkipLiveInboxNote(worktreePath, callerTag) {
+  try {
+    const base = path.basename(String(worktreePath || '').replace(/[\\/]+$/g, '')) || 'unknown';
+    const safeBase = base.replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 80);
+    const date = new Date().toISOString().slice(0, 10);
+    const fname = `engine-worktree-skip-live-${safeBase}-${date}.md`;
+    const inboxDir = path.join(MINIONS_DIR, 'notes', 'inbox');
+    try { fs.mkdirSync(inboxDir, { recursive: true }); } catch { /* exists */ }
+    const fpath = path.join(inboxDir, fname);
+    if (fs.existsSync(fpath)) return; // deduped
+    const body = [
+      '---',
+      `id: NOTE-${crypto.randomBytes(8).toString('hex')}`,
+      'agent: engine',
+      `date: ${date}`,
+      '---',
+      '',
+      `# Engine skipped worktree wipe — live dispatch guard fired (W-mq5rwwss000f30a7)`,
+      '',
+      `- caller: ${callerTag || 'unknown'}`,
+      `- worktree: ${worktreePath}`,
+      `- timestamp: ${new Date().toISOString()}`,
+      '',
+      'A non-terminal dispatch row still claims this worktree. The wipe was skipped to',
+      'protect agent state. If this fires repeatedly, inspect engine/state.db dispatches',
+      "table to find which dispatch is stuck claiming the path.",
+      '',
+    ].join('\n');
+    fs.writeFileSync(fpath, body);
+  } catch { /* best-effort — never throw from the skip-note writer */ }
+}
+
+function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
   const resolved = path.resolve(wtPath);
   const resolvedRoot = path.resolve(worktreeRoot) + path.sep;
   if (!resolved.startsWith(resolvedRoot)) {
     log('warn', `removeWorktree: refusing to remove ${wtPath} — not under ${worktreeRoot}`);
     return false;
   }
+  // W-mq5rwwss000f30a7 — never wipe a worktree while an agent is actively
+  // dispatched inside it. isWorktreePathLive fails OPEN (returns true) when
+  // the dispatches table is unreachable, so we err on the side of leaking
+  // the worktree rather than destroying agent work.
+  //
+  // PR #3133 review: callers that are themselves the owning dispatch (e.g.
+  // the W-mpbqhstz001lf518 dispatch-end orphan GC, or the pool-return
+  // chain) can pass `excludeDispatchId` so their OWN active row — which
+  // legitimately claims the worktreePath via the pending→active persistence
+  // at engine.js — is ignored by the guard. Any OTHER non-terminal row
+  // still blocks the wipe.
+  const excludeDispatchId = opts && opts.excludeDispatchId ? String(opts.excludeDispatchId) : null;
+  if (isWorktreePathLive(resolved, excludeDispatchId ? { excludeDispatchId } : undefined)) {
+    log('warn', `removeWorktree: skip — live dispatch in ${wtPath}`);
+    _writeWorktreeSkipLiveInboxNote(wtPath, 'shared.removeWorktree');
+    return false;
+  }
   _pruneRemoveWorktreeFailures();
   // Skip paths that failed 3+ times — retry after 1 hour cooldown
   const prior = _removeWorktreeFailures.get(resolved);
@@ -7030,6 +7143,9 @@ module.exports = {
   listProcessDescendants,
   listProcessReachable,
   removeWorktree,
+  isWorktreePathLive,
+  _normalizeWorktreePath, // exported for testing
+  _writeWorktreeSkipLiveInboxNote, // exported for testing
   _retryFsOp, // exported for testing (W-mq5o6bvy000x7191)
   bumpWorktreeGcMetric, // exported for testing (W-mq5o6bvy000x7191)
   _WORKTREE_RETRYABLE_CODES, // exported for testing (W-mq5o6bvy000x7191)

package/engine/worktree-gc.js

@@ -284,6 +284,13 @@ function gcDispatchWorktreeIfOrphan(opts) {
     worktreeRoot,
     log = _noopLog,
     removeWorktree = null,
+    // PR #3133 review — when the dispatch-end GC is the caller, the
+    // current dispatch's own active row legitimately claims worktreePath
+    // (persisted by engine.js at pending→active). Pass `excludeDispatchId`
+    // so shared.removeWorktree's live-guard ignores that row and lets the
+    // dispatch GC its own orphan worktree. Other live claimants still
+    // block the wipe.
+    excludeDispatchId = null,
     config = null,
     writeToInbox = null,
   } = opts || {};
@@ -295,9 +302,10 @@ function gcDispatchWorktreeIfOrphan(opts) {
     return { outcome: 'skip', reason: 'no-git-root', removed: false };
   }
   const _removeFn = typeof removeWorktree === 'function' ? removeWorktree : shared.removeWorktree;
+  const _rmOpts = excludeDispatchId ? { excludeDispatchId } : undefined;
   const resolved = (() => { try { return path.resolve(worktreePath); } catch { return worktreePath; } })();
   try {
-    const removed = _removeFn(worktreePath, gitRoot, worktreeRoot);
+    const removed = _removeFn(worktreePath, gitRoot, worktreeRoot, _rmOpts);
     if (removed) {
       _markStuckSuccess(resolved, { writeToInbox });
       log('info', `worktree-gc: dispatch-end removed ${path.basename(worktreePath)}`);

package/engine.js

@@ -1021,9 +1021,21 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
               statusError: e.message,
             },
           );
-          result.quarantined = true;
-          result.quarantinedPath = q.quarantinedPath;
-          result.backupRef = q.backupRef;
+          // PR #3133 review — honor q.skipped instead of dishonestly
+          // claiming quarantined=true with a null path. When
+          // _quarantineDirtyWorktree skips because shared.isWorktreePathLive
+          // fires on the worktree, no rename happened, no backup ref was
+          // written, and the caller's downstream "quarantined to X" log /
+          // error message would print "quarantined to null". Surface the
+          // skip honestly so the spawn-error path (engine.js:2056-2066) can
+          // render a truthful message and the dispatch stays non-retryable.
+          if (q.skipped) {
+            result.quarantineSkipped = true;
+          } else {
+            result.quarantined = true;
+            result.quarantinedPath = q.quarantinedPath;
+            result.backupRef = q.backupRef;
+          }
         } catch (qErr) {
           result.quarantineError = qErr.message;
           log('error', `assertCleanSharedWorktree: quarantine after status-failed failed for ${worktreePath}: ${qErr.message}`);
@@ -1143,9 +1155,16 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
             dirtyFiles: result.dirtyFiles,
           },
         );
-        result.quarantined = true;
-        result.quarantinedPath = q.quarantinedPath;
-        result.backupRef = q.backupRef;
+        // PR #3133 review — same honest-result fix as the status-failed
+        // path above. If _quarantineDirtyWorktree was skipped by the
+        // live-guard, do NOT set quarantined=true with a null path.
+        if (q.skipped) {
+          result.quarantineSkipped = true;
+        } else {
+          result.quarantined = true;
+          result.quarantinedPath = q.quarantinedPath;
+          result.backupRef = q.backupRef;
+        }
       } catch (qErr) {
         result.quarantineError = qErr.message;
         log('error', `assertCleanSharedWorktree: quarantine failed for ${worktreePath}: ${qErr.message}`);
@@ -1214,6 +1233,14 @@ async function _quarantineDirtyWorktree(rootDir, worktreePath, branchName, gitOp
 
   // Rename the worktree dir. Once this succeeds the worktree is functionally
   // quarantined; subsequent failures only affect ref bookkeeping.
+  // W-mq5rwwss000f30a7 — never quarantine (=rename out from under) a worktree
+  // that a live dispatch still claims. Quarantine breaks the agent's cwd just
+  // as completely as removeWorktree would.
+  if (shared.isWorktreePathLive(worktreePath)) {
+    log('warn', `_quarantineDirtyWorktree: skip — live dispatch in ${worktreePath}`);
+    shared._writeWorktreeSkipLiveInboxNote(worktreePath, '_quarantineDirtyWorktree');
+    return { quarantinedPath: null, backupRef: null, skipped: true };
+  }
   fs.renameSync(worktreePath, quarantinedPath);
 
   // Prune git's stale worktree metadata so the next `git worktree add` for
@@ -2047,14 +2074,14 @@ async function spawnAgent(dispatchItem, config) {
         const failureClassName = isDivergent ? 'WORKTREE_DIVERGENT' : 'WORKTREE_DIRTY';
         const reasonMsg = cleanResult.quarantined
           ? `${failureClassName}: reused worktree at ${worktreePath} was dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} dirty file(s)${previewFiles ? ': ' + previewFiles : ''}) — quarantined to ${cleanResult.quarantinedPath}. Next dispatch will start fresh.`
-          : `${failureClassName}: reused worktree at ${worktreePath} is dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} file(s)${previewFiles ? ': ' + previewFiles : ''}). Quarantine ${cleanResult.quarantineError ? 'errored: ' + cleanResult.quarantineError : 'was not attempted (' + cleanResult.reason + ').'}`;
+          : `${failureClassName}: reused worktree at ${worktreePath} is dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} file(s)${previewFiles ? ': ' + previewFiles : ''}). Quarantine ${cleanResult.quarantineError ? 'errored: ' + cleanResult.quarantineError : (cleanResult.quarantineSkipped ? 'was skipped — another live dispatch claims the worktree (see notes/inbox/ engine-worktree-skip-live note).' : 'was not attempted (' + cleanResult.reason + ').')}`;
         log('error', reasonMsg);
         _cleanupPromptFiles();
         completeDispatch(
           id,
           DISPATCH_RESULT.ERROR,
           reasonMsg.slice(0, 500),
-          `Engine preflight refused to dispatch into a dirty/divergent reused worktree (#2996). Reason: ${cleanResult.reason}.${cleanResult.quarantined ? ` Worktree quarantined to ${cleanResult.quarantinedPath}; backup ref ${cleanResult.backupRef || '(skipped)'}. See notes/inbox/ for recovery instructions.` : ''}`,
+          `Engine preflight refused to dispatch into a dirty/divergent reused worktree (#2996). Reason: ${cleanResult.reason}.${cleanResult.quarantined ? ` Worktree quarantined to ${cleanResult.quarantinedPath}; backup ref ${cleanResult.backupRef || '(skipped)'}. See notes/inbox/ for recovery instructions.` : (cleanResult.quarantineSkipped ? ' Quarantine was skipped because another live dispatch claims this worktree path; this dispatch will not auto-retry until the live claimant clears.' : '')}`,
           { agentRetryable: isStatusProbeFailed && cleanResult.quarantined, failureClass: failureClassValue },
         );
         cleanupTempAgent(agentId);
@@ -3743,6 +3770,15 @@ async function spawnAgent(dispatchItem, config) {
       const _projForReturn = project?.name || 'default';
       const _poolSizeReturn = worktreePool.getProjectPoolSize(_projForReturn, config);
       if (!_keepPidsAlive && !_managedSpawnAlive && _poolSizeReturn > 0) {
+        // W-mq5rwwss000f30a7 — defensive live-worktree check before the
+        // destructive `git reset --hard HEAD → git clean -fd → checkout
+        // --detach` chain. We pass excludeDispatchId so the active row for
+        // THIS dispatch (still in dispatch.active until completeDispatch
+        // fires below) is ignored. Any OTHER live dispatch claiming the
+        // same path is a sign of a concurrency bug and must not be wiped.
+        if (shared.isWorktreePathLive(worktreePath, { excludeDispatchId: id })) {
+          log('warn', `worktree-pool: skip return — another live dispatch claims ${worktreePath}`);
+        } else {
         try {
           const _mainRefRet = sanitizeBranch(shared.resolveMainBranch(rootDir, project?.mainBranch));
           await shared.shellSafeGit(['reset', '--hard', 'HEAD'], { ..._gitOpts, cwd: worktreePath, timeout: 30000 });
@@ -3771,6 +3807,7 @@ async function spawnAgent(dispatchItem, config) {
           // dispatch-end GC below will pick it up via the isPoolMember
           // check (which now correctly returns false).
         }
+        }
       } else if (_keepPidsAlive || _managedSpawnAlive) {
         // Skip the pool — the worktree is in use by left-running processes
         // (keep_processes PIDs or managed-spawn services). Make sure no
@@ -3803,6 +3840,13 @@ async function spawnAgent(dispatchItem, config) {
           worktreeRoot: _wtRoot,
           agentId,
           managedSpawnSpawnedCount: Array.isArray(managedSpawnSpawned) ? managedSpawnSpawned.length : 0,
+          // W-mq5rwwss000f30a7 / PR #3133 review — this dispatch's own
+          // active row still claims worktreePath (persisted at pending→active,
+          // line ~3998). Without excludeDispatchId, shared.removeWorktree's
+          // live-guard would skip and silently neuter the GC for the
+          // default worktreePoolSize:0 config. Pool-return uses the same
+          // plumbing; this is the matching wiring on the orphan-GC side.
+          excludeDispatchId: id,
           log,
         });
         if (_gcResult.outcome === 'gc') {
@@ -3973,6 +4017,11 @@ async function spawnAgent(dispatchItem, config) {
     // route output parsing through the right adapter. Also surfaces the choice
     // in dispatch.json for debugging multi-runtime fleets.
     item.runtimeName = runtimeName;
+    // W-mq5rwwss000f30a7 — persist the worktree path so the live-worktree
+    // guard (shared.isWorktreePathLive) can correlate destructive callers
+    // (removeWorktree, cleanup orphan-dir sweep, pool-return, quarantine)
+    // back to this active dispatch and skip the wipe.
+    if (worktreePath) item.worktreePath = worktreePath;
     delete item.skipReason;
     delete item._agentBusySince;
     if (!dispatch.active.some(d => d.id === id)) {

package/package.json

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