@yemi33/minions 0.1.2424 → 0.1.2425

package/engine/worktree-gc.js

@@ -27,6 +27,9 @@ const path = require('path');
 const shared = require('./shared');
 const worktreePool = require('./worktree-pool');
 
+const DEFAULT_ORPHAN_RETENTION_MS = 2 * 60 * 60 * 1000;
+const DEFAULT_QUARANTINE_RETENTION_MS = 24 * 60 * 60 * 1000;
+
 let keepProcessSweep = null;
 function _keepProcessSweep() {
   if (!keepProcessSweep) keepProcessSweep = require('./keep-process-sweep');
@@ -41,20 +44,29 @@ function _managedSpawn() {
 
 const _noopLog = () => {};
 
-function _collectAnchoredCwds(listManagedSpecs, listKeepProcessCwds) {
+function _pathIsLiveFailOpen(checkFn, worktreePath, opts) {
+  try { return !!checkFn(worktreePath, opts); }
+  catch { return true; }
+}
+
+function _collectAnchoredCwds(listManagedSpecs, listKeepProcessCwds, opts = {}) {
   const out = [];
   try {
     for (const rec of (listManagedSpecs() || [])) {
       if (!rec || typeof rec.cwd !== 'string' || !rec.cwd) continue;
       try { out.push(shared.realPathForComparison(rec.cwd)); } catch {}
     }
-  } catch {}
+  } catch (err) {
+    if (opts.throwOnFailure) throw err;
+  }
   try {
     for (const cwd of (listKeepProcessCwds() || [])) {
       if (typeof cwd !== 'string' || !cwd) continue;
       try { out.push(shared.realPathForComparison(cwd)); } catch {}
     }
-  } catch {}
+  } catch (err) {
+    if (opts.throwOnFailure) throw err;
+  }
   return out;
 }
 
@@ -67,6 +79,51 @@ function _isWorktreeCwdAnchored(worktreePath, anchoredCwds) {
   return false;
 }
 
+function _isQuarantineDirName(name) {
+  return /-quarantine-(?:protected-)?\d+(?:$|-)/.test(String(name || ''));
+}
+
+function _quarantineCreatedAt(name, fallbackMs) {
+  const match = String(name || '').match(/-quarantine-(?:protected-)?(\d+)(?:$|-)/);
+  if (!match) return fallbackMs;
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallbackMs;
+}
+
+function isLegacyMinionsWorktreeDir(worktreePath, commonGitDir, opts = {}) {
+  const _fs = opts.fs || fs;
+  if (!worktreePath || !commonGitDir) return false;
+  const name = path.basename(path.resolve(worktreePath));
+  if (!/^W-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) return false;
+  const dotGit = path.join(worktreePath, '.git');
+  let stat;
+  try { stat = _fs.lstatSync(dotGit); } catch { return false; }
+  if (!stat || !stat.isFile()) return false;
+  let raw;
+  try { raw = String(_fs.readFileSync(dotGit, 'utf8')); } catch { return false; }
+  const match = raw.match(/^gitdir:\s*(.+?)\s*$/im);
+  if (!match) return false;
+  let gitdir;
+  try {
+    gitdir = path.resolve(worktreePath, match[1].trim());
+  } catch {
+    return false;
+  }
+  const commonWorktrees = worktreePool._normalizePath(path.join(commonGitDir, 'worktrees'));
+  const candidate = worktreePool._normalizePath(gitdir);
+  return !!candidate && candidate.startsWith(commonWorktrees + '/');
+}
+
+function _resolveGitCommonDir(rootDir, execSilent) {
+  const raw = String(execSilent('git rev-parse --git-common-dir', {
+    cwd: rootDir,
+    timeout: 10000,
+    windowsHide: true,
+  }) || '').trim();
+  if (!raw) return null;
+  return path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(rootDir, raw);
+}
+
 // ── 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
@@ -333,7 +390,7 @@ function _resetStuckPathsForTesting() { _stuckPaths.clear(); }
 // OS to release the killed processes' file handles, then attempts ONE more
 // removal. On success, writes the recovered-via-holder-reap note via
 // `_markStuckSuccess` with the reaped-pid attribution.
-function _postReapRetry(wtPath, gitRoot, parentDir, resolvedPath, _removeWorktree, opts, projStats, result, log, reapedPids) {
+function _postReapRetry(wtPath, gitRoot, parentDir, resolvedPath, _removeWorktree, opts, stats, log, reapedPids) {
   try { shared.clearWorktreeFailureCache(resolvedPath); } catch { /* optional */ }
 
   // The actual removal attempt, run after the settle window.
@@ -343,8 +400,12 @@ function _postReapRetry(wtPath, gitRoot, parentDir, resolvedPath, _removeWorktre
       if (removed) {
         // Down-count the failure we recorded just before; this dispatch
         // ultimately succeeded after the auto-reap.
-        if (projStats) { projStats.failed = Math.max(0, projStats.failed - 1); projStats.evicted++; }
-        if (result) { result.failed = Math.max(0, result.failed - 1); result.evicted++; }
+        for (const stat of stats) {
+          if (!stat) continue;
+          if (typeof stat.failed === 'number') stat.failed = Math.max(0, stat.failed - 1);
+          if (typeof stat.evicted === 'number') stat.evicted++;
+          if (typeof stat.removed === 'number') stat.removed++;
+        }
         _markStuckSuccess(resolvedPath, {
           writeToInbox: opts.writeToInbox,
           recoveryReason: 'holder-reap',
@@ -378,13 +439,16 @@ function _postReapRetry(wtPath, gitRoot, parentDir, resolvedPath, _removeWorktre
   try { settled = sleepFn(2000); } catch { /* sleep init failure — fire retry anyway */ }
 
   if (settled && typeof settled.then === 'function') {
-    // Async settle window — fire-and-forget; never blocks the event loop.
-    settled.then(() => { try { _doRetry(); } catch { /* ignore */ } }).catch(() => {});
-    return;
+    // Async settle window — callers may observe completion without blocking
+    // the tick that scheduled it.
+    return Promise.resolve(settled)
+      .then(() => _doRetry(), () => false)
+      .catch(() => false);
   }
 
   // Sync settle window (test injection) — fire retry immediately.
   try { _doRetry(); } catch { /* ignore */ }
+  return null;
 }
 
 /**
@@ -424,7 +488,8 @@ function _postReapRetry(wtPath, gitRoot, parentDir, resolvedPath, _removeWorktre
  * matching gcDispatchWorktreeIfOrphan's existing contract. When `stats`
  * objects are supplied the helper mutates their evicted/failed/kept counters
  * directly (the sweeps); the dispatch-end caller passes none and maps the
- * return value instead.
+ * return value instead. Async post-reap completions are appended to an
+ * optional `deferredRetries` collector for aggregate callers.
  */
 function reapAndRemoveWorktree(opts) {
   const {
@@ -449,6 +514,7 @@ function reapAndRemoveWorktree(opts) {
     sleepSyncFn = null,
     // accounting + logging
     stats = [],
+    deferredRetries = null,
     successReason = 'orphan',
     successMetric = null,
     recheckSuppressedAfterEscalate = false,
@@ -472,6 +538,7 @@ function reapAndRemoveWorktree(opts) {
   if (typeof slowRetryMs === 'number') {
     if (!_shouldSlowRetry(resolved, slowRetryMs)) {
       _bumpStats('kept');
+      _bumpStats('skipped');
       return { ..._idle(), reason: 'slow-retry' };
     }
   }
@@ -483,6 +550,7 @@ function reapAndRemoveWorktree(opts) {
     catch (_e) { owned = false; }
     if (!owned) {
       _bumpStats('kept');
+      _bumpStats('preserved');
       if (typeof onMarkerSkipLog === 'function') log('debug', onMarkerSkipLog());
       return { ..._idle(), reason: 'no-marker' };
     }
@@ -512,12 +580,21 @@ function reapAndRemoveWorktree(opts) {
     return !escResult.alreadyEscalated && !suppressed;
   };
   const _postReapOpts = { writeToInbox, sleepSyncFn };
+  const _queuePostReapRetry = (reapedPids) => {
+    if (!enablePostReapRetry || reapedPids.length === 0) return;
+    const completion = _postReapRetry(
+      worktreePath, gitRoot, parentDir, resolved, _removeFn,
+      _postReapOpts, stats, log, reapedPids
+    );
+    if (completion && Array.isArray(deferredRetries)) deferredRetries.push(completion);
+  };
 
   // (4)+(5) remove + accounting. removeWorktree owns its own backoff loop.
   try {
     const removed = _removeFn(worktreePath, gitRoot, parentDir, rmOpts);
     if (removed) {
       _bumpStats('evicted');
+      _bumpStats('removed');
       _markStuckSuccess(resolved, { writeToInbox });
       if (successMetric) { try { shared.bumpWorktreeGcMetric(successMetric); } catch { /* optional */ } }
       if (typeof onRemovedLog === 'function') log('info', onRemovedLog());
@@ -527,18 +604,14 @@ function reapAndRemoveWorktree(opts) {
     const escResult = _maybeEscalateStuck(resolved, 'remove returned false', _escalateOpts);
     if (_shouldWarn(escResult) && typeof onFailLog === 'function') log('warn', onFailLog('false'));
     const reapedPids = escResult.reapedPids || [];
-    if (enablePostReapRetry && reapedPids.length > 0) {
-      _postReapRetry(worktreePath, gitRoot, parentDir, resolved, _removeFn, _postReapOpts, stats[0] || null, stats[1] || null, log, reapedPids);
-    }
+    _queuePostReapRetry(reapedPids);
     return { outcome: 'gc-failed', removed: false, reason: 'remove-failed', escalated: escResult.escalated, stuckEscalated: escResult.escalated, reapedPids };
   } catch (rmErr) {
     _bumpStats('failed');
     const escResult = _maybeEscalateStuck(resolved, rmErr && rmErr.message, _escalateOpts);
     if (_shouldWarn(escResult) && typeof onFailLog === 'function') log('warn', onFailLog('threw', rmErr && rmErr.message));
     const reapedPids = escResult.reapedPids || [];
-    if (enablePostReapRetry && reapedPids.length > 0) {
-      _postReapRetry(worktreePath, gitRoot, parentDir, resolved, _removeFn, _postReapOpts, stats[0] || null, stats[1] || null, log, reapedPids);
-    }
+    _queuePostReapRetry(reapedPids);
     return { outcome: 'gc-failed', removed: false, reason: 'remove-threw', escalated: escResult.escalated, stuckEscalated: escResult.escalated, reapedPids };
   }
 }
@@ -613,7 +686,10 @@ function shouldGcDispatchWorktree(opts) {
     return { gc: false, reason: 'managed-spawn-anchored' };
   }
 
-  // keep_processes anchor check: any live PID for this agent → skip.
+  // keep_processes anchor check: only live PIDs whose declared cwd is inside
+  // this worktree protect it. An agent can leave a process from an older
+  // dispatch alive, so an agent-wide PID match alone is not a path anchor.
+  // Legacy records without cwd remain fail-open and retain the worktree.
   if (agentId) {
     try {
       const fn = typeof getActiveAnchorPidsForAgent === 'function'
@@ -621,7 +697,19 @@ function shouldGcDispatchWorktree(opts) {
         : _keepProcessSweep().getActiveAnchorPidsForAgent;
       const res = fn(agentId);
       if (res && res.pids && res.pids.size > 0) {
-        return { gc: false, reason: 'keep-processes-anchored' };
+        const anchorCwd = res.record && typeof res.record.cwd === 'string'
+          ? res.record.cwd
+          : '';
+        if (!anchorCwd) {
+          return { gc: false, reason: 'keep-processes-anchored' };
+        }
+        try {
+          if (shared.isPathInsideOrEqual(anchorCwd, worktreePath)) {
+            return { gc: false, reason: 'keep-processes-anchored' };
+          }
+        } catch (_e) {
+          return { gc: false, reason: 'keep-processes-anchored' };
+        }
       }
     } catch (_e) { /* sidecar reader optional */ }
   }
@@ -718,6 +806,404 @@ function gcDispatchWorktreeIfOrphan(opts) {
   return { outcome: 'gc-failed', reason: r.reason, removed: false, stuckEscalated: r.stuckEscalated };
 }
 
+/**
+ * Reconcile each configured worktree root against Git's registry and remove
+ * stale on-disk residue that registry-derived GC cannot see. This pass is
+ * intentionally narrower than pruneOrphanWorktrees:
+ *
+ *   - registered paths are not deleted here; only locked/initializing entries
+ *     are protected from the downstream dispatch-oriented pruner;
+ *   - active SQL claims, pool entries, process anchors, and cwd holders are
+ *     preserved;
+ *   - ownership requires the marker, or a legacy Windows W-* name whose .git
+ *     pointer targets this project's common .git/worktrees directory;
+ *   - ordinary residue waits two hours; quarantine residue waits 24 hours;
+ *   - any Git registration-list failure skips the entire shared root.
+ */
+function reconcileStaleWorktreeDirectories(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 _execSilent = typeof opts.execSilent === 'function' ? opts.execSilent : shared.execSilent;
+  const _parseWorktreePorcelain = typeof opts.parseWorktreePorcelain === 'function'
+    ? opts.parseWorktreePorcelain
+    : shared.parseWorktreePorcelain;
+  const _removeWorktree = typeof opts.removeWorktree === 'function'
+    ? opts.removeWorktree
+    : shared.removeWorktree;
+  const _hasOwnerMarker = typeof opts.hasOwnerMarker === 'function'
+    ? opts.hasOwnerMarker
+    : shared.hasWorktreeOwnerMarker;
+  const _writeOwnerMarker = typeof opts.writeOwnerMarker === 'function'
+    ? opts.writeOwnerMarker
+    : shared.writeWorktreeOwnerMarker;
+  const _hasProtectedQuarantineMarker = typeof opts.hasProtectedQuarantineMarker === 'function'
+    ? opts.hasProtectedQuarantineMarker
+    : shared.hasProtectedQuarantineMarker;
+  const _isWorktreePathLive = typeof opts.isWorktreePathLive === 'function'
+    ? opts.isWorktreePathLive
+    : shared.isWorktreePathLive;
+  const _findProcessesWithCwdInside = typeof opts.findProcessesWithCwdInside === 'function'
+    ? opts.findProcessesWithCwdInside
+    : (process.platform === 'win32' && typeof shared.findProcessCwdHolders === 'function'
+      ? shared.findProcessCwdHolders
+      : shared.findProcessesWithCwdInside);
+  const _resolveCommonDir = typeof opts.resolveGitCommonDir === 'function'
+    ? opts.resolveGitCommonDir
+    : (rootDir) => _resolveGitCommonDir(rootDir, _execSilent);
+  const _parsedTreesByProject = opts.parsedTreesByProject instanceof Map
+    ? opts.parsedTreesByProject
+    : null;
+  const _liveOpts = opts.db ? { db: opts.db } : undefined;
+  const now = Number.isFinite(Number(opts.now)) ? Number(opts.now) : Date.now();
+  const orphanRetentionMs = Math.max(0,
+    Number.isFinite(Number(opts.orphanRetentionMs))
+      ? Number(opts.orphanRetentionMs)
+      : DEFAULT_ORPHAN_RETENTION_MS);
+  const quarantineRetentionMs = Math.max(0,
+    Number.isFinite(Number(opts.quarantineRetentionMs))
+      ? Number(opts.quarantineRetentionMs)
+      : DEFAULT_QUARANTINE_RETENTION_MS);
+
+  const result = {
+    scanned: 0,
+    removed: 0,
+    kept: 0,
+    failed: 0,
+    registered: 0,
+    skippedLive: 0,
+    pooled: 0,
+    anchored: 0,
+    processHeld: 0,
+    recent: 0,
+    foreign: 0,
+    protected: 0,
+    perRoot: {},
+  };
+  const protectedPaths = new Set();
+  const failedRoots = new Set();
+  Object.defineProperties(result, {
+    protectedPaths: { value: protectedPaths, enumerable: false },
+    failedRoots: { value: failedRoots, enumerable: false },
+  });
+
+  const groups = new Map();
+  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; }
+    const wtParent = path.resolve(rootDir, worktreeRootRel);
+    let parentExists = false;
+    try { parentExists = _fs.existsSync(wtParent); } catch { parentExists = false; }
+    if (!parentExists) continue;
+    const key = worktreePool._normalizePath(wtParent);
+    if (!groups.has(key)) groups.set(key, { wtParent, projects: [] });
+    const group = groups.get(key);
+    if (!group.projects.some((entry) => entry.rootDir === rootDir)) {
+      group.projects.push({ project, rootDir, rootExists });
+    }
+  }
+
+  const globalLiveDirNames = new Set();
+  for (const dispatch of [...(dispatchSnap.active || []), ...(dispatchSnap.pending || [])]) {
+    if (!dispatch) continue;
+    if (dispatch.worktreePath) {
+      try { globalLiveDirNames.add(path.basename(path.resolve(dispatch.worktreePath))); } catch {}
+    }
+    if (!dispatch.id || !dispatch.meta?.branch) continue;
+    const projectName = typeof dispatch.meta.project === 'string'
+      ? dispatch.meta.project
+      : (dispatch.meta.project?.name || 'default');
+    try {
+      globalLiveDirNames.add(shared.buildWorktreeDirName({
+        dispatchId: dispatch.id,
+        projectName,
+        branchName: dispatch.meta.branch,
+      }));
+    } catch {}
+  }
+
+  const poolPaths = new Set();
+  let poolReadError = null;
+  try {
+    for (const entry of (worktreePool.readPool() || { entries: [] }).entries || []) {
+      if (entry?.path) poolPaths.add(worktreePool._normalizePath(entry.path));
+    }
+  } catch (err) {
+    poolReadError = err;
+  }
+  if (Array.isArray(opts.extraPoolPaths)) {
+    for (const candidate of opts.extraPoolPaths) {
+      poolPaths.add(worktreePool._normalizePath(candidate));
+    }
+  }
+  if (poolReadError) {
+    for (const group of groups.values()) {
+      failedRoots.add(worktreePool._normalizePath(group.wtParent));
+    }
+    result.failed = groups.size || 1;
+    log('warn', `worktree-reconcile: pool state unavailable (${poolReadError.message}) — fail-closed`);
+    return result;
+  }
+  const listManagedSpecs = typeof opts.listManagedSpecs === 'function'
+    ? opts.listManagedSpecs
+    : (() => _managedSpawn().listManagedSpecs());
+  const listKeepProcessCwds = typeof opts.listKeepProcessCwds === 'function'
+    ? opts.listKeepProcessCwds
+    : (() => _keepProcessSweep().getActiveKeepProcessCwds());
+  let anchoredCwds;
+  try {
+    anchoredCwds = _collectAnchoredCwds(
+      listManagedSpecs,
+      listKeepProcessCwds,
+      { throwOnFailure: true },
+    );
+  } catch (err) {
+    for (const group of groups.values()) {
+      failedRoots.add(worktreePool._normalizePath(group.wtParent));
+    }
+    result.failed = groups.size || 1;
+    log('warn', `worktree-reconcile: process anchor state unavailable (${err.message}) — fail-closed`);
+    return result;
+  }
+
+  for (const group of groups.values()) {
+    const stats = {
+      scanned: 0, removed: 0, kept: 0, failed: 0,
+      registered: 0, skippedLive: 0, pooled: 0, anchored: 0,
+      processHeld: 0, recent: 0, foreign: 0, protected: 0,
+    };
+    result.perRoot[group.wtParent] = stats;
+    const keep = (kind, candidate, protectDownstream = true) => {
+      if (kind) {
+        stats[kind]++;
+        result[kind]++;
+      }
+      stats.kept++;
+      result.kept++;
+      if (candidate && protectDownstream) protectedPaths.add(worktreePool._normalizePath(candidate));
+    };
+    const registeredPaths = new Set();
+    const lockedRegisteredPaths = new Set();
+    const commonGitDirs = [];
+    let registrationError = null;
+    let holderSnapshot = null;
+    let holderProbeError = null;
+    let holderProbeAttempted = false;
+    const isProcessHeld = (candidate) => {
+      if (!holderProbeAttempted) {
+        holderProbeAttempted = true;
+        try {
+          holderSnapshot = _findProcessesWithCwdInside(group.wtParent, {
+            timeoutMs: process.platform === 'win32'
+              ? (opts.config?.engine?.statusProbeKillTimeoutMs
+                ?? shared.ENGINE_DEFAULTS.statusProbeKillTimeoutMs)
+              : (opts.config?.engine?.orphanHolderScanTimeoutMs
+                ?? shared.ENGINE_DEFAULTS.orphanHolderScanTimeoutMs),
+            throwOnFailure: true,
+          }) || [];
+        } catch (err) {
+          holderProbeError = err;
+          stats.failed++;
+          result.failed++;
+          log('warn', `worktree-reconcile: holder probe failed for ${group.wtParent}: ${err.message}`);
+        }
+      }
+      if (holderProbeError) return true;
+      return holderSnapshot.some((holder) => {
+        if (!holder?.cwd) return true;
+        try { return shared.isPathInsideOrEqual(holder.cwd, candidate); }
+        catch { return true; }
+      });
+    };
+
+    for (const { project, rootDir, rootExists } of group.projects) {
+      let trees;
+      try {
+        if (!rootExists) {
+          throw new Error(`configured project localPath does not exist: ${rootDir}`);
+        }
+        if (_parsedTreesByProject && _parsedTreesByProject.has(rootDir)) {
+          trees = _parsedTreesByProject.get(rootDir);
+        } else {
+          const raw = String(_execSilent('git --no-optional-locks worktree list --porcelain', {
+            cwd: rootDir,
+            timeout: 15000,
+            windowsHide: true,
+          }) || '');
+          trees = _parseWorktreePorcelain(raw);
+        }
+        if (!Array.isArray(trees)) throw new Error('worktree registry parser did not return an array');
+        for (const tree of trees) {
+          if (!tree?.path) continue;
+          const normalized = worktreePool._normalizePath(tree.path);
+          registeredPaths.add(normalized);
+          if (tree.locked) lockedRegisteredPaths.add(normalized);
+        }
+      } catch (err) {
+        registrationError = err;
+        log('warn', `worktree-reconcile: registry list failed for ${project.name || rootDir}: ${err.message}`);
+        break;
+      }
+      try {
+        const commonDir = _resolveCommonDir(rootDir, project);
+        if (commonDir) commonGitDirs.push(path.resolve(commonDir));
+      } catch (err) {
+        log('debug', `worktree-reconcile: common git dir unavailable for ${project.name || rootDir}: ${err.message}`);
+      }
+    }
+
+    if (registrationError) {
+      stats.failed++;
+      result.failed++;
+      failedRoots.add(worktreePool._normalizePath(group.wtParent));
+      try { shared.bumpWorktreeGcMetric('reconcileFailures'); } catch {}
+      if (typeof opts.writeToInbox === 'function') {
+        try {
+          const rootSlug = path.basename(group.wtParent).replace(/[^a-zA-Z0-9._-]+/g, '-');
+          opts.writeToInbox('engine', `worktree-reconcile-failed-${rootSlug}`, [
+            '# Worktree filesystem reconciliation failed closed',
+            '',
+            `**Worktree root:** ${group.wtParent}`,
+            `**Error:** ${registrationError.message}`,
+            '',
+            'No directories were removed because Git registrations could not be enumerated safely.',
+          ].join('\n'));
+        } catch {}
+      }
+      continue;
+    }
+
+    let entries;
+    try {
+      entries = _fs.readdirSync(group.wtParent, { withFileTypes: true });
+    } catch (err) {
+      stats.failed++;
+      result.failed++;
+      failedRoots.add(worktreePool._normalizePath(group.wtParent));
+      log('warn', `worktree-reconcile: readdir failed for ${group.wtParent}: ${err.message}`);
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry || (typeof entry.isDirectory === 'function' && !entry.isDirectory())) continue;
+      const name = entry.name || entry;
+      if (typeof name !== 'string' || !name || shared.isWorktreeRootInfraEntry(name)) continue;
+      const candidate = path.resolve(group.wtParent, name);
+      if (!candidate.startsWith(group.wtParent + path.sep)) continue;
+      stats.scanned++;
+      result.scanned++;
+
+      const normalized = worktreePool._normalizePath(candidate);
+      if (lockedRegisteredPaths.has(normalized)) {
+        keep('registered', candidate);
+        continue;
+      }
+      if (globalLiveDirNames.has(name) || _pathIsLiveFailOpen(_isWorktreePathLive, candidate, _liveOpts)) {
+        keep('skippedLive', candidate);
+        continue;
+      }
+      if (poolPaths.has(normalized)) {
+        keep('pooled', candidate);
+        continue;
+      }
+      if (_isWorktreeCwdAnchored(candidate, anchoredCwds)) {
+        keep('anchored', candidate);
+        continue;
+      }
+      let protectedQuarantine = true;
+      try { protectedQuarantine = !!_hasProtectedQuarantineMarker(candidate); } catch {}
+      if (protectedQuarantine) {
+        keep('protected', candidate);
+        continue;
+      }
+
+      let owned = false;
+      let legacyOwned = false;
+      try { owned = !!_hasOwnerMarker(candidate); } catch {}
+      if (!owned) {
+        for (const commonGitDir of commonGitDirs) {
+          if (isLegacyMinionsWorktreeDir(candidate, commonGitDir, { fs: _fs })) {
+            owned = true;
+            legacyOwned = true;
+            break;
+          }
+        }
+      }
+      if (!owned) {
+        keep('foreign', candidate);
+        continue;
+      }
+      let stat;
+      try { stat = _fs.statSync(candidate); }
+      catch {
+        keep(null, candidate);
+        continue;
+      }
+      const quarantine = _isQuarantineDirName(name);
+      const createdAt = quarantine
+        ? _quarantineCreatedAt(name, stat.mtimeMs)
+        : stat.mtimeMs;
+      const retentionMs = quarantine ? quarantineRetentionMs : orphanRetentionMs;
+      if ((now - createdAt) < retentionMs) {
+        keep('recent', candidate);
+        continue;
+      }
+
+      // Adopt legacy residue immediately before deletion. The pre-adoption
+      // stat above keeps the original retention clock; the marker makes a
+      // partially removed husk provably owned on the next retry.
+      if (legacyOwned && !_writeOwnerMarker(candidate, { reconciledLegacy: true })) {
+        stats.failed++; result.failed++;
+        keep('foreign', candidate);
+        log('warn', `worktree-reconcile: could not stamp legacy ownership marker for ${candidate}; preserving`);
+        continue;
+      }
+
+      if (isProcessHeld(candidate)) {
+        if (holderProbeError) {
+          keep(null, candidate);
+        } else {
+          keep('processHeld', candidate);
+        }
+        continue;
+      }
+      if (registeredPaths.has(normalized)) {
+        // Preserve here without shielding safe, unlocked registrations from downstream pruning.
+        keep('registered', candidate, false);
+        continue;
+      }
+
+      try {
+        const rootDir = group.projects[0].rootDir;
+        const removed = _removeWorktree(candidate, rootDir, group.wtParent, {
+          config: opts.config,
+        });
+        if (removed) {
+          stats.removed++; result.removed++;
+          try { shared.bumpWorktreeGcMetric('reconciledStaleDirs'); } catch {}
+          log('info', `worktree-reconcile: removed stale unregistered directory ${candidate}`);
+        } else {
+          stats.failed++; result.failed++;
+          log('warn', `worktree-reconcile: removeWorktree declined ${candidate}`);
+        }
+      } catch (err) {
+        stats.failed++; result.failed++;
+        log('warn', `worktree-reconcile: removal failed for ${candidate}: ${err.message}`);
+      }
+    }
+  }
+
+  return result;
+}
+
 /**
  * Walk each project's worktree root and evict orphan W-* dirs.
  *
@@ -740,7 +1226,8 @@ function gcDispatchWorktreeIfOrphan(opts) {
  *      completed dispatch with long-running services survives engine
  *      restart. (PR #2627 review — Issue 1)
  *
- * Returns `{ scanned, kept, evicted, failed, perProject }`.
+ * Returns legacy `{ scanned, kept, evicted, failed }` counters plus explicit
+ * `{ removed, skipped, skippedLive, preserved, perProject }` outcomes.
  */
 function pruneOrphanWorktrees(opts) {
   opts = opts || {};
@@ -762,6 +1249,12 @@ function pruneOrphanWorktrees(opts) {
   const _hasOwnerMarker = typeof opts.hasOwnerMarker === 'function'
     ? opts.hasOwnerMarker
     : shared.hasWorktreeOwnerMarker;
+  const _isWorktreePathLive = typeof opts.isWorktreePathLive === 'function'
+    ? opts.isWorktreePathLive
+    : shared.isWorktreePathLive;
+  const _liveOpts = opts.db ? { db: opts.db } : undefined;
+  const protectedPaths = opts.protectedPaths instanceof Set ? opts.protectedPaths : new Set();
+  const failedRoots = opts.failedRoots instanceof Set ? opts.failedRoots : new Set();
   const _listManagedSpecs = typeof opts.listManagedSpecs === 'function'
     ? opts.listManagedSpecs
     : (() => {
@@ -802,7 +1295,12 @@ function pruneOrphanWorktrees(opts) {
     if (d.worktreePath) {
       try { globalLiveDirNames.add(path.basename(path.resolve(d.worktreePath))); } catch {}
     }
-    if (!d.meta || !d.meta.branch) continue;
+    if (!d.meta) continue;
+    let dispatchBranch = d.meta.branch;
+    if (!dispatchBranch && d.meta.project) {
+      dispatchBranch = shared.READ_ONLY_ROOT_TASK_TYPES.has(d.type) ? 'read-only' : 'branchless';
+    }
+    if (!dispatchBranch) continue;
     const dispatchProject = typeof d.meta.project === 'string'
       ? d.meta.project
       : (d.meta.project?.name || 'default');
@@ -810,14 +1308,18 @@ function pruneOrphanWorktrees(opts) {
       globalLiveDirNames.add(_buildWorktreeDirName({
         dispatchId: d.id,
         projectName: dispatchProject,
-        branchName: d.meta.branch,
+        branchName: dispatchBranch,
       }));
     } catch (_e) { /* defensive */ }
   }
 
   const anchoredCwds = _collectAnchoredCwds(_listManagedSpecs, _listKeepProcessCwds);
 
-  const result = { scanned: 0, kept: 0, evicted: 0, failed: 0, perProject: {} };
+  const result = {
+    scanned: 0, kept: 0, evicted: 0, failed: 0,
+    removed: 0, skipped: 0, skippedLive: 0, preserved: 0,
+    perProject: {},
+  };
 
   for (const project of projects) {
     if (!project || !project.localPath) continue;
@@ -827,6 +1329,10 @@ function pruneOrphanWorktrees(opts) {
     try { rootExists = _fs.existsSync(rootDir); } catch { rootExists = false; }
     if (!rootExists) continue;
     const wtParent = path.resolve(rootDir, worktreeRootRel);
+    if (failedRoots.has(worktreePool._normalizePath(wtParent))) {
+      log('warn', `worktree-gc: skipping ${wtParent} because filesystem reconciliation failed closed`);
+      continue;
+    }
     let parentExists = false;
     try { parentExists = _fs.existsSync(wtParent); } catch { parentExists = false; }
     if (!parentExists) continue;
@@ -838,7 +1344,10 @@ function pruneOrphanWorktrees(opts) {
       continue;
     }
 
-    const projStats = { scanned: 0, kept: 0, evicted: 0, failed: 0 };
+    const projStats = {
+      scanned: 0, kept: 0, evicted: 0, failed: 0,
+      removed: 0, skipped: 0, skippedLive: 0, preserved: 0,
+    };
     for (const ent of entries) {
       if (!ent || (typeof ent.isDirectory === 'function' && !ent.isDirectory())) continue;
       const name = ent.name || ent;
@@ -848,23 +1357,72 @@ function pruneOrphanWorktrees(opts) {
       projStats.scanned++;
       result.scanned++;
       const wtPath = path.join(wtParent, name);
+      if (protectedPaths.has(worktreePool._normalizePath(wtPath))) {
+        projStats.kept++; result.kept++;
+        projStats.preserved++; result.preserved++;
+        continue;
+      }
 
       // 1. Live-dispatch protection (cross-project safe).
-      if (globalLiveDirNames.has(name)) {
+      const retryMarker = name.lastIndexOf(shared.WORKTREE_RETRY_PATH_MARKER);
+      const liveBaseName = retryMarker > 0 ? name.slice(0, retryMarker) : name;
+      if (globalLiveDirNames.has(name) || globalLiveDirNames.has(liveBaseName)) {
         projStats.kept++; result.kept++;
+        projStats.skipped++; result.skipped++;
+        projStats.skippedLive++; result.skippedLive++;
+        continue;
+      }
+      // The persisted path is authoritative. Derived directory names are only
+      // a pre-persistence fallback and can miss legacy or reused worktrees.
+      if (_pathIsLiveFailOpen(_isWorktreePathLive, wtPath, _liveOpts)) {
+        projStats.kept++; result.kept++;
+        projStats.skipped++; result.skipped++;
+        projStats.skippedLive++; result.skippedLive++;
         continue;
       }
       // 2. Pool membership protection.
       const normPath = worktreePool._normalizePath(wtPath);
       if (poolPaths.has(normPath)) {
         projStats.kept++; result.kept++;
+        projStats.preserved++; result.preserved++;
         continue;
       }
       // 3. managed_spawn / keep_processes cwd anchor protection.
       if (_isWorktreeCwdAnchored(wtPath, anchoredCwds)) {
         projStats.kept++; result.kept++;
+        projStats.preserved++; result.preserved++;
         continue;
       }
+      // Quarantine directories are recovery artifacts, not ordinary crash
+      // residue. Keep them for a deterministic recovery window, and keep
+      // protected quarantines indefinitely when no durable backup ref exists.
+      if (_isQuarantineDirName(name)) {
+        let protectedQuarantine = true;
+        try { protectedQuarantine = shared.hasProtectedQuarantineMarker(wtPath); } catch {}
+        if (protectedQuarantine) {
+          projStats.kept++; result.kept++;
+          projStats.preserved++; result.preserved++;
+          continue;
+        }
+        let quarantineStat;
+        try { quarantineStat = _fs.statSync(wtPath); }
+        catch {
+          projStats.kept++; result.kept++;
+          projStats.preserved++; result.preserved++;
+          continue;
+        }
+        const now = Number.isFinite(Number(opts.now)) ? Number(opts.now) : Date.now();
+        const retentionMs = Math.max(0,
+          Number.isFinite(Number(opts.quarantineRetentionMs))
+            ? Number(opts.quarantineRetentionMs)
+            : DEFAULT_QUARANTINE_RETENTION_MS);
+        const createdAt = _quarantineCreatedAt(name, quarantineStat.mtimeMs);
+        if ((now - createdAt) < retentionMs) {
+          projStats.kept++; result.kept++;
+          projStats.preserved++; result.preserved++;
+          continue;
+        }
+      }
 
       // P-c7e2b405 — route the slow-retry gate, ownership-marker gate (now
       // requireOwnerMarker:true to match the out-of-root pruner), remove,
@@ -888,6 +1446,7 @@ function pruneOrphanWorktrees(opts) {
         writeToInbox: opts.writeToInbox,
         sleepSyncFn: opts.sleepSyncFn,
         stats: [projStats, result],
+        deferredRetries: opts.deferredRetries,
         removeWorktree: _removeWorktree,
         hasOwnerMarker: _hasOwnerMarker,
         log,
@@ -932,7 +1491,9 @@ function pruneOrphanWorktrees(opts) {
  *   4. Path is in the worktree-pool → keep.
  *   5. managed_spawn cwd anchored → keep.
  *
- * Returns `{ scanned, kept, evicted, failed, prunedRegistry, perProject }`.
+ * Returns legacy `{ scanned, kept, evicted, failed, prunedRegistry }` counters
+ * plus explicit `{ removed, skipped, skippedLive, preserved, perProject }`
+ * outcomes.
  *
  * W-mq5o6bvy000x7191 Layer 3.
  */
@@ -983,6 +1544,10 @@ function pruneOrphanWorktreesFromGitRegistry(opts) {
   const _hasOwnerMarker = typeof opts.hasOwnerMarker === 'function'
     ? opts.hasOwnerMarker
     : shared.hasWorktreeOwnerMarker;
+  const _isWorktreePathLive = typeof opts.isWorktreePathLive === 'function'
+    ? opts.isWorktreePathLive
+    : shared.isWorktreePathLive;
+  const _liveOpts = opts.db ? { db: opts.db } : undefined;
 
   // Branches of active/pending dispatches (with and without `refs/heads/`
   // normalization). Matched case-insensitively to mirror git's behavior on
@@ -1010,7 +1575,11 @@ function pruneOrphanWorktreesFromGitRegistry(opts) {
 
   const anchoredCwds = _collectAnchoredCwds(_listManagedSpecs, _listKeepProcessCwds);
 
-  const result = { scanned: 0, kept: 0, evicted: 0, failed: 0, prunedRegistry: 0, perProject: {} };
+  const result = {
+    scanned: 0, kept: 0, evicted: 0, failed: 0, prunedRegistry: 0,
+    removed: 0, skipped: 0, skippedLive: 0, preserved: 0,
+    perProject: {},
+  };
   const _seenAbs = new Set(); // dedup across projects sharing a parent
 
   for (const project of projects) {
@@ -1026,7 +1595,10 @@ function pruneOrphanWorktreesFromGitRegistry(opts) {
     const wtParentAbs = path.resolve(rootDir, worktreeRootRel);
     const wtParentPrefix = wtParentAbs + path.sep;
 
-    const projStats = { scanned: 0, kept: 0, evicted: 0, failed: 0, prunedRegistry: 0 };
+    const projStats = {
+      scanned: 0, kept: 0, evicted: 0, failed: 0, prunedRegistry: 0,
+      removed: 0, skipped: 0, skippedLive: 0, preserved: 0,
+    };
     let trees;
     if (_parsedTreesByProject && _parsedTreesByProject.has(rootDir)) {
       trees = _parsedTreesByProject.get(rootDir);
@@ -1065,16 +1637,29 @@ function pruneOrphanWorktreesFromGitRegistry(opts) {
 
       // Branch protection
       if (wt.branch && protectedBranches.has(String(wt.branch).toLowerCase())) {
-        projStats.kept++; result.kept++; continue;
+        projStats.kept++; result.kept++;
+        projStats.skipped++; result.skipped++;
+        projStats.skippedLive++; result.skippedLive++;
+        continue;
+      }
+      if (_pathIsLiveFailOpen(_isWorktreePathLive, wtAbs, _liveOpts)) {
+        projStats.kept++; result.kept++;
+        projStats.skipped++; result.skipped++;
+        projStats.skippedLive++; result.skippedLive++;
+        continue;
       }
       // Pool protection
       const normPath = worktreePool._normalizePath(wtAbs);
       if (poolPaths.has(normPath)) {
-        projStats.kept++; result.kept++; continue;
+        projStats.kept++; result.kept++;
+        projStats.preserved++; result.preserved++;
+        continue;
       }
       // managed_spawn / keep_processes cwd anchor protection.
       if (_isWorktreeCwdAnchored(wtAbs, anchoredCwds)) {
-        projStats.kept++; result.kept++; continue;
+        projStats.kept++; result.kept++;
+        projStats.preserved++; result.preserved++;
+        continue;
       }
 
       // P-c7e2b405 — ownership-marker gate, slow-retry gate, remove, escalate,
@@ -1103,6 +1688,7 @@ function pruneOrphanWorktreesFromGitRegistry(opts) {
         writeToInbox: opts.writeToInbox,
         sleepSyncFn: opts.sleepSyncFn,
         stats: [projStats, result],
+        deferredRetries: opts.deferredRetries,
         removeWorktree: _removeWorktree,
         hasOwnerMarker: _hasOwnerMarker,
         log,
@@ -1168,7 +1754,8 @@ function pruneOrphanWorktreesFromGitRegistry(opts) {
  *   when set for a project, skip the self-shell of `git worktree list
  *   --porcelain` and reuse the supplied parsed trees).
  *
- * Returns `{ scanned, reclaimed, skippedLive, failed, perProject }` where
+ * Returns `{ scanned, reclaimed, skippedLive, failed, removed, skipped,
+ * preserved, perProject }` where
  * `scanned` counts only the missing-dir candidates considered (dirs that still
  * exist are skipped before scanning).
  */
@@ -1196,7 +1783,11 @@ function reclaimMissingDirWorktrees(opts) {
     : shared.isWorktreePathLive;
   const _liveOpts = opts.db ? { db: opts.db } : undefined;
 
-  const result = { scanned: 0, reclaimed: 0, skippedLive: 0, failed: 0, perProject: {} };
+  const result = {
+    scanned: 0, reclaimed: 0, skippedLive: 0, failed: 0,
+    removed: 0, skipped: 0, preserved: 0,
+    perProject: {},
+  };
   const _seenAbs = new Set(); // dedup across projects sharing a parent repo
 
   for (const project of projects) {
@@ -1207,7 +1798,10 @@ function reclaimMissingDirWorktrees(opts) {
     try { rootExists = _fs.existsSync(rootDir); } catch { rootExists = false; }
     if (!rootExists) continue;
 
-    const projStats = { scanned: 0, reclaimed: 0, skippedLive: 0, failed: 0 };
+    const projStats = {
+      scanned: 0, reclaimed: 0, skippedLive: 0, failed: 0,
+      removed: 0, skipped: 0, preserved: 0,
+    };
     let trees;
     if (_parsedTreesByProject && _parsedTreesByProject.has(rootDir)) {
       trees = _parsedTreesByProject.get(rootDir);
@@ -1250,11 +1844,9 @@ function reclaimMissingDirWorktrees(opts) {
 
       // SAFETY 2 — never reclaim a path a non-terminal dispatch still claims
       // (fail-open: isWorktreePathLive returns true when SQL is unreachable).
-      let live = true;
-      try { live = !!_isWorktreePathLive(wt.path, _liveOpts); }
-      catch (_e) { live = true; }
-      if (live) {
+      if (_pathIsLiveFailOpen(_isWorktreePathLive, wt.path, _liveOpts)) {
         projStats.skippedLive++; result.skippedLive++;
+        projStats.skipped++; result.skipped++;
         log('debug', `worktree-gc: missing-dir reclaim skipping live-claimed ${wtAbs}`);
         continue;
       }
@@ -1265,9 +1857,32 @@ function reclaimMissingDirWorktrees(opts) {
         });
         reclaimedHere++;
         projStats.reclaimed++; result.reclaimed++;
+        projStats.removed++; result.removed++;
         try { shared.bumpWorktreeGcMetric('missingDirReclaimed'); } catch { /* metric optional */ }
         log('info', `worktree-gc: reclaimed missing-dir worktree ${wtAbs}${wt.locked ? ' (was locked)' : ''}${wt.branch ? ` [branch ${wt.branch}]` : ''}`);
       } catch (e) {
+        // Another cleanup path may have removed the registration after this
+        // sweep captured its shared porcelain snapshot. Re-list before calling
+        // an idempotently completed race a failure.
+        let stillRegistered = true;
+        try {
+          const freshRaw = String(_execSilent('git --no-optional-locks worktree list --porcelain', {
+            cwd: rootDir, timeout: 15000, windowsHide: true,
+          }) || '');
+          const freshTrees = _parseWorktreePorcelain(freshRaw);
+          const targetNorm = worktreePool._normalizePath(wtAbs);
+          stillRegistered = freshTrees.some((fresh) => {
+            return fresh && fresh.path
+              && worktreePool._normalizePath(fresh.path) === targetNorm;
+          });
+        } catch { /* keep the original failure authoritative */ }
+        if (!stillRegistered) {
+          reclaimedHere++;
+          projStats.reclaimed++; result.reclaimed++;
+          projStats.removed++; result.removed++;
+          log('debug', `worktree-gc: missing-dir registration already absent after concurrent cleanup ${wtAbs}`);
+          continue;
+        }
         projStats.failed++; result.failed++;
         log('warn', `worktree-gc: missing-dir reclaim remove -f -f failed for ${wtAbs}: ${(e.message || '').split('\n')[0]}`);
       }
@@ -1292,10 +1907,14 @@ function reclaimMissingDirWorktrees(opts) {
 module.exports = {
   shouldGcDispatchWorktree,
   gcDispatchWorktreeIfOrphan,
+  reconcileStaleWorktreeDirectories,
   pruneOrphanWorktrees,
   pruneOrphanWorktreesFromGitRegistry,
   reclaimMissingDirWorktrees, // W-mqifblkf00149df5 — locked-initializing missing-dir reaper
   reapAndRemoveWorktree, // P-c7e2b405 — shared reap-then-remove core (exported for testing)
+  isLegacyMinionsWorktreeDir, // exported for testing
+  DEFAULT_ORPHAN_RETENTION_MS,
+  DEFAULT_QUARANTINE_RETENTION_MS,
   // exported for testing (W-mq5o6bvy000x7191)
   _resetStuckPathsForTesting,
   _stuckPaths,