@yemi33/minions 0.1.2142 → 0.1.2143

package/engine/worktree-gc.js

@@ -41,6 +41,128 @@ function _managedSpawn() {
 
 const _noopLog = () => {};
 
+// ── Stuck-dir escalation (Layer 4 of W-mq5o6bvy000x7191) ─────────────────────
+// In-memory ring of paths that have failed removal N consecutive times. After
+// escalation we (a) write a dedup'd inbox note, (b) suppress repeat per-tick
+// warns for `worktreeStuckSuppressMs`, and (c) reduce retry cadence to
+// `worktreeStuckSlowRetryMs`. The ring also remembers the last attempt time so
+// the slow-cadence gate is precise. Memory only — dies with the engine; a
+// fresh boot starts fresh and is re-escalated on the same path after N more
+// failures, which is the desired behavior.
+const _stuckPaths = new Map(); // resolved path -> { failures, escalatedAt, suppressedUntil, lastAttempt, lastError, lastNoteDate }
+
+function _stuckRecord(resolvedPath) {
+  let rec = _stuckPaths.get(resolvedPath);
+  if (!rec) { rec = { failures: 0, escalatedAt: 0, suppressedUntil: 0, lastAttempt: 0, lastError: '', lastNoteDate: '' }; _stuckPaths.set(resolvedPath, rec); }
+  return rec;
+}
+
+function _isStuckPathSuppressed(resolvedPath, now = Date.now()) {
+  const rec = _stuckPaths.get(resolvedPath);
+  if (!rec || !rec.suppressedUntil) return false;
+  return now < rec.suppressedUntil;
+}
+
+function _shouldSlowRetry(resolvedPath, slowRetryMs, now = Date.now()) {
+  const rec = _stuckPaths.get(resolvedPath);
+  if (!rec || !rec.escalatedAt) return true; // not escalated → eligible
+  return (now - rec.lastAttempt) >= slowRetryMs;
+}
+
+function _markStuckSuccess(resolvedPath, opts = {}) {
+  const rec = _stuckPaths.get(resolvedPath);
+  if (!rec) return false;
+  const wasEscalated = rec.escalatedAt > 0;
+  _stuckPaths.delete(resolvedPath);
+  if (wasEscalated) {
+    try { shared.bumpWorktreeGcMetric('recoveredAfterEscalation'); } catch { /* optional */ }
+    try {
+      const writer = typeof opts.writeToInbox === 'function' ? opts.writeToInbox : shared.writeToInbox;
+      const basename = path.basename(resolvedPath);
+      const body = [
+        `# Worktree recovered: ${basename}`,
+        '',
+        `Previously stuck worktree dir **${resolvedPath}** has been successfully removed`,
+        `after escalation. Suppression cleared.`,
+      ].join('\n');
+      writer('engine', `worktree-recovered-${basename}`, body);
+    } catch { /* note best-effort */ }
+  }
+  return wasEscalated;
+}
+
+function _maybeEscalateStuck(resolvedPath, errorMsg, opts = {}) {
+  const cfgEng = (opts.config && opts.config.engine) || {};
+  const threshold = cfgEng.worktreeStuckThreshold || shared.ENGINE_DEFAULTS.worktreeStuckThreshold || 10;
+  const suppressMs = cfgEng.worktreeStuckSuppressMs || shared.ENGINE_DEFAULTS.worktreeStuckSuppressMs || (60 * 60 * 1000);
+  const now = Date.now();
+  const rec = _stuckRecord(resolvedPath);
+  rec.failures++;
+  rec.lastAttempt = now;
+  rec.lastError = errorMsg || rec.lastError || 'unknown';
+  if (rec.failures < threshold) return { escalated: false, alreadyEscalated: false };
+
+  const alreadyEscalated = rec.escalatedAt > 0;
+  if (!alreadyEscalated) {
+    rec.escalatedAt = now;
+    rec.suppressedUntil = now + suppressMs;
+    try { shared.bumpWorktreeGcMetric('stuckEscalated'); } catch { /* optional */ }
+  } else if (now >= rec.suppressedUntil) {
+    // Re-arm the suppression window on each post-escalation failure tick.
+    rec.suppressedUntil = now + suppressMs;
+  }
+
+  // Dedup inbox note per UTC day.
+  const today = new Date(now).toISOString().slice(0, 10);
+  if (rec.lastNoteDate === today) return { escalated: !alreadyEscalated, alreadyEscalated };
+  rec.lastNoteDate = today;
+
+  try {
+    const writer = typeof opts.writeToInbox === 'function' ? opts.writeToInbox : shared.writeToInbox;
+    const basename = path.basename(resolvedPath);
+    const body = [
+      `# Worktree stuck: ${basename}`,
+      '',
+      `Worktree dir **${resolvedPath}** has failed removal ${rec.failures} consecutive times.`,
+      `Last error: \`${rec.lastError}\``,
+      '',
+      '## Suggested manual recovery (Windows)',
+      '',
+      'Identify the lock holder:',
+      '',
+      '```powershell',
+      `Get-Process | Where-Object { $_.Path -like '${resolvedPath.replace(/'/g, "''")}*' }`,
+      '```',
+      '',
+      'If `handle.exe` from Sysinternals is installed:',
+      '',
+      '```',
+      `handle.exe -p <pid> ${resolvedPath}`,
+      '```',
+      '',
+      'Once the holder is gone, force-remove:',
+      '',
+      '```powershell',
+      `Remove-Item -Recurse -Force "${resolvedPath}"`,
+      '```',
+      '',
+      `The engine will continue to retry this path at the slow cadence`,
+      `(\`ENGINE_DEFAULTS.worktreeStuckSlowRetryMs\`, default 30min). When the`,
+      `holder finally releases, a \`worktree-recovered-${basename}\` note is`,
+      `written here to clear this alert.`,
+      '',
+      `Per-tick warn spam is suppressed for the next`,
+      `\`ENGINE_DEFAULTS.worktreeStuckSuppressMs\` (default 60min).`,
+    ].join('\n');
+    writer('engine', `worktree-stuck-${basename}`, body);
+  } catch { /* note best-effort */ }
+
+  return { escalated: !alreadyEscalated, alreadyEscalated };
+}
+
+// Test-only reset hook. Production code never calls this.
+function _resetStuckPathsForTesting() { _stuckPaths.clear(); }
+
 /**
  * Decide whether a dispatch-end worktree should be GC'd.
  *
@@ -162,6 +284,8 @@ function gcDispatchWorktreeIfOrphan(opts) {
     worktreeRoot,
     log = _noopLog,
     removeWorktree = null,
+    config = null,
+    writeToInbox = null,
   } = opts || {};
   const decision = shouldGcDispatchWorktree(opts);
   if (!decision.gc) {
@@ -171,17 +295,26 @@ function gcDispatchWorktreeIfOrphan(opts) {
     return { outcome: 'skip', reason: 'no-git-root', removed: false };
   }
   const _removeFn = typeof removeWorktree === 'function' ? removeWorktree : shared.removeWorktree;
+  const resolved = (() => { try { return path.resolve(worktreePath); } catch { return worktreePath; } })();
   try {
     const removed = _removeFn(worktreePath, gitRoot, worktreeRoot);
     if (removed) {
+      _markStuckSuccess(resolved, { writeToInbox });
       log('info', `worktree-gc: dispatch-end removed ${path.basename(worktreePath)}`);
       return { outcome: 'gc', reason: decision.reason, removed: true };
     }
-    log('warn', `worktree-gc: dispatch-end remove returned false for ${worktreePath}`);
-    return { outcome: 'gc-failed', reason: 'remove-failed', removed: false };
+    // W-mq5o6bvy000x7191 (Layer 4): track stuck dirs even on soft-false returns.
+    const { escalated, alreadyEscalated } = _maybeEscalateStuck(resolved, 'remove returned false', { config, writeToInbox });
+    if (!alreadyEscalated && !_isStuckPathSuppressed(resolved)) {
+      log('warn', `worktree-gc: dispatch-end remove returned false for ${worktreePath}`);
+    }
+    return { outcome: 'gc-failed', reason: 'remove-failed', removed: false, stuckEscalated: escalated };
   } catch (gcErr) {
-    log('warn', `worktree-gc: dispatch-end remove threw for ${worktreePath}: ${gcErr.message}`);
-    return { outcome: 'gc-failed', reason: 'remove-threw', removed: false };
+    const { escalated, alreadyEscalated } = _maybeEscalateStuck(resolved, gcErr && gcErr.message, { config, writeToInbox });
+    if (!alreadyEscalated && !_isStuckPathSuppressed(resolved)) {
+      log('warn', `worktree-gc: dispatch-end remove threw for ${worktreePath}: ${gcErr.message}`);
+    }
+    return { outcome: 'gc-failed', reason: 'remove-threw', removed: false, stuckEscalated: escalated };
   }
 }
 
@@ -335,21 +468,255 @@ function pruneOrphanWorktrees(opts) {
       }
 
       try {
+        // W-mq5o6bvy000x7191 (Layer 4): respect slow-cadence retry for paths
+        // that have escalated past `worktreeStuckThreshold`.
+        const wtResolved = path.resolve(wtPath);
+        const slowRetryMs = (opts.config?.engine?.worktreeStuckSlowRetryMs)
+          ?? shared.ENGINE_DEFAULTS.worktreeStuckSlowRetryMs
+          ?? (30 * 60 * 1000);
+        if (!_shouldSlowRetry(wtResolved, slowRetryMs)) {
+          projStats.kept++; result.kept++;
+          continue;
+        }
+        const suppressed = _isStuckPathSuppressed(wtResolved);
         const removed = _removeWorktree(wtPath, rootDir, wtParent);
         if (removed) {
           projStats.evicted++; result.evicted++;
+          _markStuckSuccess(wtResolved, { writeToInbox: opts.writeToInbox });
           log('info', `worktree-gc: boot-evicted orphan ${name} for project ${project.name || 'default'}`);
         } else {
           projStats.failed++; result.failed++;
-          log('warn', `worktree-gc: boot-evict returned false for ${wtPath}`);
+          const { alreadyEscalated } = _maybeEscalateStuck(wtResolved, 'remove returned false', { config: opts.config, writeToInbox: opts.writeToInbox });
+          if (!alreadyEscalated && !suppressed) {
+            log('warn', `worktree-gc: boot-evict returned false for ${wtPath}`);
+          }
+        }
+      } catch (rmErr) {
+        projStats.failed++; result.failed++;
+        const wtResolved = path.resolve(wtPath);
+        const suppressed = _isStuckPathSuppressed(wtResolved);
+        const { alreadyEscalated } = _maybeEscalateStuck(wtResolved, rmErr && rmErr.message, { config: opts.config, writeToInbox: opts.writeToInbox });
+        if (!alreadyEscalated && !suppressed) {
+          log('warn', `worktree-gc: boot-evict threw for ${wtPath}: ${rmErr.message}`);
+        }
+      }
+    }
+    result.perProject[project.name || rootDir] = projStats;
+  }
+  return result;
+}
+
+/**
+ * Out-of-root scan: walk `git worktree list --porcelain` for every project,
+ * find registered worktrees outside the configured `worktreeRoot`, and reap
+ * the unprotected ones. Companion to `pruneOrphanWorktrees`, which only
+ * walks `<localPath>/<worktreeRoot>` and is permanently blind to worktrees
+ * created under `D:/tmp-*`, `D:/squad-worktrees/*`, etc.
+ *
+ * Also calls `git worktree prune --expire=now` per project so registry
+ * entries whose dirs were manually deleted (`Remove-Item`d) drop out of the
+ * git index immediately.
+ *
+ *   - projects        — array of `{ name, localPath }`
+ *   - dispatchSnap    — `{ active: [...], pending: [...] }`
+ *   - worktreeRootRel — configured `engine.worktreeRoot` (default '../worktrees')
+ *                       used to compute the inside-root set we DO NOT touch
+ *                       here (the existing scanner handles it).
+ *   - log / fs / removeWorktree / listManagedSpecs / execSilent — injection
+ *
+ * Protection rules mirror `pruneOrphanWorktrees`:
+ *   1. The main checkout (path === projectLocalPath) is always kept.
+ *   2. Any path inside the configured `worktreeRoot` is skipped (delegated).
+ *   3. Branch matches an active/pending dispatch → keep.
+ *   4. Path is in the worktree-pool → keep.
+ *   5. managed_spawn cwd anchored → keep.
+ *
+ * Returns `{ scanned, kept, evicted, failed, prunedRegistry, perProject }`.
+ *
+ * W-mq5o6bvy000x7191 Layer 3.
+ */
+function pruneOrphanWorktreesFromGitRegistry(opts) {
+  opts = opts || {};
+  const projects = Array.isArray(opts.projects) ? opts.projects : [];
+  const dispatchSnap = opts.dispatchSnap || { active: [], pending: [] };
+  const worktreeRootRel = typeof opts.worktreeRootRel === 'string' && opts.worktreeRootRel.length > 0
+    ? opts.worktreeRootRel
+    : (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.worktreeRoot) || '../worktrees';
+  const log = typeof opts.log === 'function' ? opts.log : _noopLog;
+  const _fs = opts.fs || fs;
+  const _removeWorktree = typeof opts.removeWorktree === 'function'
+    ? opts.removeWorktree
+    : shared.removeWorktree;
+  const _listManagedSpecs = typeof opts.listManagedSpecs === 'function'
+    ? opts.listManagedSpecs
+    : (() => {
+      try { return _managedSpawn().listManagedSpecs(); }
+      catch (_e) { return []; }
+    });
+  const _execSilent = typeof opts.execSilent === 'function'
+    ? opts.execSilent
+    : shared.execSilent;
+  const _parseWorktreePorcelain = typeof opts.parseWorktreePorcelain === 'function'
+    ? opts.parseWorktreePorcelain
+    : shared.parseWorktreePorcelain;
+
+  // Branches of active/pending dispatches (with and without `refs/heads/`
+  // normalization). Matched case-insensitively to mirror git's behavior on
+  // Windows (case-insensitive filesystems).
+  const protectedBranches = new Set();
+  for (const d of [...(dispatchSnap.active || []), ...(dispatchSnap.pending || [])]) {
+    const br = d && d.meta && d.meta.branch;
+    if (br && typeof br === 'string') {
+      protectedBranches.add(br.toLowerCase());
+      protectedBranches.add(br.toLowerCase().replace(/^refs\/heads\//, ''));
+    }
+  }
+
+  // Pool-known paths (idle + borrowed + stale-but-still-on-disk).
+  const poolPaths = new Set();
+  try {
+    const entries = (worktreePool.readPool() || { entries: [] }).entries || [];
+    for (const e of entries) {
+      if (e && e.path) poolPaths.add(worktreePool._normalizePath(e.path));
+    }
+  } catch (_e) { /* pool readable optional */ }
+  if (Array.isArray(opts.extraPoolPaths)) {
+    for (const p of opts.extraPoolPaths) poolPaths.add(worktreePool._normalizePath(p));
+  }
+
+  // managed_spawn cwds.
+  const managedSpawnCwds = [];
+  try {
+    for (const rec of (_listManagedSpecs() || [])) {
+      if (!rec || typeof rec.cwd !== 'string' || rec.cwd.length === 0) continue;
+      try { managedSpawnCwds.push(path.resolve(rec.cwd)); }
+      catch (_e) { /* malformed cwd — skip */ }
+    }
+  } catch (_e) { /* optional */ }
+
+  const result = { scanned: 0, kept: 0, evicted: 0, failed: 0, prunedRegistry: 0, perProject: {} };
+  const _seenAbs = new Set(); // dedup across projects sharing a parent
+
+  for (const project of projects) {
+    if (!project || !project.localPath) continue;
+    let rootDir;
+    try { rootDir = path.resolve(String(project.localPath)); } catch { continue; }
+    let rootExists = false;
+    try { rootExists = _fs.existsSync(rootDir); } catch { rootExists = false; }
+    if (!rootExists) continue;
+
+    // Compute the inside-`worktreeRoot` boundary so we DON'T double-sweep the
+    // dirs the existing scanner already handles.
+    const wtParentAbs = path.resolve(rootDir, worktreeRootRel);
+    const wtParentPrefix = wtParentAbs + path.sep;
+
+    const projStats = { scanned: 0, kept: 0, evicted: 0, failed: 0, prunedRegistry: 0 };
+    let raw = '';
+    try {
+      raw = String(_execSilent('git --no-optional-locks worktree list --porcelain', {
+        cwd: rootDir, timeout: 15000, windowsHide: true,
+      }) || '');
+    } catch (e) {
+      log('warn', `worktree-gc: git worktree list failed for ${project.name || rootDir}: ${e.message}`);
+      result.perProject[project.name || rootDir] = projStats;
+      continue;
+    }
+
+    let trees;
+    try { trees = _parseWorktreePorcelain(raw); }
+    catch (e) {
+      log('warn', `worktree-gc: parse worktree list failed for ${project.name || rootDir}: ${e.message}`);
+      result.perProject[project.name || rootDir] = projStats;
+      continue;
+    }
+
+    for (const wt of trees) {
+      if (!wt || !wt.path) continue;
+      let wtAbs;
+      try { wtAbs = path.resolve(wt.path); } catch { continue; }
+      // Skip main checkout
+      if (wtAbs === rootDir) continue;
+      // Skip dirs inside the configured worktreeRoot (handled by sibling scanner)
+      if (wtAbs === wtParentAbs || wtAbs.startsWith(wtParentPrefix)) continue;
+      if (_seenAbs.has(wtAbs)) continue;
+      _seenAbs.add(wtAbs);
+
+      projStats.scanned++;
+      result.scanned++;
+
+      // Branch protection
+      if (wt.branch && protectedBranches.has(String(wt.branch).toLowerCase())) {
+        projStats.kept++; result.kept++; continue;
+      }
+      // Pool protection
+      const normPath = worktreePool._normalizePath(wtAbs);
+      if (poolPaths.has(normPath)) {
+        projStats.kept++; result.kept++; continue;
+      }
+      // managed_spawn anchor protection
+      if (managedSpawnCwds.length > 0) {
+        const wtPrefix = wtAbs + path.sep;
+        let anchored = false;
+        for (const cwd of managedSpawnCwds) {
+          if (cwd === wtAbs || cwd.startsWith(wtPrefix)) { anchored = true; break; }
+        }
+        if (anchored) { projStats.kept++; result.kept++; continue; }
+      }
+
+      // Slow-cadence gate for already-escalated stuck paths
+      const slowRetryMs = (opts.config?.engine?.worktreeStuckSlowRetryMs)
+        ?? shared.ENGINE_DEFAULTS.worktreeStuckSlowRetryMs
+        ?? (30 * 60 * 1000);
+      if (!_shouldSlowRetry(wtAbs, slowRetryMs)) {
+        projStats.kept++; result.kept++; continue;
+      }
+
+      // parentDir for the safety boundary check inside removeWorktree must be
+      // the dir *containing* this worktree (not the project's worktreeRoot,
+      // since that's not where this dir lives).
+      const parentDir = path.dirname(wtAbs);
+      const suppressed = _isStuckPathSuppressed(wtAbs);
+      try {
+        const removed = _removeWorktree(wtAbs, rootDir, parentDir);
+        if (removed) {
+          projStats.evicted++; result.evicted++;
+          _markStuckSuccess(wtAbs, { writeToInbox: opts.writeToInbox });
+          try { shared.bumpWorktreeGcMetric('outOfRootEvicted'); } catch { /* optional */ }
+          log('info', `worktree-gc: out-of-root evicted ${wtAbs} for project ${project.name || 'default'}`);
+        } else {
+          projStats.failed++; result.failed++;
+          const { alreadyEscalated } = _maybeEscalateStuck(wtAbs, 'remove returned false', { config: opts.config, writeToInbox: opts.writeToInbox });
+          if (!alreadyEscalated && !suppressed) {
+            log('warn', `worktree-gc: out-of-root remove returned false for ${wtAbs}`);
+          }
         }
       } catch (rmErr) {
         projStats.failed++; result.failed++;
-        log('warn', `worktree-gc: boot-evict threw for ${wtPath}: ${rmErr.message}`);
+        const { alreadyEscalated } = _maybeEscalateStuck(wtAbs, rmErr && rmErr.message, { config: opts.config, writeToInbox: opts.writeToInbox });
+        if (!alreadyEscalated && !suppressed) {
+          log('warn', `worktree-gc: out-of-root remove threw for ${wtAbs}: ${rmErr.message}`);
+        }
       }
     }
+
+    // Always finish with `git worktree prune --expire=now` to drop registry
+    // entries whose dirs were manually removed (e.g. operator `Remove-Item`).
+    try {
+      _execSilent('git worktree prune --expire=now', {
+        cwd: rootDir, timeout: 10000, windowsHide: true,
+      });
+      // We can't tell how many entries pruned without a second `worktree list`
+      // diff; count the call itself for cadence visibility.
+      projStats.prunedRegistry = 1;
+      result.prunedRegistry++;
+      try { shared.bumpWorktreeGcMetric('registryPruned'); } catch { /* optional */ }
+    } catch (e) {
+      log('warn', `worktree-gc: git worktree prune failed for ${project.name || rootDir}: ${e.message}`);
+    }
+
     result.perProject[project.name || rootDir] = projStats;
   }
+
   return result;
 }
 
@@ -357,4 +724,8 @@ module.exports = {
   shouldGcDispatchWorktree,
   gcDispatchWorktreeIfOrphan,
   pruneOrphanWorktrees,
+  pruneOrphanWorktreesFromGitRegistry,
+  // exported for testing (W-mq5o6bvy000x7191)
+  _resetStuckPathsForTesting,
+  _stuckPaths,
 };

package/engine.js

@@ -5018,6 +5018,23 @@ function _warnSilentDiscoveryOnce(kind, project, dataPath, config) {
   log('warn', `Silent-discovery footgun: project "${projName}" has ${count} record(s) in ${path.basename(dataPath)} but workSources.${kind}.enabled is not true — engine will not pick them up. ${hint}`);
 }
 
+/**
+ * W-mq5rs2eq000da8a9 — in-process dedupe set for PR dispatch-skip log lines.
+ * Keyed by `${prId}:${reason}` so each (PR, reason) combination logs at most
+ * once per engine process. Cleared only on engine restart — no persistence
+ * needed; the goal is operator visibility into WHY a tracked PR is being
+ * skipped (replaces the silent `continue` that hid the `_autoObserve` bug).
+ */
+const _prDispatchSkipLogged = new Set();
+
+function _logPrDispatchSkipOnce(pr, reason) {
+  const prId = pr?.id || pr?.url || '<unknown-pr>';
+  const key = `${prId}:${reason}`;
+  if (_prDispatchSkipLogged.has(key)) return;
+  _prDispatchSkipLogged.add(key);
+  log('info', `Discovery: skipping PR ${prId} (${reason}) — not eligible for auto-managed review/fix dispatch`);
+}
+
 /**
  * Scan pull-requests.json for PRs needing review or fixes
  */
@@ -5059,9 +5076,12 @@ async function discoverFromPrs(config, project) {
       .filter(Boolean)
   );
 
-  const knownAgents = new Set(Object.keys(config.agents || {}));
   for (const pr of prs) {
-    if (pr.status !== PR_STATUS.ACTIVE || pr._contextOnly) continue;
+    if (pr.status !== PR_STATUS.ACTIVE) continue;
+    if (pr._contextOnly) {
+      _logPrDispatchSkipOnce(pr, 'context-only');
+      continue;
+    }
     if (!shared.isPrCompatibleWithProject(project, pr, pr.url || '')) continue;
     const prDisplayId = shared.getPrDisplayId(pr);
     const prCanonicalId = shared.getCanonicalPrId(project, pr, pr.url || '');
@@ -5072,10 +5092,15 @@ async function discoverFromPrs(config, project) {
       log('info', `Branch mutex: skipping PR ${pr.id} dispatch — branch ${prBranchForMutex} locked by another agent`);
       continue;
     }
-    // Skip human-authored PRs not linked to any work item — only auto-manage agent PRs
-    // Manually-linked PRs with autoObserve=true (_manual && !_contextOnly) are allowed through
-    const isAgentPr = knownAgents.has((pr.agent || '').toLowerCase()) || (pr.prdItems && pr.prdItems.length > 0) || (pr._manual && !pr._contextOnly);
-    if (!isAgentPr) continue;
+    // Auto-managed gate: single source of truth in engine/shared.js.
+    // Honors prdItems, _autoObserve, sourcePlan/itemType, and any non-empty
+    // non-'human' agent author. See W-mq5rs2eq000da8a9 for the bug fix —
+    // the prior inline `knownAgents.has(...) || prdItems || (_manual && !_contextOnly)`
+    // silently dropped PRs with `_autoObserve: true` + human author.
+    if (!shared.isAutoManagedPrRecord(pr)) {
+      _logPrDispatchSkipOnce(pr, 'not-auto-managed');
+      continue;
+    }
 
     const prNumber = shared.getPrNumber(pr);
     // Use reviewStatus as single source of truth (synced from ADO/GitHub votes)
@@ -7530,6 +7555,28 @@ async function tickInner() {
     if (_isTickStale(myGeneration)) return;
   }
 
+  // 2.54. Periodic worktree GC sweep (W-mq5o6bvy000x7191). Catches dirs the
+  // dispatch-end gcDispatchWorktreeIfOrphan couldn't remove (typically Windows
+  // file locks: EPERM/EBUSY on lingering spawn-agent.exe handles, AV scans,
+  // node_modules\.bin shims). Delegates to `cleanup.runPeriodicWorktreeSweep`,
+  // which runs the two pruners in `engine/worktree-gc.js` against a single
+  // shared `dispatchSnap`: (1) in-root `pruneOrphanWorktrees` and (2)
+  // out-of-root `pruneOrphanWorktreesFromGitRegistry` (catches `git worktree
+  // list` entries outside `worktreeRoot`). Runs at worktreePruneIntervalTicks
+  // cadence (default 30 ticks ~= 5 min).
+  const wtPruneEvery = Math.max(1, ENGINE_DEFAULTS.worktreePruneIntervalTicks || 30);
+  if (tickCount % wtPruneEvery === 0) {
+    safe('pruneWorktreesPeriodic', () => {
+      const { runPeriodicWorktreeSweep } = require('./engine/cleanup');
+      const stats = runPeriodicWorktreeSweep(config);
+      const totalEvicted = (stats.evicted || 0) + (stats.outOfRootEvicted || 0);
+      if (totalEvicted > 0 || stats.failed > 0) {
+        log('info', `worktree-prune sweep: scanned=${stats.scanned} evicted=${stats.evicted} outOfRootEvicted=${stats.outOfRootEvicted} kept=${stats.kept} failed=${stats.failed} prunedRegistry=${stats.prunedRegistry}`);
+      }
+    });
+    if (_isTickStale(myGeneration)) return;
+  }
+
   // 2.55. Check persistent watches (~3 min — cadence in ENGINE_DEFAULTS.watchPollEvery)
   const watchPollIntervalMs = _pollIntervalMsFromTicks(ENGINE_DEFAULTS.watchPollEvery || 18, tickIntervalMs);
   if (_shouldRunPeriodicPhase(now, lastWatchCheckAt, watchPollIntervalMs)) {

package/package.json

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