@yemi33/minions 0.1.2424 → 0.1.2425

package/engine/cleanup.js

@@ -28,10 +28,8 @@ function engine() { if (!_engine) _engine = require('../engine'); return _engine
 let _dispatch = null;
 function dispatchModule() { if (!_dispatch) _dispatch = require('./dispatch'); return _dispatch; }
 
-// Lazy require for worktree-pool — used to protect pool entries from age/cap
-// sweeps (W-mp73ya3e000me6c5). Borrowed entries with live dispatches are
-// always protected; idle entries survive the age sweep but stay eligible for
-// the cap sweep so MAX_WORKTREES is still honored.
+// Lazy require for worktree-pool. Borrowed entries with live dispatches are
+// protected; idle-entry TTL cleanup remains owned by worktree-pool.pruneStale.
 let _worktreePool = null;
 function worktreePool() {
   if (!_worktreePool) _worktreePool = require('./worktree-pool');
@@ -92,9 +90,7 @@ function localBranchWorktreeInUse(root, branch) {
 // P-e0b4f7a5 — collect branches of work items currently in the
 // phantom-completion retry state for a given project. Returns a Set of
 // branch strings. Used by the worktree cleanup loop to protect worktrees
-// belonging to in-flight phantom retries from the 2-hour age sweep —
-// without this protection the agent's pushed branch reference could be
-// destroyed alongside the worktree before the retry runs.
+// belonging to in-flight phantom retries from terminal-PR cleanup.
 function collectPhantomBranchesForProject(project) {
   const branches = new Set();
   try {
@@ -318,61 +314,6 @@ async function getWorktreeBranchAsync(wtPath) {
   }
 }
 
-/**
- * Kill orphaned processes whose dispatch ID appears in the worktree dir name.
- * Only kills processes NOT in the active dispatch queue — never kills live agents.
- */
-function _killProcessInWorktree(dir, activeProcesses, activeIds) {
-  const dirLower = dir.toLowerCase();
-
-  // Check tracked in-memory processes — only kill if dispatch is no longer active
-  for (const [id, info] of activeProcesses.entries()) {
-    if (!dirLower.includes(id.toLowerCase().slice(-8))) continue;
-    if (activeIds.has(id)) continue; // still active — do not kill
-    try { shared.killImmediate(info.proc); } catch {}
-    activeProcesses.delete(id);
-    log('info', `Killed orphaned process for dispatch ${id} before worktree removal`);
-  }
-
-  // Check PID files in engine/tmp/ — both legacy flat layout and per-dispatch
-  // dirs (P-f6-tmp-toctou). Only kill if no active dispatch matches.
-  try {
-    shared.forEachPidFile((pidFilePath, fileName, layout) => {
-      const pidFileName = fileName.replace(/^pid-/, '').replace(/\.pid$/, '');
-      if (!dirLower.includes(pidFileName.slice(-8))) return;
-      // Verify this PID file's dispatch is not active
-      let isActive = false;
-      for (const id of activeIds) { if (pidFileName.includes(id.slice(-8))) { isActive = true; break; } }
-      if (isActive) return; // still active — do not kill
-      let pid;
-      try { pid = parseInt(fs.readFileSync(pidFilePath, 'utf8').trim(), 10); }
-      catch { return; }
-      if (pid > 0) {
-        // Verify the PID still belongs to a Minions runtime process before killing.
-        // The shared helper inspects the PID's full command line for `claude` /
-        // `copilot` so a recycled PID running an unrelated process is skipped.
-        try {
-          if (process.platform === 'win32') {
-            if (!shared.isProcessCommandLineMatchingAgent(pid)) return;
-            exec(`taskkill /F /T /PID ${pid}`, { stdio: 'pipe', timeout: 5000, windowsHide: true });
-          } else {
-            if (!shared.isProcessCommandLineMatchingAgent(pid)) return;
-            try { process.kill(-pid, 'SIGKILL'); } catch { process.kill(pid, 'SIGKILL'); }
-          }
-          log('info', `Killed orphaned PID ${pid} (${fileName}, ${layout}) before worktree removal`);
-        } catch {} // process may already be dead
-      }
-      if (layout === 'dispatch-dir') {
-        // Remove the entire per-dispatch dir — its remaining sidecars are
-        // orphans of the same dead process.
-        try { shared.removeDispatchTmpDir(path.dirname(pidFilePath)); } catch {}
-      } else {
-        try { fs.unlinkSync(pidFilePath); } catch {}
-      }
-    });
-  } catch {} // tmp dir may not exist
-}
-
 // Agent scratch (`.agent-temp` under the worktree root) holds throwaway git
 // repos written by dispatched agents + the test-suite-run-by-agents. Nothing
 // owns its lifecycle, so it accumulates unboundedly (observed: 26k+ dirs). The
@@ -384,22 +325,41 @@ function _killProcessInWorktree(dir, activeProcesses, activeIds) {
 // across cleanup cycles.
 const AGENT_SCRATCH_TTL_MS = 6 * 60 * 60 * 1000; // 6h — comfortably > agentTimeout (5h), so only dead-dispatch scratch is reaped
 const AGENT_SCRATCH_MAX_SCAN_PER_CLEANUP = 2000;
+const _agentScratchScanOffsets = new Map();
+const LEGACY_LLM_TEMP_RE = /-(?:prompt|sys|sysprompt)-[^\\/]+\.md$/i;
 
-function reapAgentScratch(worktreeRoot) {
+function reapAgentScratch(worktreeRoot, opts = {}) {
   const scratchDir = path.join(worktreeRoot, shared.WORKTREE_SCRATCH_DIR_NAME);
   let names;
-  try { names = fs.readdirSync(scratchDir); } catch { return 0; } // no scratch dir → nothing to do
+  try { names = fs.readdirSync(scratchDir); } catch {
+    _agentScratchScanOffsets.delete(scratchDir);
+    return 0;
+  }
+  if (names.length === 0) {
+    _agentScratchScanOffsets.delete(scratchDir);
+    return 0;
+  }
   const cutoff = Date.now() - AGENT_SCRATCH_TTL_MS;
+  const maxScan = Number.isFinite(Number(opts.maxScan))
+    ? Math.max(1, Math.floor(Number(opts.maxScan)))
+    : AGENT_SCRATCH_MAX_SCAN_PER_CLEANUP;
   let reaped = 0;
-  const limit = Math.min(names.length, AGENT_SCRATCH_MAX_SCAN_PER_CLEANUP);
+  const limit = Math.min(names.length, maxScan);
+  const start = (_agentScratchScanOffsets.get(scratchDir) || 0) % names.length;
   for (let i = 0; i < limit; i++) {
-    const full = path.join(scratchDir, names[i]);
+    const full = path.join(scratchDir, names[(start + i) % names.length]);
     let stat;
     try { stat = fs.statSync(full); } catch { continue; }
     if (stat.mtimeMs >= cutoff) continue; // recent — may belong to a live dispatch
     try { fs.rmSync(full, { recursive: true, force: true }); reaped++; }
     catch { /* locked / in use — leave it for a later pass */ }
   }
+  const remaining = names.length - reaped;
+  if (remaining > 0) {
+    _agentScratchScanOffsets.set(scratchDir, (start + limit - reaped) % remaining);
+  } else {
+    _agentScratchScanOffsets.delete(scratchDir);
+  }
   if (reaped > 0) {
     log('info', `Reaped ${reaped} stale agent-scratch entries (>${Math.round(AGENT_SCRATCH_TTL_MS / 3600000)}h) from ${scratchDir}`);
   }
@@ -415,6 +375,7 @@ function reapAgentScratch(worktreeRoot) {
 const KNOWLEDGE_SCRATCH_RE = /(?:kb-cleanup-batch|consolidated-digest|consolidated-ci-health)/i;
 const KNOWLEDGE_SCRATCH_TTL_MS = 48 * 60 * 60 * 1000; // 48h — keep a couple days for reference, reap older
 const KNOWLEDGE_SCRATCH_MAX_SCAN = 5000;
+const RUNTIME_ARTIFACT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 
 function reapKnowledgeScratch(minionsDir = MINIONS_DIR) {
   const dir = path.join(minionsDir, 'knowledge');
@@ -440,6 +401,54 @@ function reapKnowledgeScratch(minionsDir = MINIONS_DIR) {
   return reaped;
 }
 
+function pruneStaleEngineTmpFiles(opts = {}) {
+  const now = Number.isFinite(Number(opts.now)) ? Number(opts.now) : Date.now();
+  const tmpDir = path.join(ENGINE_DIR, 'tmp');
+  let entries;
+  try { entries = fs.readdirSync(tmpDir, { withFileTypes: true }); } catch { return 0; }
+  let pruned = 0;
+  for (const entry of entries) {
+    if (!entry.isFile() || /^pid-.*\.pid$/i.test(entry.name)) continue;
+    const full = path.join(tmpDir, entry.name);
+    let stat;
+    try { stat = fs.statSync(full); } catch { continue; }
+    if ((now - stat.mtimeMs) < RUNTIME_ARTIFACT_RETENTION_MS) continue;
+    try { fs.unlinkSync(full); pruned++; } catch { /* best-effort */ }
+  }
+  return pruned;
+}
+
+function pruneOrphanManagedLogs(opts = {}) {
+  const now = Number.isFinite(Number(opts.now)) ? Number(opts.now) : Date.now();
+  const specs = Array.isArray(opts.specs)
+    ? opts.specs
+    : require('./managed-spawn').listManagedSpecs();
+  const normalize = value => {
+    const resolved = path.resolve(String(value || ''));
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+  };
+  const protectedLogs = new Set();
+  for (const spec of specs || []) {
+    if (!spec?.log_path) continue;
+    protectedLogs.add(normalize(spec.log_path));
+    protectedLogs.add(normalize(`${spec.log_path}.1`));
+  }
+  const logsDir = path.join(ENGINE_DIR, 'managed-logs');
+  let entries;
+  try { entries = fs.readdirSync(logsDir, { withFileTypes: true }); } catch { return 0; }
+  let pruned = 0;
+  for (const entry of entries) {
+    if (!entry.isFile() || !/\.log(?:\.1)?$/i.test(entry.name)) continue;
+    const full = path.join(logsDir, entry.name);
+    if (protectedLogs.has(normalize(full))) continue;
+    let stat;
+    try { stat = fs.statSync(full); } catch { continue; }
+    if ((now - stat.mtimeMs) < RUNTIME_ARTIFACT_RETENTION_MS) continue;
+    try { fs.unlinkSync(full); pruned++; } catch { /* best-effort */ }
+  }
+  return pruned;
+}
+
 // ─── Cleanup Orchestrator ────────────────────────────────────────────────────
 
 async function runCleanup(config, verbose = false) {
@@ -487,7 +496,8 @@ async function runCleanup(config, verbose = false) {
       continue;
     }
     for (const f of dirEntries) {
-      const isPromptTemp = f.startsWith('prompt-') || f.startsWith('sysprompt-') || f.startsWith('tmp-sysprompt-');
+      const isLegacyLlmTemp = dir === tmpDir && LEGACY_LLM_TEMP_RE.test(f);
+      const isPromptTemp = isLegacyLlmTemp || 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);
@@ -518,6 +528,15 @@ async function runCleanup(config, verbose = false) {
       }
     } catch { /* sweep is best-effort */ }
   }
+  cleaned.staleRuntimeTmpFiles = 0;
+  try {
+    cleaned.staleRuntimeTmpFiles = pruneStaleEngineTmpFiles();
+    cleaned.tempFiles += cleaned.staleRuntimeTmpFiles;
+  } catch (e) { log('warn', `pruneStaleEngineTmpFiles: ${e.message}`); }
+  cleaned.orphanManagedLogs = 0;
+  try {
+    cleaned.orphanManagedLogs = pruneOrphanManagedLogs();
+  } catch (e) { log('warn', `pruneOrphanManagedLogs: ${e.message}`); }
 
   // 2. Clean live-output.log and live-output-prev.log for idle agents (not currently working)
   for (const [agentId] of Object.entries(config.agents || {})) {
@@ -615,100 +634,25 @@ async function runCleanup(config, verbose = false) {
     }
   }
 
-  // 2d. Reap on-disk worktree dirs not registered in `git worktree list`. Can
-  // be left behind when removeWorktree fails mid-way, when `git worktree prune`
-  // ran without a follow-up rm -rf, or after manual `git worktree remove
-  // --force` leaves an empty dir. Phase 3 below only walks dirs already in
-  // git's list, so these are invisible to it. 2h mtime gate matches the
-  // existing age sweep further down.
+  // 2d. Filesystem-authoritative stale-directory reconciliation. This is the
+  // sole destructive scan of the configured worktree root; periodic and boot
+  // maintenance use the same implementation.
   cleaned.orphanWorktreeDirs = 0;
-  const _twoHoursAgo = Date.now() - 7200000;
-  const _scannedWtRoots = new Set();
-  for (const project of projects) {
-    const root = project.localPath ? path.resolve(project.localPath) : null;
-    if (!root || !fs.existsSync(root)) continue;
-    const wtRoots = new Set();
-    const configuredRoot = path.resolve(root, config.engine?.worktreeRoot || '../worktrees');
-    if (fs.existsSync(configuredRoot)) wtRoots.add(configuredRoot);
-    for (const d of ['worktrees', '.claude/worktrees'].map(d => path.join(root, d))) {
-      if (fs.existsSync(d)) wtRoots.add(d);
-    }
-    let registered = null;
-    for (const wtRoot of wtRoots) {
-      if (_scannedWtRoots.has(wtRoot)) continue;
-      _scannedWtRoots.add(wtRoot);
-      // Resolve `git worktree list` once per project; reused across its roots.
-      if (registered === null) {
-        try {
-          const raw = String(shared.execSilent('git worktree list --porcelain', { cwd: root, timeout: 10000, windowsHide: true }) || '');
-          registered = new Set(shared.parseWorktreePorcelain(raw).map(wt => path.resolve(wt.path)));
-        } catch (e) {
-          log('warn', `orphan worktree dir scan for ${project.name || root}: ${e.message}`);
-          registered = new Set();
-        }
-      }
-      let entries;
-      try { entries = fs.readdirSync(wtRoot, { withFileTypes: true }); } catch { continue; }
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        const full = path.resolve(wtRoot, entry.name);
-        // Defensive boundary: only ever delete strictly inside the worktree
-        // root we enumerated. readdirSync never yields `..`, so this is always
-        // true today — but it makes the "never escape wtRoot" invariant
-        // explicit and immune to a future refactor of how `full` is derived.
-        if (full !== wtRoot && !full.startsWith(wtRoot + path.sep)) continue;
-        if (registered.has(full)) continue;
-        // W-mqecdoot — ownership gate, parity with the out-of-root worktree GC
-        // (worktree-gc.pruneOrphanWorktreesFromGitRegistry). Only ever reap a
-        // dir the engine positively created (carries the `.minions-worktree`
-        // marker stamped right after `git worktree add`). A dir with NO marker
-        // is a human's hand-made worktree (`git worktree add ../worktrees/mine`)
-        // or some unrelated folder dropped into the worktree root — KEEP it,
-        // never delete. Fail-open: leak a husk rather than nuke someone's
-        // unpushed work. This closes the same data-loss class the marker fixed
-        // for the registry sweep, for this on-disk-dir sweep too. The cost is
-        // that empty leftover husks whose marker was already removed leak
-        // instead of being reaped — an acceptable trade for "absolutely never
-        // delete foreign data".
-        let owned = false;
-        try { owned = !!shared.hasWorktreeOwnerMarker(full); } catch { owned = false; }
-        if (!owned) {
-          log('debug', `Cleanup: keeping orphan worktree dir ${full} — no engine ownership marker (foreign/hand-made worktree)`);
-          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`);
-          const blockingInfo = shared.getWorktreeBlockingDispatchInfo(full);
-          shared._writeWorktreeSkipLiveInboxNote(full, 'cleanup.orphanWorktreeDirSweep', blockingInfo);
-          continue;
-        }
-        // W-mr2zu0hb000f20c7 — route through shared.removeWorktree instead of a
-        // raw fs.rmSync so this path gets the same retry-with-backoff (transient
-        // Windows EBUSY/locked-file handling) and real-repo-refusal safety net
-        // that every other worktree removal in this file uses. This dir already
-        // isn't registered in `git worktree list`, so the primary
-        // `git worktree remove --force` inside removeWorktree is expected to
-        // fail and fall through to its fs.rmSync + retry logic — that's fine,
-        // the safety checks (ownership marker already verified above; real-repo
-        // and live-dispatch refusals re-checked inside removeWorktree) still apply.
-        try {
-          if (shared.removeWorktree(full, root, wtRoot)) {
-            cleaned.orphanWorktreeDirs++;
-            log('info', `Cleanup: removed orphan worktree dir ${full} (not registered in git)`);
-          } else {
-            log('warn', `orphan worktree dir ${full}: removeWorktree declined (see prior log line for reason)`);
-          }
-        } catch (err) {
-          log('warn', `orphan worktree dir ${full}: ${err.message}`);
-        }
-      }
-    }
+  cleaned.worktreeReconcileFailed = 0;
+  try {
+    const reconcile = require('./worktree-gc').reconcileStaleWorktreeDirectories({
+      projects,
+      dispatchSnap: getDispatch(),
+      worktreeRootRel: config.engine?.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot,
+      config,
+      log: (level, message) => log(level, message),
+      writeToInbox: (agent, slug, content) => shared.writeToInbox(agent, slug, content),
+    });
+    cleaned.orphanWorktreeDirs = reconcile.removed || 0;
+    cleaned.worktreeReconcileFailed = reconcile.failed || 0;
+  } catch (err) {
+    cleaned.worktreeReconcileFailed = 1;
+    log('warn', `worktree filesystem reconcile: ${err.message}`);
   }
 
   // 3. Clean git worktrees for merged/abandoned PRs
@@ -725,12 +669,26 @@ async function runCleanup(config, verbose = false) {
     const root = project.localPath ? path.resolve(project.localPath) : null;
     if (!root || !fs.existsSync(root)) continue;
 
-    // Scan all potential worktree locations: configured root + common project-local dirs
+    // This phase only handles explicit merged/abandoned PR cleanup. Generic
+    // retention cleanup belongs to the authoritative reconciliation above.
+    let registeredByPath;
+    try {
+      const raw = String(shared.execSilent('git --no-optional-locks worktree list --porcelain', {
+        cwd: root, timeout: 15000, windowsHide: true,
+      }) || '');
+      registeredByPath = new Map(
+        shared.parseWorktreePorcelain(raw)
+          .filter(entry => entry?.path)
+          .map(entry => [worktreePool()._normalizePath(entry.path), entry]),
+      );
+    } catch (err) {
+      log('warn', `cleanup merged worktrees for ${project.name || root}: registry unavailable (${err.message}) — fail-closed`);
+      continue;
+    }
+
     const worktreeRoots = new Set();
     const configuredRoot = path.resolve(root, config.engine?.worktreeRoot || '../worktrees');
     if (fs.existsSync(configuredRoot)) worktreeRoots.add(configuredRoot);
-    const localDirs = ['worktrees', '.claude/worktrees'].map(d => path.join(root, d));
-    for (const d of localDirs) { if (fs.existsSync(d)) worktreeRoots.add(d); }
 
     for (const worktreeRoot of worktreeRoots) {
 
@@ -750,8 +708,7 @@ async function runCleanup(config, verbose = false) {
       }
     }
 
-    // List worktrees — collect info for age-based + cap-based cleanup
-    const MAX_WORKTREES = 10;
+    // List registered engine-owned worktrees for explicit terminal PR cleanup.
     try {
       // Collect all worktree directories (including nested ones like minions-work/P-xxx)
       const allDirs = [];
@@ -765,64 +722,53 @@ async function runCleanup(config, verbose = false) {
         if (shared.isWorktreeRootInfraEntry(dir)) continue;
         const dirPath = path.join(worktreeRoot, dir);
         try { if (!fs.statSync(dirPath).isDirectory()) continue; } catch { continue; }
-        // Check if this is a git worktree (has .git file) or a parent directory
+        // Check if this is a registered engine-owned git worktree or a parent
+        // directory containing one. Unregistered residue is owned by phase 2d.
         if (fs.existsSync(path.join(dirPath, '.git'))) {
-          allDirs.push({ dir, wtPath: dirPath });
+          const normalized = worktreePool()._normalizePath(dirPath);
+          if (registeredByPath.has(normalized)
+              && shared.hasWorktreeOwnerMarker(dirPath)
+              && !shared.hasProtectedQuarantineMarker(dirPath)
+              && !/-quarantine-(?:protected-)?\d+(?:$|-)/.test(dir)) {
+            allDirs.push({ dir, wtPath: dirPath, registration: registeredByPath.get(normalized) });
+          }
         } else {
           // Scan subdirectories for worktrees
           try {
             for (const sub of fs.readdirSync(dirPath)) {
               const subPath = path.join(dirPath, sub);
-              try { if (fs.statSync(subPath).isDirectory()) allDirs.push({ dir: dir + '/' + sub, wtPath: subPath }); } catch { /* skip */ }
+              try {
+                if (!fs.statSync(subPath).isDirectory()) continue;
+                const normalized = worktreePool()._normalizePath(subPath);
+                if (registeredByPath.has(normalized)
+                    && shared.hasWorktreeOwnerMarker(subPath)
+                    && !shared.hasProtectedQuarantineMarker(subPath)
+                    && !/-quarantine-(?:protected-)?\d+(?:$|-)/.test(sub)) {
+                  allDirs.push({ dir: dir + '/' + sub, wtPath: subPath, registration: registeredByPath.get(normalized) });
+                }
+              } catch { /* skip */ }
             }
           } catch { /* skip */ }
         }
       }
 
-      const wtEntries = []; // { dir, wtPath, mtime, shouldClean, isProtected }
+      if (allDirs.length === 0) continue;
+
+      const wtEntries = []; // { dir, wtPath, shouldClean, isProtected }
       const dispatch = getDispatch();
       const activeDispatchIds = new Set((dispatch.active || []).map(d => d.id));
-      // P-e0b4f7a5 — branches whose work item is mid-phantom-retry. Their
-      // worktrees must survive the age/cap sweep until the retry completes
-      // (or exhausts its budget) so the agent's already-pushed branch ref
-      // isn't destroyed alongside the worktree.
+      // P-e0b4f7a5 — branches whose work item is mid-phantom-retry survive
+      // terminal-PR cleanup until the retry completes or exhausts its budget.
       const phantomBranches = collectPhantomBranchesForProject(project);
 
-      // W-mp73ya3e000me6c5 — worktree pool protection sets. Borrowed entries
-      // with live dispatches are ALWAYS protected (no age, no cap). Idle
-      // entries survive the age sweep but stay eligible for the cap sweep so
-      // MAX_WORKTREES is still honored.
+      // W-mp73ya3e000me6c5 — borrowed entries with live dispatches are
+      // protected; idle pool TTL is handled by worktree-pool.pruneStale.
       let _activeBorrowedPaths = new Set();
-      let _idlePaths = new Set();
       try {
         _activeBorrowedPaths = worktreePool().getActiveBorrowedPaths(activeDispatchIds);
-        _idlePaths = worktreePool().getIdlePaths();
       } catch (e) { log('warn', `worktree-pool: cleanup lookup failed: ${e.message}`); }
       const _normalizePoolPath = worktreePool()._normalizePath;
 
-      // W-mpbinmrh001907e9 — managed-spawn cwd anchor protection. After a
-      // managed_spawn dispatch succeeds, engine-owned services run with
-      // `cwd` inside the dispatch's worktree; the agent is gone so no
-      // active dispatch references the branch and the >2h age sweep would
-      // reap the worktree from under the live services. Build a list of
-      // normalized cwd values from managed-process state and protect any
-      // worktree dir that contains one. Cwd is optional per the schema, so
-      // entries without cwd contribute nothing.
-      const _anchoredProcessCwds = [];
-      try {
-        const _ms = require('./managed-spawn');
-        for (const rec of _ms.listManagedSpecs()) {
-          if (rec && typeof rec.cwd === 'string' && rec.cwd.length > 0) {
-            try { _anchoredProcessCwds.push(shared.realPathForComparison(rec.cwd)); }
-            catch (_e) { /* malformed cwd — skip */ }
-          }
-        }
-      } catch (e) { log('warn', `managed-spawn cwd anchor lookup failed: ${e.message}`); }
-      try {
-        const _kp = require('./keep-process-sweep');
-        _anchoredProcessCwds.push(..._kp.getActiveKeepProcessCwds());
-      } catch (e) { log('warn', `keep-processes cwd anchor lookup failed: ${e.message}`); }
-
       // Probe `git branch --show-current` for every worktree in chunks of 5.
       // Sequential probing was the dominant cost in the cleanup phase
       // (5–15s tick stall every 10 ticks at 50+ worktrees), but unbounded
@@ -838,10 +784,53 @@ async function runCleanup(config, verbose = false) {
         for (const [wtPath, branch] of pairs) branchMap.set(wtPath, branch);
       }
 
-      for (const { dir, wtPath } of allDirs) {
+      // Refresh process protection after the asynchronous branch probes so a
+      // service started during that wait cannot lose its cwd at deletion.
+      const _anchoredProcessCwds = [];
+      let _anchorProbeFailed = false;
+      try {
+        const _ms = require('./managed-spawn');
+        for (const rec of _ms.listManagedSpecs()) {
+          if (rec && typeof rec.cwd === 'string' && rec.cwd.length > 0) {
+            try { _anchoredProcessCwds.push(shared.realPathForComparison(rec.cwd)); }
+            catch (_e) { /* malformed cwd — skip */ }
+          }
+        }
+      } catch (e) {
+        _anchorProbeFailed = true;
+        log('warn', `managed-spawn cwd anchor lookup failed: ${e.message}`);
+      }
+      try {
+        const _kp = require('./keep-process-sweep');
+        _anchoredProcessCwds.push(..._kp.getActiveKeepProcessCwds());
+      } catch (e) {
+        _anchorProbeFailed = true;
+        log('warn', `keep-processes cwd anchor lookup failed: ${e.message}`);
+      }
+      if (_anchorProbeFailed) {
+        log('warn', `cleanup merged worktrees for ${project.name || root}: process anchor state unavailable — fail-closed`);
+        continue;
+      }
+      let _cwdHolders;
+      try {
+        const finder = process.platform === 'win32'
+          ? shared.findProcessCwdHolders
+          : shared.findProcessesWithCwdInside;
+        _cwdHolders = finder(worktreeRoot, {
+          timeoutMs: process.platform === 'win32'
+            ? (config.engine?.statusProbeKillTimeoutMs ?? ENGINE_DEFAULTS.statusProbeKillTimeoutMs)
+            : (config.engine?.orphanHolderScanTimeoutMs ?? ENGINE_DEFAULTS.orphanHolderScanTimeoutMs),
+          throwOnFailure: true,
+        }) || [];
+      } catch (err) {
+        log('warn', `cleanup merged worktrees for ${project.name || root}: holder probe failed (${err.message}) — fail-closed`);
+        continue;
+      }
+
+      for (const { dir, wtPath, registration } of allDirs) {
 
         let shouldClean = false;
-        let isProtected = false;
+        let isProtected = !!registration?.locked;
         const actualBranch = branchMap.get(wtPath) || '';
 
         // Check if this worktree's branch is merged/abandoned
@@ -862,6 +851,7 @@ async function runCleanup(config, verbose = false) {
           return worktreeMatchesBranch(dirLower, d.meta.branch, actualBranch);
         });
         if (isReferenced) isProtected = true;
+        if (!isProtected && shared.isWorktreePathLive(wtPath)) isProtected = true;
 
         // P-e0b4f7a5 — protect worktrees whose branch matches a work item in
         // the phantom-completion retry state. The dispatch may have already
@@ -880,7 +870,6 @@ async function runCleanup(config, verbose = false) {
         // W-mp73ya3e000me6c5 — pool-membership protection.
         const _normWt = _normalizePoolPath ? _normalizePoolPath(wtPath) : wtPath;
         const _isActiveBorrowed = _activeBorrowedPaths.has(_normWt);
-        const _isIdlePool = _idlePaths.has(_normWt);
         if (_isActiveBorrowed) {
           // Borrowed by a live dispatch — full protection (overrides any
           // earlier shouldClean from merged-branch match too: the borrow
@@ -893,7 +882,7 @@ async function runCleanup(config, verbose = false) {
         // Long-running process cwd anchor protection.
         // Worktrees backing live managed_spawn or keep_processes cwds must outlive the
         // originating dispatch.
-        // Overrides merged-branch and age sweeps because the cwd record is
+        // Overrides merged-branch cleanup because the cwd record is
         // the authoritative signal that something live still uses the dir.
         if (_anchoredProcessCwds.length > 0) {
           for (const cwd of _anchoredProcessCwds) {
@@ -910,17 +899,14 @@ async function runCleanup(config, verbose = false) {
           }
         }
 
-        // Also clean worktrees older than 2 hours with no active dispatch referencing them
-        let mtime = Date.now();
-        if (!shouldClean) {
-          try {
-            const stat = fs.statSync(wtPath);
-            mtime = stat.mtimeMs;
-            const ageMs = Date.now() - mtime;
-            if (ageMs > 7200000 && !isReferenced && !isProtected && !_isIdlePool) { // 2 hours — P-e0b4f7a5: phantom-protected worktrees survive the age sweep too. W-mp73ya3e000me6c5: idle pool entries also survive (TTL eviction handled by worktree-pool.pruneStale).
-              shouldClean = true;
-            }
-          } catch { /* optional */ }
+        if (!isProtected && _cwdHolders.some((holder) => {
+          if (!holder?.cwd) return true;
+          try { return shared.isPathInsideOrEqual(holder.cwd, wtPath); }
+          catch { return true; }
+        })) {
+          isProtected = true;
+          shouldClean = false;
+          if (verbose) console.log(`  Skipping worktree ${dir}: process cwd holder`);
         }
 
         // Skip worktrees for active shared-branch plans.
@@ -937,19 +923,7 @@ async function runCleanup(config, verbose = false) {
           }
         }
 
-        wtEntries.push({ dir, wtPath, mtime, shouldClean, isProtected, actualBranch, matchedMergedBranch });
-      }
-
-      // Enforce max worktree cap — if over limit, mark oldest unprotected for cleanup
-      const surviving = wtEntries.filter(e => !e.shouldClean && !e.isProtected);
-      if (surviving.length + wtEntries.filter(e => e.isProtected).length > MAX_WORKTREES) {
-        // Sort oldest first
-        surviving.sort((a, b) => a.mtime - b.mtime);
-        const excess = surviving.length + wtEntries.filter(e => e.isProtected).length - MAX_WORKTREES;
-        for (let i = 0; i < Math.min(excess, surviving.length); i++) {
-          surviving[i].shouldClean = true;
-          if (verbose) console.log(`  Marking worktree ${surviving[i].dir} for cap cleanup (${MAX_WORKTREES} max)`);
-        }
+        wtEntries.push({ dir, wtPath, shouldClean, isProtected, actualBranch, matchedMergedBranch });
       }
 
       // Remove all marked worktrees
@@ -966,9 +940,32 @@ async function runCleanup(config, verbose = false) {
           freshMergedPrByBranch.set(sanitizeBranch(normalizeLocalBranchName(pr.branch)).toLowerCase(), pr);
         }
       }
+      let freshRegisteredByPath;
+      try {
+        const raw = String(shared.execSilent('git --no-optional-locks worktree list --porcelain', {
+          cwd: root, timeout: 15000, windowsHide: true,
+        }) || '');
+        freshRegisteredByPath = new Map(
+          shared.parseWorktreePorcelain(raw)
+            .filter(item => item?.path)
+            .map(item => [worktreePool()._normalizePath(item.path), item]),
+        );
+      } catch (err) {
+        log('warn', `cleanup merged worktrees for ${project.name || root}: final registry check failed (${err.message}) — fail-closed`);
+        continue;
+      }
 
       for (const entry of wtEntries) {
         if (entry.shouldClean) {
+          const normalizedEntryPath = worktreePool()._normalizePath(entry.wtPath);
+          const freshRegistration = freshRegisteredByPath.get(normalizedEntryPath);
+          if (!freshRegistration
+              || freshRegistration.locked
+              || shared.isWorktreePathLive(entry.wtPath)
+              || !shared.hasWorktreeOwnerMarker(entry.wtPath)
+              || shared.hasProtectedQuarantineMarker(entry.wtPath)) {
+            continue;
+          }
           // Verify the branch is still merged/closed — skip if PR was reopened since initial check
           const entryDirLower = entry.dir.toLowerCase();
           let stillMerged = false;
@@ -978,25 +975,18 @@ async function runCleanup(config, verbose = false) {
               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 => worktreeMatchesBranch(entryDirLower, branch, entry.actualBranch));
-            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;
-            }
+            if (verbose) console.log(`  Skipping worktree ${entry.dir}: PR was reopened since initial check`);
+            log('info', `Worktree deletion skipped — PR reopened: ${entry.dir}`);
+            continue;
           }
 
           if (_attemptedWorktreePaths.has(entry.wtPath)) continue;
           _attemptedWorktreePaths.add(entry.wtPath);
-          // Kill any process still running in this worktree before removal
-          _killProcessInWorktree(entry.dir, activeProcesses, activeDispatchIds);
           if (shared.removeWorktree(entry.wtPath, root, worktreeRoot)) {
             cleaned.worktrees++;
-            // W-mp73ya3e000me6c5 — keep the pool file in sync when an idle
-            // pool entry is reaped by the cap sweep (or any other reason).
+            // W-mp73ya3e000me6c5 — keep the pool file in sync when terminal
+            // PR cleanup removes an entry.
             try { worktreePool().evictEntry(entry.wtPath, 'cleanup-removed'); } catch (_e) { /* optional */ }
             const mergedPr = entry.matchedMergedBranch
               ? freshMergedPrByBranch.get(sanitizeBranch(normalizeLocalBranchName(entry.matchedMergedBranch)).toLowerCase())
@@ -1043,6 +1033,29 @@ async function runCleanup(config, verbose = false) {
 
     // Clean individual orphaned processes — no matching active dispatch
     const activeIds = new Set((dispatch.active || []).map(d => d.id));
+    cleaned.stalePidFiles = 0;
+    shared.forEachPidFile((pidFilePath, fileName, layout) => {
+      let stat;
+      try { stat = fs.statSync(pidFilePath); } catch { return; }
+      if (stat.mtimeMs >= oneHourAgo) return;
+      const pidFileName = fileName.replace(/^pid-/, '').replace(/\.pid$/, '');
+      if ([...activeIds].some(id => pidFileName.includes(String(id).slice(-8)))) return;
+      let pid;
+      try { pid = Number(fs.readFileSync(pidFilePath, 'utf8').trim()); } catch { return; }
+      if (activePids.has(pid)) return;
+      if (Number.isInteger(pid) && pid > 0 && shared.isProcessCommandLineMatchingAgent(pid)) {
+        try {
+          shared.killImmediate({ pid });
+          cleaned.zombies++;
+        } catch { /* process may already be gone */ }
+      }
+      if (layout === 'dispatch-dir') {
+        try { shared.removeDispatchTmpDir(path.dirname(pidFilePath)); } catch {}
+      } else {
+        try { fs.unlinkSync(pidFilePath); } catch {}
+      }
+      cleaned.stalePidFiles++;
+    });
     for (const [id, info] of activeProcesses.entries()) {
       if (!activeIds.has(id)) {
         shared.killImmediate(info.proc);
@@ -1186,8 +1199,9 @@ async function runCleanup(config, verbose = false) {
 
   const _orphanTemp = cleaned.orphanTempAgentDirs || 0;
   const _orphanWt = cleaned.orphanWorktreeDirs || 0;
-  if (cleaned.tempFiles + cleaned.liveOutputs + cleaned.worktrees + cleaned.zombies + (cleaned.files || 0) + cleaned.orphanedDispatches + (cleaned.nestedWorktrees || 0) + _orphanTemp + _orphanWt > 0) {
-    log('info', `Cleanup: ${cleaned.tempFiles} temp, ${cleaned.liveOutputs} live outputs, ${cleaned.worktrees} worktrees, ${cleaned.zombies} zombies, ${cleaned.files || 0} archives, ${cleaned.orphanedDispatches} orphaned dispatches, ${cleaned.nestedWorktrees || 0} nested worktrees flagged, ${_orphanTemp} orphan temp dirs, ${_orphanWt} orphan worktree dirs`);
+  const _reconcileFailed = cleaned.worktreeReconcileFailed || 0;
+  if (cleaned.tempFiles + cleaned.liveOutputs + cleaned.worktrees + cleaned.zombies + (cleaned.files || 0) + cleaned.orphanedDispatches + (cleaned.nestedWorktrees || 0) + _orphanTemp + _orphanWt + _reconcileFailed + cleaned.orphanManagedLogs > 0) {
+    log('info', `Cleanup: ${cleaned.tempFiles} temp, ${cleaned.liveOutputs} live outputs, ${cleaned.worktrees} worktrees, ${cleaned.zombies} zombies, ${cleaned.files || 0} archives, ${cleaned.orphanedDispatches} orphaned dispatches, ${cleaned.nestedWorktrees || 0} nested worktrees flagged, ${_orphanTemp} orphan temp dirs, ${_orphanWt} orphan worktree dirs, ${cleaned.orphanManagedLogs} orphan managed logs, ${_reconcileFailed} worktree reconcile failures`);
   }
 
   // 8. Clean swept KB files older than 7 days
@@ -1577,6 +1591,37 @@ async function runCleanup(config, verbose = false) {
     }
   } catch (e) { log('warn', `pruneCrashDiagnosticsReports: ${e.message}`); }
 
+  // 19. Review-learning retention (P-1ed2fb5f). Unresolved candidates expire
+  // after 180 days; compact lifecycle events are capped at one year AND 50000
+  // rows. Deliberately decoupled from KB file TTL — active procedural lessons
+  // persist until superseded or retracted, so this never touches active rows.
+  cleaned.expiredReviewCandidates = 0;
+  cleaned.prunedLifecycleEvents = 0;
+  try {
+    const memoryStore = require('./memory-store');
+    cleaned.expiredReviewCandidates = memoryStore.expireStaleReviewLearningCandidates();
+    cleaned.prunedLifecycleEvents = memoryStore.pruneMemoryLifecycleEvents();
+    if (cleaned.expiredReviewCandidates > 0 || cleaned.prunedLifecycleEvents > 0) {
+      log('info', `cleanup: expired ${cleaned.expiredReviewCandidates} review candidate(s), pruned ${cleaned.prunedLifecycleEvents} lifecycle event(s)`);
+    }
+  } catch (e) { log('warn', `review-learning retention: ${e.message}`); }
+
+  // 20. Recovery refs outlive the 24-hour quarantine-directory window so an
+  // operator can still recover preserved commits/WIP after directory cleanup.
+  // Bound that independent recovery window at 10 days.
+  cleaned.quarantineRefs = 0;
+  try {
+    const { pruneExpiredQuarantineRefs } = require('./quarantine-refs');
+    const result = await pruneExpiredQuarantineRefs(projects);
+    cleaned.quarantineRefs = result.removed;
+    if (result.removed > 0) {
+      log('info', `cleanup: pruned ${result.removed} quarantine recovery ref(s) older than 10 days`);
+    }
+    for (const failure of result.errors) {
+      log('warn', `quarantine-ref retention (${failure.project || 'unknown project'}): ${failure.error}`);
+    }
+  } catch (e) { log('warn', `quarantine-ref retention: ${e.message}`); }
+
   return cleaned;
 }
 
@@ -1615,13 +1660,18 @@ function scrubStaleMetrics() {
  *
  * Both pruners share the SAME `dispatchSnap` from `queries.getDispatch()`
  * so live work isn't yanked between scans. Returns aggregate stats for
- * tick-level logging.
+ * tick-level logging. When holder-reap retries are deferred, `stats.settled`
+ * resolves with the same object after its final counters are refreshed.
  */
 function runPeriodicWorktreeSweep(config) {
   const worktreeGc = require('./worktree-gc');
   const allProjects = getProjects(config);
   // PL-live-checkout-reliability-hardening — EXCLUDE live-checkout projects from
-  // the worktree GC entirely. The three pruners derive their targets from
+  // registry-derived destructive pruners. Filesystem reconciliation below still
+  // enumerates every configured repo: hybrid projects create worktrees for typed
+  // tasks, pure-live projects may retain residue from a prior mode, and every repo
+  // sharing a root must contribute registrations before any directory is deleted.
+  // The three legacy pruners derive their targets from
   // `git worktree list --porcelain`, which for a live project returns the
   // OPERATOR'S OWN primary checkout (and any secondary operator worktrees). The
   // engine never creates a managed worktree in live mode, so there is nothing
@@ -1636,8 +1686,15 @@ function runPeriodicWorktreeSweep(config) {
     try { return !shared.isLiveCheckoutProject(p); } catch { return false; } // W-mquoe8fu000w9383: fail-CLOSED — exclude from GC when checkout mode cannot be determined
   });
   const liveSkipped = allProjects.length - projects.length;
-  if (projects.length === 0) {
-    return { scanned: 0, kept: 0, evicted: 0, failed: 0, outOfRootEvicted: 0, prunedRegistry: 0, missingDirReclaimed: 0, missingDirSkippedLive: 0, liveProjectsSkipped: liveSkipped };
+  if (allProjects.length === 0) {
+    return {
+      scanned: 0, kept: 0, evicted: 0, failed: 0,
+      removed: 0, skipped: 0, preserved: 0,
+      outOfRootEvicted: 0, prunedRegistry: 0,
+      missingDirReclaimed: 0, missingDirSkippedLive: 0,
+      reconciledStaleDirs: 0, reconciledScanned: 0,
+      liveProjectsSkipped: liveSkipped,
+    };
   }
   const dispatchSnap = getDispatch();
   const worktreeRootRel = config?.engine?.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot;
@@ -1645,6 +1702,10 @@ function runPeriodicWorktreeSweep(config) {
 
   let scanned = 0, kept = 0, evicted = 0, failed = 0, outOfRootEvicted = 0, prunedRegistry = 0;
   let missingDirReclaimed = 0, missingDirSkippedLive = 0;
+  let reconciledStaleDirs = 0, reconciledScanned = 0;
+  let removed = 0, skipped = 0, preserved = 0;
+  let r0 = null, r1 = null, r2 = null, r3 = null;
+  const deferredRetries = [];
   const _writeToInbox = (a, s, c) => { try { return shared.writeToInbox(a, s, c); } catch (_e) { return false; } };
 
   // P-d8f1a3c6 — shell `git worktree list --porcelain` at most once per project
@@ -1655,7 +1716,7 @@ function runPeriodicWorktreeSweep(config) {
   // consumer's own self-shelling path. `pruneOrphanWorktrees` (r1, fs-readdir
   // based) never lists and is unaffected.
   const parsedTreesByProject = new Map();
-  for (const project of projects) {
+  for (const project of allProjects) {
     if (!project || !project.localPath) continue;
     let rootDir;
     try { rootDir = path.resolve(String(project.localPath)); } catch { continue; }
@@ -1674,44 +1735,103 @@ function runPeriodicWorktreeSweep(config) {
     }
   }
 
+  // Filesystem-authoritative reconciliation: Git registry sweeps cannot see
+  // directories left behind after their registration was pruned. Reconcile
+  // those stale, positively-owned dirs before the dispatch-oriented pruners.
   try {
-    const r1 = worktreeGc.pruneOrphanWorktrees({
-      projects, dispatchSnap, worktreeRootRel, log: _log, config, writeToInbox: _writeToInbox,
-    });
-    scanned += r1.scanned || 0;
-    kept += r1.kept || 0;
-    evicted += r1.evicted || 0;
-    failed += r1.failed || 0;
-  } catch (e) { log('warn', `worktree-gc periodic in-root: ${e.message}`); }
-
-  try {
-    const r2 = worktreeGc.pruneOrphanWorktreesFromGitRegistry({
-      projects, dispatchSnap, worktreeRootRel, log: _log, config, writeToInbox: _writeToInbox,
-      parsedTreesByProject,
+    r0 = worktreeGc.reconcileStaleWorktreeDirectories({
+      projects: allProjects, dispatchSnap, worktreeRootRel, log: _log, config,
+      parsedTreesByProject, writeToInbox: _writeToInbox,
     });
-    scanned += r2.scanned || 0;
-    kept += r2.kept || 0;
-    outOfRootEvicted += r2.evicted || 0;
-    failed += r2.failed || 0;
-    prunedRegistry += r2.prunedRegistry || 0;
-  } catch (e) { log('warn', `worktree-gc periodic out-of-root: ${e.message}`); }
+    reconciledScanned = r0.scanned || 0;
+    reconciledStaleDirs += r0.removed || 0;
+    failed += r0.failed || 0;
+    removed += r0.removed || 0;
+  } catch (e) {
+    failed++;
+    log('warn', `worktree-gc periodic filesystem reconcile: ${e.message}`);
+  }
 
   // W-mqifblkf00149df5 — reclaim locked-`initializing` worktree entries whose
-  // backing dir is MISSING. Neither pruner above touches these: the in-root
+  // backing dir is MISSING. Neither sibling pruner touches these: the in-root
   // scanner walks the filesystem (the dir is gone, so it's invisible) and the
   // out-of-root scanner deliberately skips dirs inside worktreeRoot and only
   // runs a plain `prune` that SKIPS locked entries. Without this, an
   // interrupted `git worktree add` bricks the branch until a human intervenes.
+  // Run this BEFORE either removal pruner mutates the registry represented by
+  // parsedTreesByProject. Otherwise a successful in-root eviction turns its
+  // once-present entry into a stale "missing" candidate and produces a false
+  // remove -f -f failure later in the same sweep.
   try {
-    const r3 = worktreeGc.reclaimMissingDirWorktrees({
+    r3 = worktreeGc.reclaimMissingDirWorktrees({
       projects, log: _log, config, parsedTreesByProject,
     });
+    scanned += r3.scanned || 0;
     missingDirReclaimed += r3.reclaimed || 0;
     missingDirSkippedLive += r3.skippedLive || 0;
     failed += r3.failed || 0;
+    removed += r3.removed ?? r3.reclaimed ?? 0;
+    skipped += r3.skipped ?? r3.skippedLive ?? 0;
+    preserved += r3.preserved || 0;
   } catch (e) { log('warn', `worktree-gc periodic missing-dir reclaim: ${e.message}`); }
 
-  return { scanned, kept, evicted, failed, outOfRootEvicted, prunedRegistry, missingDirReclaimed, missingDirSkippedLive, liveProjectsSkipped: liveSkipped };
+  if (r0) {
+    try {
+      r1 = worktreeGc.pruneOrphanWorktrees({
+        projects, dispatchSnap, worktreeRootRel, log: _log, config, writeToInbox: _writeToInbox,
+        deferredRetries,
+        protectedPaths: r0.protectedPaths,
+        failedRoots: r0.failedRoots,
+      });
+      scanned += r1.scanned || 0;
+      kept += r1.kept || 0;
+      evicted += r1.evicted || 0;
+      failed += r1.failed || 0;
+      removed += r1.removed ?? r1.evicted ?? 0;
+      skipped += r1.skipped || 0;
+      preserved += r1.preserved || 0;
+    } catch (e) { log('warn', `worktree-gc periodic in-root: ${e.message}`); }
+  } else {
+    log('warn', 'worktree-gc periodic in-root skipped because filesystem reconciliation did not complete');
+  }
+
+  try {
+    r2 = worktreeGc.pruneOrphanWorktreesFromGitRegistry({
+      projects, dispatchSnap, worktreeRootRel, log: _log, config, writeToInbox: _writeToInbox,
+      parsedTreesByProject, deferredRetries,
+    });
+    scanned += r2.scanned || 0;
+    kept += r2.kept || 0;
+    outOfRootEvicted += r2.evicted || 0;
+    failed += r2.failed || 0;
+    prunedRegistry += r2.prunedRegistry || 0;
+    removed += r2.removed ?? r2.evicted ?? 0;
+    skipped += r2.skipped || 0;
+    preserved += r2.preserved || 0;
+  } catch (e) { log('warn', `worktree-gc periodic out-of-root: ${e.message}`); }
+
+  const stats = {
+    scanned, kept, evicted, failed,
+    removed, skipped, preserved,
+    outOfRootEvicted, prunedRegistry,
+    missingDirReclaimed, missingDirSkippedLive,
+    reconciledStaleDirs, reconciledScanned,
+    liveProjectsSkipped: liveSkipped,
+  };
+  if (deferredRetries.length > 0) {
+    const settled = Promise.allSettled(deferredRetries).then(() => {
+      stats.evicted = r1?.evicted || 0;
+      stats.outOfRootEvicted = r2?.evicted || 0;
+      stats.failed = (r0?.failed || 0) + (r3?.failed || 0) + (r1?.failed || 0) + (r2?.failed || 0);
+      stats.removed = (r0?.removed || 0)
+        + (r3?.removed ?? r3?.reclaimed ?? 0)
+        + (r1?.removed ?? r1?.evicted ?? 0)
+        + (r2?.removed ?? r2?.evicted ?? 0);
+      return stats;
+    });
+    Object.defineProperty(stats, 'settled', { value: settled, enumerable: false });
+  }
+  return stats;
 }
 
 // ─── Exports ─────────────────────────────────────────────────────────────────
@@ -1729,4 +1849,6 @@ module.exports = {
   collectPhantomBranchesForProject, // P-e0b4f7a5 — exported for testing
   reapAgentScratch,                 // exported for testing
   reapKnowledgeScratch,             // exported for testing
+  pruneStaleEngineTmpFiles,         // exported for testing
+  pruneOrphanManagedLogs,           // exported for testing
 };