@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/worktrees/inventory.js

@@ -0,0 +1,671 @@
+/**
+ * engine/worktrees/inventory.js — worktree lifecycle observability
+ * (W-ms5tb6ha016fda10)
+ *
+ * The engine already has several destructive sweeps, but no read-only answer to
+ * the question an operator actually asks when `D:\worktrees` has 142 directories
+ * and only 6 registrations: *what are all these, and which ones is the engine
+ * ever going to clean up?*
+ *
+ * This module classifies every directory under each project's configured
+ * worktree root, plus every out-of-root git registration, into disjoint buckets:
+ *
+ *   active            — a non-terminal dispatch currently claims the path
+ *                       (`shared.isWorktreePathLive`). NEVER removable.
+ *   pooled            — a warm worktree-pool entry.
+ *   anchored          — held by a live keep_processes / managed_spawn cwd.
+ *   registered        — known to `git worktree list` but not claimed above.
+ *   ownedOrphan       — carries the engine ownership marker, unregistered, not
+ *                       live. THIS is the reclaimable backlog.
+ *   quarantined       — a `-quarantine-<ts>` recovery artifact (with the
+ *                       `protected` sub-count for the ones whose WIP has no
+ *                       durable recovery ref).
+ *   foreignUnmanaged  — no ownership marker. The engine must NEVER delete these.
+ *
+ * The disjoint buckets roll up into a `lifecycle` split (`owned` vs
+ * `foreignUnmanaged`) that is the ONLY supported source for any headline
+ * "how many worktrees does Minions have?" metric — see
+ * `summarizeLifecycleCounts`. A raw filesystem scan cannot answer that question
+ * without calling an operator's hand-made scratch checkout an active Minions
+ * worktree.
+ *
+ * It is strictly READ-ONLY: no git mutation, no filesystem writes, no removal.
+ * Every probe fails safe — a dir whose ownership cannot be determined counts as
+ * `foreignUnmanaged`, and a project whose git registry cannot be read reports an
+ * error entry rather than silently reporting zero orphans.
+ *
+ * Zero dependencies — Node built-ins + engine/core/shared + the sibling worktree
+ * modules. Cross-platform: all path comparison goes through the same
+ * normalizers the GC uses.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const shared = require('../core/shared');
+const worktreePool = require('./pool');
+const quarantineRefs = require('./quarantine-refs');
+
+// Bound the async pre-read fan-out the same way the sibling quarantine-ref
+// sweep does: enough parallelism to hide per-syscall latency, few enough
+// handles that a 150-directory root cannot exhaust the pool.
+const WORKTREE_PROBE_CONCURRENCY = 8;
+
+function _emptyBuckets() {
+  return {
+    active: 0,
+    pooled: 0,
+    anchored: 0,
+    registered: 0,
+    ownedOrphan: 0,
+    quarantined: 0,
+    quarantinedProtected: 0,
+    foreignUnmanaged: 0,
+    total: 0,
+  };
+}
+
+function _addBuckets(target, source) {
+  for (const key of Object.keys(target)) target[key] += source[key] || 0;
+  return target;
+}
+
+function _isLiveFailOpen(isWorktreePathLive, candidate, liveOpts) {
+  // Mirrors engine/worktrees/gc.js: SQL trouble means "assume live" so a
+  // reporting glitch can never make a live worktree look reclaimable.
+  try { return !!isWorktreePathLive(candidate, liveOpts); }
+  catch { return true; }
+}
+
+/**
+ * W-ms9q3dql00vxd4a8 — the default liveness probe, resolved ONCE per inventory
+ * build instead of once per directory. `shared.isWorktreePathLive` re-scans the
+ * whole pending+active dispatch set for every path it is asked about, which is
+ * the right trade for the handful of destructive wipe sites but costs O(n)
+ * queries when classifying a 150-directory worktree root on the dashboard's
+ * refresh path.
+ *
+ * The fail-open contract is identical: an unreadable dispatch table means
+ * "assume everything is live", never "assume everything is reclaimable".
+ */
+function _makeBatchedLiveProbe(db) {
+  let live;
+  try { live = shared.listLiveWorktreePaths(db ? { db } : undefined); }
+  catch { live = null; }
+  if (!live || live.ok !== true) return () => true;
+  return (candidate) => {
+    try { return live.paths.has(shared._normalizeWorktreePath(candidate)); }
+    catch { return true; }
+  };
+}
+
+function _collectAnchoredCwdPaths(listManagedSpecs, listKeepProcessCwds) {
+  const out = [];
+  try {
+    for (const rec of (listManagedSpecs() || [])) {
+      if (!rec || typeof rec.cwd !== 'string' || !rec.cwd) continue;
+      out.push(rec.cwd);
+    }
+  } catch { /* managed-spawn state unavailable */ }
+  try {
+    for (const cwd of (listKeepProcessCwds() || [])) {
+      if (typeof cwd !== 'string' || !cwd) continue;
+      out.push(cwd);
+    }
+  } catch { /* keep-process state unavailable */ }
+  return out;
+}
+
+function _collectAnchoredCwds(listManagedSpecs, listKeepProcessCwds) {
+  const out = [];
+  for (const cwd of _collectAnchoredCwdPaths(listManagedSpecs, listKeepProcessCwds)) {
+    try { out.push(shared.pathForComparison(cwd)); } catch { /* unreadable cwd */ }
+  }
+  return out;
+}
+
+/**
+ * W-ms9q3dql00vxd4a8 — anchors are resolved to their COMPARISON form once per
+ * build, not once per candidate.
+ *
+ * `shared.isPathInsideOrEqual` symlink-resolves BOTH sides on every call, so the
+ * old shape cost O(directories x anchors) `realpathSync` syscalls: a single live
+ * managed-spawn service turned a 150-directory root into a >100 ms synchronous
+ * block on the dashboard's event loop. Comparing pre-resolved paths through the
+ * shared containment rule keeps the semantics byte-for-byte and drops the
+ * per-candidate cost to one resolution.
+ */
+function _isAnchored(candidate, ctx) {
+  if (!ctx.anchoredCwds.length) return false;
+  let candidateCompare;
+  try { candidateCompare = ctx.comparePathFor(candidate); } catch { return false; }
+  for (const cwd of ctx.anchoredCwds) {
+    try { if (shared.isResolvedPathInsideOrEqual(cwd, candidateCompare)) return true; }
+    catch { /* incomparable paths are not anchors */ }
+  }
+  return false;
+}
+
+function _isQuarantineDirName(name) {
+  return /-quarantine-(?:protected-)?\d+(?:$|-)/.test(String(name || ''));
+}
+
+/**
+ * Count dispatches that ran without allocating a repository checkout because
+ * they declared the control-plane execution surface. Derived from the dispatch
+ * record itself (`executionSurface`), so there is no counter to migrate, reset,
+ * or drift out of sync with reality.
+ */
+function countAvoidedAllocations(dispatchSnap) {
+  const surface = shared.EXECUTION_SURFACE.CONTROL_PLANE;
+  let active = 0;
+  let completed = 0;
+  for (const entry of (Array.isArray(dispatchSnap?.active) ? dispatchSnap.active : [])) {
+    if (entry?.executionSurface === surface) active++;
+  }
+  for (const entry of (Array.isArray(dispatchSnap?.completed) ? dispatchSnap.completed : [])) {
+    if (entry?.executionSurface === surface) completed++;
+  }
+  return { active, completed, total: active + completed };
+}
+
+function _classifyDirectory(candidate, ctx) {
+  const name = path.basename(candidate);
+  const normalized = worktreePool._normalizePath(candidate);
+
+  if (_isLiveFailOpen(ctx.isWorktreePathLive, candidate, ctx.liveOpts)) return 'active';
+  if (ctx.poolPaths.has(normalized)) return 'pooled';
+  if (_isAnchored(candidate, ctx)) return 'anchored';
+
+  let owned = false;
+  try { owned = !!ctx.hasWorktreeOwnerMarker(candidate); } catch { owned = false; }
+
+  if (_isQuarantineDirName(name)) {
+    // A quarantine dir is always engine residue: it is a rename of a worktree
+    // the engine itself created. Report it as quarantined regardless of whether
+    // the marker survived the rename, but never let that reclassify a dir the
+    // engine cannot prove it owns — an unmarked one is still reported under
+    // `foreignUnmanaged` for the removal decision.
+    return owned ? 'quarantined' : 'foreignUnmanaged';
+  }
+  if (!owned) return 'foreignUnmanaged';
+  if (ctx.registeredPaths.has(normalized)) return 'registered';
+  return 'ownedOrphan';
+}
+
+/**
+ * Build the read-only worktree inventory.
+ *
+ * @param {object} opts
+ * @param {Array<{name?:string, localPath?:string}>} opts.projects
+ * @param {object} [opts.dispatchSnap]  — `{active, pending, completed}` snapshot
+ * @param {object} [opts.config]        — for `engine.worktreeRoot`
+ * @param {Map}    [opts.parsedTreesByProject] — pre-read `git worktree list`
+ *   output keyed on resolved localPath, so an async caller can pay the git
+ *   shell-out cost off the event loop (same injection shape as
+ *   engine/orchestration/cleanup.js uses for the GC pruners).
+ * @param {Map}    [opts.entriesByWorktreeRoot] — pre-read worktree-root
+ *   directory listings keyed on the resolved worktree root.
+ * @param {Map}    [opts.probesByPath] — pre-read per-directory filesystem
+ *   probes (ownership marker, protected-quarantine marker, comparison path)
+ *   keyed on the normalized directory path. Any path missing from the map (or
+ *   any field missing from its record) falls back to the real synchronous
+ *   probe, so a partial pre-read can never change a classification.
+ * Injection points (all optional, default to the real implementations) mirror
+ * engine/worktrees/gc.js so unit tests can drive this deterministically:
+ *   fs, execSilent, parseWorktreePorcelain, isWorktreePathLive,
+ *   hasWorktreeOwnerMarker, hasProtectedQuarantineMarker, listPoolPaths,
+ *   listManagedSpecs, listKeepProcessCwds, db
+ * @returns {{ perProject: object, totals: object, avoidedAllocations: object,
+ *             recoverableRefs: object, errors: Array }}
+ */
+function buildWorktreeInventory(opts = {}) {
+  const projects = (Array.isArray(opts.projects) ? opts.projects : [])
+    .filter(p => p && p.localPath);
+  const _fs = opts.fs || fs;
+  const _execSilent = typeof opts.execSilent === 'function' ? opts.execSilent : shared.execSilent;
+  const _parsePorcelain = typeof opts.parseWorktreePorcelain === 'function'
+    ? opts.parseWorktreePorcelain
+    : shared.parseWorktreePorcelain;
+  const _parsedTreesByProject = opts.parsedTreesByProject instanceof Map
+    ? opts.parsedTreesByProject
+    : null;
+  const _entriesByWorktreeRoot = opts.entriesByWorktreeRoot instanceof Map
+    ? opts.entriesByWorktreeRoot
+    : null;
+  const _probesByPath = opts.probesByPath instanceof Map ? opts.probesByPath : null;
+  const _probeFor = (candidate) => {
+    if (!_probesByPath) return null;
+    try { return _probesByPath.get(worktreePool._normalizePath(candidate)) || null; }
+    catch { return null; }
+  };
+  const ctx = {
+    isWorktreePathLive: typeof opts.isWorktreePathLive === 'function'
+      ? opts.isWorktreePathLive
+      : _makeBatchedLiveProbe(opts.db),
+    // A pre-read probe is used when present; anything the async pre-read could
+    // not resolve falls through to the real synchronous helper, so the
+    // fail-safe direction of each classification is unchanged.
+    hasWorktreeOwnerMarker: typeof opts.hasWorktreeOwnerMarker === 'function'
+      ? opts.hasWorktreeOwnerMarker
+      : (candidate) => {
+        const probe = _probeFor(candidate);
+        return typeof probe?.ownerMarker === 'boolean'
+          ? probe.ownerMarker
+          : shared.hasWorktreeOwnerMarker(candidate);
+      },
+    comparePathFor: (candidate) => {
+      const probe = _probeFor(candidate);
+      return probe?.comparePath || shared.pathForComparison(candidate);
+    },
+    liveOpts: opts.db ? { db: opts.db } : undefined,
+    anchoredCwds: Array.isArray(opts.anchoredCwds)
+      ? opts.anchoredCwds
+      : _collectAnchoredCwds(
+        typeof opts.listManagedSpecs === 'function'
+          ? opts.listManagedSpecs
+          : () => require('../processes/managed-spawn').listManagedSpecs(),
+        typeof opts.listKeepProcessCwds === 'function'
+          ? opts.listKeepProcessCwds
+          : () => require('../processes/keep-process-sweep').getActiveKeepProcessCwds(),
+      ),
+    poolPaths: new Set(),
+    registeredPaths: new Set(),
+  };
+  const hasProtectedQuarantineMarker = typeof opts.hasProtectedQuarantineMarker === 'function'
+    ? opts.hasProtectedQuarantineMarker
+    : (candidate) => {
+      const probe = _probeFor(candidate);
+      return typeof probe?.protectedQuarantineMarker === 'boolean'
+        ? probe.protectedQuarantineMarker
+        : shared.hasProtectedQuarantineMarker(candidate);
+    };
+  const listPoolPaths = typeof opts.listPoolPaths === 'function'
+    ? opts.listPoolPaths
+    : (project) => {
+      try {
+        return [
+          ...(worktreePool.getActiveBorrowedPaths(project) || []),
+          ...(worktreePool.getIdlePaths(project) || []),
+        ];
+      } catch { return []; }
+    };
+
+  const worktreeRootRel = opts.config?.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot;
+  const perProject = {};
+  const totals = _emptyBuckets();
+  const errors = [];
+  // W-ms9q3dql00vxd4a8 — dedupe ACROSS projects, not just within one. Two
+  // projects whose `worktreeRoot` resolves to the same directory (the
+  // monorepo-style layout the GC already groups by root) otherwise classify
+  // every directory twice and double the reported total. Attribution goes to
+  // the first project that claims the root; `perProject[label].worktreeRoot`
+  // still identifies which root each project resolved to.
+  const seen = new Set();
+
+  for (const project of projects) {
+    const label = project.name || project.localPath;
+    const rootDir = path.resolve(String(project.localPath));
+    const buckets = _emptyBuckets();
+
+    ctx.poolPaths = new Set(
+      (listPoolPaths(project) || [])
+        .filter(p => typeof p === 'string' && p)
+        .map(p => worktreePool._normalizePath(p)),
+    );
+
+    // Registered paths come from git itself. A read failure is REPORTED, never
+    // treated as "nothing is registered" — that inversion would relabel every
+    // live worktree as an orphan.
+    ctx.registeredPaths = new Set();
+    const outOfRoot = [];
+    let worktreeRoot;
+    try { worktreeRoot = path.resolve(rootDir, worktreeRootRel); }
+    catch { worktreeRoot = null; }
+    let registryReadable = false;
+    try {
+      let trees;
+      if (_parsedTreesByProject && _parsedTreesByProject.has(rootDir)) {
+        trees = _parsedTreesByProject.get(rootDir);
+        if (!Array.isArray(trees)) throw new Error('pre-read worktree registry is not an array');
+      } else {
+        const raw = String(_execSilent('git --no-optional-locks worktree list --porcelain', {
+          cwd: rootDir, timeout: 15000, windowsHide: true,
+        }) || '');
+        trees = _parsePorcelain(raw) || [];
+      }
+      for (const tree of trees) {
+        if (!tree?.path) continue;
+        const abs = path.resolve(tree.path);
+        if (worktreePool._normalizePath(abs) === worktreePool._normalizePath(rootDir)) continue;
+        ctx.registeredPaths.add(worktreePool._normalizePath(abs));
+        if (worktreeRoot && !shared.isPathInsideOrEqual(worktreeRoot, abs)) outOfRoot.push(abs);
+      }
+      registryReadable = true;
+    } catch (e) {
+      errors.push({ project: label, scope: 'git-registry', error: e?.message || String(e) });
+    }
+
+    let entries = [];
+    if (worktreeRoot) {
+      const preRead = _entriesByWorktreeRoot ? _entriesByWorktreeRoot.get(worktreeRoot) : null;
+      if (Array.isArray(preRead)) {
+        entries = preRead;
+      } else {
+        try {
+          entries = _fs.readdirSync(worktreeRoot, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && !shared.isWorktreeRootInfraEntry(entry.name))
+            .map(entry => path.join(worktreeRoot, entry.name));
+        } catch (e) {
+          if (e?.code !== 'ENOENT') {
+            errors.push({ project: label, scope: 'worktree-root', error: e?.message || String(e) });
+          }
+        }
+      }
+    }
+
+    const seenBefore = seen.size;
+    for (const candidate of [...entries, ...outOfRoot]) {
+      const normalized = worktreePool._normalizePath(candidate);
+      if (seen.has(normalized)) continue;
+      seen.add(normalized);
+      // Without a readable registry we cannot distinguish `registered` from
+      // `ownedOrphan`, so an owned dir is reported as `registered` (the
+      // conservative direction — nothing gets reported as reclaimable).
+      let bucket = _classifyDirectory(candidate, ctx);
+      if (!registryReadable && bucket === 'ownedOrphan') bucket = 'registered';
+      buckets[bucket]++;
+      buckets.total++;
+      if (bucket === 'quarantined') {
+        let isProtected = true;
+        try { isProtected = !!hasProtectedQuarantineMarker(candidate); } catch { isProtected = true; }
+        if (isProtected) buckets.quarantinedProtected++;
+      }
+    }
+
+    perProject[label] = {
+      ...buckets,
+      worktreeRoot: worktreeRoot || null,
+      registryReadable,
+      // True when every directory under this project's root was already
+      // classified for an earlier project sharing the same root.
+      sharedRoot: seen.size === seenBefore && (entries.length + outOfRoot.length) > 0,
+    };
+    _addBuckets(totals, buckets);
+  }
+
+  return {
+    perProject,
+    totals,
+    lifecycle: _summarizeLifecycle(totals),
+    avoidedAllocations: countAvoidedAllocations(opts.dispatchSnap),
+    errors,
+  };
+}
+
+/**
+ * W-ms9q3dql00vxd4a8 — the lifecycle-owned split, derived from the SAME buckets
+ * the inventory already produces so there is exactly one classifier.
+ *
+ * `owned` is every directory the engine's own lifecycle created and is
+ * therefore responsible for: live dispatches, warm pool members, process
+ * anchors, git-registered worktrees, reclaimable owned orphans, and quarantine
+ * residue on its retention clock. `foreignUnmanaged` is everything the engine
+ * has NO ownership proof for — operator scratch worktrees and unclassifiable
+ * residue — which stays fail-open and must never be presented as an active
+ * Minions worktree.
+ */
+function _summarizeLifecycle(totals) {
+  const buckets = totals || _emptyBuckets();
+  const total = Number(buckets.total) || 0;
+  const foreignUnmanaged = Number(buckets.foreignUnmanaged) || 0;
+  return {
+    owned: Math.max(0, total - foreignUnmanaged),
+    foreignUnmanaged,
+    total,
+  };
+}
+
+function summarizeLifecycleCounts(inventory) {
+  return _summarizeLifecycle(inventory?.totals);
+}
+
+/**
+ * Pre-read `git worktree list --porcelain` for each project WITHOUT blocking
+ * the event loop, keyed on the resolved localPath so `buildWorktreeInventory`
+ * can skip its synchronous shell-out. A per-project failure is left unset so
+ * the sync builder falls back to self-shelling and still reports the error.
+ */
+async function readWorktreeRegistriesAsync(opts = {}) {
+  const parse = typeof opts.parseWorktreePorcelain === 'function'
+    ? opts.parseWorktreePorcelain
+    : shared.parseWorktreePorcelain;
+  const runGit = typeof opts.shellSafeGit === 'function' ? opts.shellSafeGit : shared.shellSafeGit;
+  const map = new Map();
+  for (const project of (Array.isArray(opts.projects) ? opts.projects : [])) {
+    if (!project?.localPath) continue;
+    let rootDir;
+    try { rootDir = path.resolve(String(project.localPath)); } catch { continue; }
+    if (map.has(rootDir)) continue;
+    try {
+      const raw = await runGit(['--no-optional-locks', 'worktree', 'list', '--porcelain'], {
+        cwd: rootDir, timeout: 15000,
+      });
+      const trees = parse(String(raw || ''));
+      if (Array.isArray(trees)) map.set(rootDir, trees);
+    } catch { /* leave unset — the sync builder self-shells and records the error */ }
+  }
+  return map;
+}
+
+/**
+ * Pre-read each project's worktree-root directory listing WITHOUT blocking the
+ * event loop, keyed on the resolved worktree root. A root that does not exist
+ * yet maps to an empty list (the sync builder's ordinary ENOENT case); any
+ * OTHER failure is left unset so the sync builder re-reads it and records the
+ * error, exactly as it does today.
+ */
+async function readWorktreeRootEntriesAsync(opts = {}) {
+  // Honor an injected `fs` when it exposes the promises API, so the async
+  // pre-read obeys exactly the same injection contract as the sync builder
+  // instead of quietly reaching past it to the real filesystem.
+  const readdir = typeof opts.fs?.promises?.readdir === 'function'
+    ? opts.fs.promises.readdir
+    : fs.promises.readdir;
+  const worktreeRootRel = opts.config?.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot;
+  const map = new Map();
+  for (const project of (Array.isArray(opts.projects) ? opts.projects : [])) {
+    if (!project?.localPath) continue;
+    let worktreeRoot;
+    try { worktreeRoot = path.resolve(path.resolve(String(project.localPath)), worktreeRootRel); }
+    catch { continue; }
+    if (map.has(worktreeRoot)) continue;
+    try {
+      const dirents = await readdir(worktreeRoot, { withFileTypes: true });
+      map.set(worktreeRoot, dirents
+        .filter(entry => entry.isDirectory() && !shared.isWorktreeRootInfraEntry(entry.name))
+        .map(entry => path.join(worktreeRoot, entry.name)));
+    } catch (e) {
+      if (e?.code === 'ENOENT') map.set(worktreeRoot, []);
+    }
+  }
+  return map;
+}
+
+/**
+ * Every directory the classifier could ask about: a SUPERSET is deliberate and
+ * safe — an unused probe costs one map entry, while a missing one silently
+ * falls back to a synchronous syscall. Building the superset from the two
+ * pre-reads avoids re-deriving the builder's in-root/out-of-root split here.
+ */
+function _probeCandidates(entriesByWorktreeRoot, parsedTreesByProject) {
+  const out = new Set();
+  for (const entries of entriesByWorktreeRoot.values()) {
+    for (const entry of (Array.isArray(entries) ? entries : [])) out.add(entry);
+  }
+  for (const trees of parsedTreesByProject.values()) {
+    for (const tree of (Array.isArray(trees) ? trees : [])) {
+      if (!tree?.path) continue;
+      try { out.add(path.resolve(tree.path)); } catch { /* unusable registry path */ }
+    }
+  }
+  return [...out];
+}
+
+/**
+ * Pre-read the per-directory filesystem probes the classifier needs — the
+ * ownership marker, the protected-quarantine marker, and the symlink-resolved
+ * comparison path — with bounded concurrency and no synchronous syscalls.
+ *
+ * A probe that fails is simply not recorded, so the synchronous classifier
+ * re-probes that one path and applies its own fail-safe. The pre-read can
+ * therefore only make the scan cheaper, never change what it reports.
+ */
+async function readWorktreeProbesAsync(candidates, opts = {}) {
+  const ownerMarkerProbe = typeof opts.hasWorktreeOwnerMarkerAsync === 'function'
+    ? opts.hasWorktreeOwnerMarkerAsync
+    : shared.hasWorktreeOwnerMarkerAsync;
+  const protectedProbe = typeof opts.hasProtectedQuarantineMarkerAsync === 'function'
+    ? opts.hasProtectedQuarantineMarkerAsync
+    : shared.hasProtectedQuarantineMarkerAsync;
+  const resolveCompare = typeof opts.pathForComparisonAsync === 'function'
+    ? opts.pathForComparisonAsync
+    : shared.pathForComparisonAsync;
+
+  const list = [...new Set((Array.isArray(candidates) ? candidates : [])
+    .filter(candidate => typeof candidate === 'string' && candidate))];
+  const map = new Map();
+  await shared.mapWithConcurrency(list, WORKTREE_PROBE_CONCURRENCY, async (candidate) => {
+    const probe = {};
+    let usable = false;
+    try { probe.ownerMarker = !!(await ownerMarkerProbe(candidate)); usable = true; }
+    catch { /* fall back to the synchronous probe for this path */ }
+    try { probe.comparePath = await resolveCompare(candidate); usable = true; }
+    catch { /* ditto */ }
+    if (_isQuarantineDirName(path.basename(candidate))) {
+      try { probe.protectedQuarantineMarker = !!(await protectedProbe(candidate)); usable = true; }
+      catch { /* ditto */ }
+    }
+    if (!usable) return;
+    try { map.set(worktreePool._normalizePath(candidate), probe); } catch { /* unusable key */ }
+  });
+  return map;
+}
+
+/**
+ * Resolve the anchored `keep_processes` / `managed_spawn` cwds to their
+ * comparison form off the event loop. Resolved with the SAME async twin the
+ * candidate paths use, so both sides of every containment test agree.
+ *
+ * A cwd the async resolver cannot handle falls back to the synchronous helper
+ * rather than being dropped: losing an anchor silently downgrades a HELD
+ * worktree to `ownedOrphan`, which is the reclaimable bucket. Only a path that
+ * neither resolver can read is dropped — the pre-existing behaviour.
+ */
+async function _readAnchoredCwdsAsync(opts = {}) {
+  const resolveCompare = typeof opts.pathForComparisonAsync === 'function'
+    ? opts.pathForComparisonAsync
+    : shared.pathForComparisonAsync;
+  const raw = _collectAnchoredCwdPaths(
+    typeof opts.listManagedSpecs === 'function'
+      ? opts.listManagedSpecs
+      : () => require('../processes/managed-spawn').listManagedSpecs(),
+    typeof opts.listKeepProcessCwds === 'function'
+      ? opts.listKeepProcessCwds
+      : () => require('../processes/keep-process-sweep').getActiveKeepProcessCwds(),
+  );
+  const out = [];
+  for (const cwd of raw) {
+    let resolved = null;
+    try { resolved = await resolveCompare(cwd); }
+    catch { /* fall through to the synchronous resolver */ }
+    if (!resolved) {
+      try { resolved = shared.pathForComparison(cwd); } catch { /* unreadable cwd */ }
+    }
+    if (resolved) out.push(resolved);
+  }
+  return out;
+}
+
+/**
+ * Async front door for callers that must not block the event loop (the
+ * dashboard's background worktree-count refresh and `GET
+ * /api/worktree-inventory`). Every filesystem and git cost is paid
+ * asynchronously up front; the SAME synchronous classifier then runs over the
+ * pre-read results, so the count and the inventory page can never disagree.
+ *
+ * W-ms9q3dql00vxd4a8 — the pre-reads are what keep the invariant honest.
+ * Classification itself is a tight loop over N directories, so leaving its
+ * probes synchronous made the whole scan one contiguous blocking block whose
+ * cost scales with the `foreignUnmanaged` residue the engine deliberately never
+ * reclaims. Measured on a 150-directory root with three live process anchors:
+ * >100 ms of event-loop stall every `worktreeCountCacheTtl`, against the 100 ms
+ * budget /api/status has to stay inside.
+ */
+async function buildWorktreeInventoryAsync(opts = {}) {
+  const parsedTreesByProject = opts.parsedTreesByProject instanceof Map
+    ? opts.parsedTreesByProject
+    : await readWorktreeRegistriesAsync(opts);
+  const entriesByWorktreeRoot = opts.entriesByWorktreeRoot instanceof Map
+    ? opts.entriesByWorktreeRoot
+    : await readWorktreeRootEntriesAsync(opts);
+  const anchoredCwds = Array.isArray(opts.anchoredCwds)
+    ? opts.anchoredCwds
+    : await _readAnchoredCwdsAsync(opts);
+  const probesByPath = opts.probesByPath instanceof Map
+    ? opts.probesByPath
+    : await readWorktreeProbesAsync(
+      _probeCandidates(entriesByWorktreeRoot, parsedTreesByProject),
+      opts,
+    );
+  return buildWorktreeInventory({
+    ...opts,
+    parsedTreesByProject,
+    entriesByWorktreeRoot,
+    anchoredCwds,
+    probesByPath,
+  });
+}
+
+/**
+ * Async wrapper that also resolves the recoverable quarantine refs (a git
+ * shell-out per project). Kept separate so the pure classification above stays
+ * synchronous and directly unit-testable.
+ */
+async function buildWorktreeInventoryWithRefs(opts = {}) {
+  const inventory = await buildWorktreeInventoryAsync(opts);
+  let refs = [];
+  try {
+    refs = await (typeof opts.listQuarantineRefs === 'function'
+      ? opts.listQuarantineRefs(opts.projects || [])
+      : quarantineRefs.listQuarantineRefs(opts.projects || []));
+  } catch (e) {
+    inventory.errors.push({ scope: 'quarantine-refs', error: e?.message || String(e) });
+  }
+  const items = Array.isArray(refs) ? refs : [];
+  inventory.recoverableRefs = {
+    total: items.filter(item => item && !item.error).length,
+    wip: items.filter(item => item && item.kind === 'wip').length,
+    commits: items.filter(item => item && item.kind === 'commits').length,
+    // W-ms87rbe601a66d13 — report the window actually in effect (operator
+    // override included), not the built-in constant, so the inventory does not
+    // advertise a 30-day recovery story on an install that shortened it.
+    retentionMs: shared.resolveQuarantineRetentionMs(opts.config),
+  };
+  for (const item of items) {
+    if (item && item.error) inventory.errors.push({ project: item.project, scope: 'quarantine-refs', error: item.error });
+  }
+  return inventory;
+}
+
+module.exports = {
+  buildWorktreeInventory,
+  buildWorktreeInventoryAsync,
+  buildWorktreeInventoryWithRefs,
+  readWorktreeRegistriesAsync,
+  readWorktreeRootEntriesAsync,
+  readWorktreeProbesAsync,
+  summarizeLifecycleCounts,
+  countAvoidedAllocations,
+  _isQuarantineDirName, // exported for testing
+};