gitnexus 1.6.10-rc.2 → 1.6.10-rc.21

package/dist/core/lbug/sidecar-recovery.js

@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
+import { HANDLE_RELEASE_PROBE_ATTEMPTS, HANDLE_RELEASE_PROBE_DELAY_MS, sleep, } from './lbug-config.js';
 export const TINY_ORPHAN_WAL_BYTES = 4 * 1024;
 /**
  * Counter-based warn anti-spam (PR #1747 review, Finding 6).
@@ -87,16 +88,47 @@ const warnOnce = (logger, key, message) => {
     logger.warn(`${message} (${ordinal(next)} occurrence of this condition)`);
 };
 // LADYBUGDB-CONTRACT: matches @ladybugdb/core ^0.18.0 native error text.
-// When bumping LadybugDB, re-validate this regex against the new error format
+// When bumping LadybugDB, re-validate this against the new error format
 // — `git grep "LADYBUGDB-CONTRACT"` enumerates every version-coupled spot.
-// Verified by upstream source/changelog diff only — forcing a genuine
-// `.shadow`-missing state via a live crash to trigger this error is not
-// reliably reproducible (a SIGKILL at the exact moment `.shadow` exists on
-// disk still recovers via `.wal.checkpoint` alone), so this matcher does not
-// have live-trigger test coverage.
+//
+// Two native formats reach here for a genuinely-missing shadow sidecar:
+//   POSIX:   `Cannot open file <path>.shadow: No such file or directory`
+//   Windows: `Cannot open file. path: <path>.shadow - Error 2: <system text>`
+// Windows OS text is localized on non-English installs (issue #2382 was filed
+// from a non-English Windows), so we key on the locale-invariant Win32 code
+// (2 = ERROR_FILE_NOT_FOUND), NOT the English phrase. The code is matched only
+// in the reason AFTER the LAST `.shadow` token (the real failing sidecar; the
+// reason text never contains `.shadow`), so a repo *path* containing e.g.
+// `\error 2\` — even under a `.shadow`-suffixed parent directory — cannot trip
+// it. Deliberate exclusions:
+//   - `Error 3` (ERROR_PATH_NOT_FOUND): the #1811 non-ASCII path-garble
+//     artifact (see lbug-config.ts) where the shadow is PRESENT on disk;
+//     treating it as missing would quarantine a live WAL — data loss.
+//   - `Error 5` / `Error 32` / POSIX `Permission denied`: present-but-locked;
+//     handled as permission/lock classes, must not quarantine.
+// The quarantine path adds a present-shadow disk check as a belt (see
+// refuseLargeWalQuarantine in lbug-adapter.ts).
+//
+// The Windows branch is derived from the issue #2382 reported string, not a
+// self-produced live crash; unit/consumer tests inject that same string, so
+// GREEN TESTS DO NOT PROVE the byte-exact 0.18.0 Windows format — confirm
+// against a real Windows run before closing #2382.
 export const isMissingShadowSidecarError = (err) => {
     const msg = err instanceof Error ? err.message : String(err);
-    return /Cannot open file .*\.shadow: No such file or directory/i.test(msg);
+    if (!/cannot open file/i.test(msg))
+        return false;
+    // Anchor on the LAST `.shadow`, not the first: LadybugDB names the failing
+    // sidecar as the final `.shadow` token and its reason text (POSIX
+    // `: No such file or directory` / Windows ` - Error N: ...`) never contains
+    // `.shadow`. Slicing from the last match isolates the true reason, so an
+    // earlier `.shadow`-suffixed path segment (e.g. a `branch=subdir` directory
+    // like `snap.shadow\`) can't shift the anchor and let a path-embedded
+    // `error 2` be read as the Win32 code (issue #2382 review, Finding A).
+    const lastShadow = [...msg.matchAll(/\.shadow\b/gi)].at(-1);
+    if (lastShadow?.index === undefined)
+        return false;
+    const reason = msg.slice(lastShadow.index);
+    return /no such file or directory/i.test(reason) || /\berror\s+2\b/i.test(reason);
 };
 // LADYBUGDB-CONTRACT: matches @ladybugdb/core ^0.18.0 native error text.
 // When bumping LadybugDB, re-validate this regex against the new error format
@@ -114,11 +146,44 @@ export const shadowSidecarRecoveryMessage = (dbPath, err) => {
         'Rebuild the index with `gitnexus analyze --force <repo-path> --index-only` and restart `gitnexus serve`.' +
         `\n  Original error: ${msg.slice(0, 200)}`);
 };
+/**
+ * Actionable message for the case where LadybugDB reports a "missing shadow"
+ * but `inspectLbugSidecars` finds the `.shadow` PRESENT on disk — the open
+ * failed on path reachability or a lock, not a genuinely-missing sidecar (issue
+ * #2382 review, S2). Unlike `shadowSidecarRecoveryMessage` it does NOT tell the
+ * operator to rebuild the index (the remedy is fixing the lock/path). Keeps the
+ * `Original error:` tail so downstream `isMissingShadowSidecarError` recognition
+ * still matches the wrapped error.
+ */
+export const presentShadowUnreachableMessage = (dbPath, err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    return (`LadybugDB checkpoint sidecar is present but unreachable for ${dbPath}. ` +
+        'The .shadow file is on disk, so the open likely failed on path reachability or a file lock ' +
+        '(antivirus, another process holding a handle, or a non-ASCII path) rather than a missing sidecar. ' +
+        'Check filesystem access and locks; only run `gitnexus analyze --force <repo-path> --index-only` ' +
+        'if the index is genuinely broken.' +
+        `\n  Original error: ${msg.slice(0, 200)}`);
+};
 const PERMISSION_RENAME_CODES = new Set(['EACCES', 'EPERM', 'EBUSY']);
 export const isPermissionRenameError = (err) => {
     const code = err?.code;
     return typeof code === 'string' && PERMISSION_RENAME_CODES.has(code);
 };
+/**
+ * Canonical remediation guidance for the LadybugDB file-lock class
+ * (EBUSY/EPERM/EACCES — an MCP/serve process holding the index, or an
+ * antivirus scan). One exported producer (this shipping review, FIX 7):
+ * the dirty-recovery park warning below, `LbugWipeError`'s message builder
+ * (lbug-adapter.ts) and {@link renameFailureMessage} previously carried
+ * three divergent hand-written copies of the same advice.
+ *
+ * `rerun` names the command to retry once the lock clears — the analyze
+ * wipe/park surfaces re-run the analyze; the read-path quarantine surface
+ * re-runs whatever command failed. No trailing period: callers own the
+ * sentence end.
+ */
+export const lbugLockRemediation = (rerun = 're-run `gitnexus analyze`') => 'stop any GitNexus MCP or serve process using this repository, add an antivirus ' +
+    `exclusion for the GitNexus storage directory, then ${rerun}`;
 /**
  * Classify a failure surfaced by quarantine rename into an actionable user-facing
  * message.
@@ -140,10 +205,10 @@ export const renameFailureMessage = (dbPath, err) => {
         const msg = err instanceof Error ? err.message : String(err);
         return (`GitNexus could not move the LadybugDB WAL sidecar at ${dbPath}.wal because of a ` +
             `filesystem permission or file-lock error (${code}). ` +
-            'Check filesystem ACLs, antivirus exclusions for the index directory, and ' +
-            'whether another process holds an open handle on the file. ' +
-            'The index does not need to be rebuilt — re-running the failing command after ' +
-            'resolving the lock or permission should succeed.' +
+            'The index does not need to be rebuilt — ' +
+            // Shared remediation copy (FIX 7); this surface serves read paths too,
+            // so the re-run target is the failing command, not the analyze.
+            `${lbugLockRemediation('re-run the failing command once the lock or permission is resolved')}.` +
             `\n  Original error: ${msg.slice(0, 200)}`);
     }
     return shadowSidecarRecoveryMessage(dbPath, err);
@@ -165,6 +230,41 @@ export async function inspectLbugSidecars(dbPath) {
     }
     return { kind: 'clean', dbPath };
 }
+/**
+ * Reject the WAL-quarantine path when discarding the WAL would be unsafe or
+ * wrong. Shared by every reactive missing-shadow recovery consumer — serve (via
+ * lbug-adapter's `refuseLargeWalQuarantine`) and the MCP/wiki/augmentation pool
+ * (via pool-adapter's `tryQuarantineForMissingShadow`) — so the quarantine
+ * safety policy has a single source of truth (issue #2382 review, Finding B).
+ *
+ *   1. `wal-with-shadow` — the `.shadow` sidecar is PRESENT on disk. A
+ *      "missing shadow" error alongside a present shadow means the open failed
+ *      on path reachability or a lock (the #1811 non-ASCII path-garble on
+ *      Windows), not a genuinely-missing shadow; quarantining would move a live
+ *      WAL sitting next to its shadow — data loss.
+ *   2. `orphan-wal` — the orphan WAL is too large to safely discard
+ *      (>TINY_ORPHAN_WAL_BYTES); preserve the uncheckpointed pages for explicit
+ *      operator recovery.
+ *
+ * Throws `shadowSidecarRecoveryMessage` in either case. Returns silently only
+ * when the shadow is absent AND the WAL is absent or tiny — the states where
+ * the existing recovery path is safe to proceed. `mode` is a label used only in
+ * the warning text (e.g. 'read-only', 'writable', 'pool read-only recovery').
+ */
+export const guardWalQuarantine = async (dbPath, mode, triggeringErr, logger) => {
+    const state = await inspectLbugSidecars(dbPath);
+    if (state.kind === 'wal-with-shadow') {
+        warnOnce(logger, `${dbPath}:present-shadow-refuse:${mode}`, `GitNexus: refusing to quarantine WAL at ${dbPath}.wal during ${mode} recovery — ` +
+            'the .shadow sidecar is present on disk, so the open likely failed on path reachability or a lock ' +
+            'rather than a missing shadow. Run `gitnexus analyze --force <repo-path> --index-only` if the index is genuinely broken.');
+        throw new Error(presentShadowUnreachableMessage(dbPath, triggeringErr));
+    }
+    if (state.kind === 'orphan-wal') {
+        warnOnce(logger, `${dbPath}:large-wal-refuse:${mode}`, `GitNexus: refusing to quarantine large WAL (${state.walBytes} bytes) at ${dbPath}.wal during ${mode} recovery; ` +
+            'manual recovery required — run `gitnexus analyze --force <repo-path> --index-only`.');
+        throw new Error(shadowSidecarRecoveryMessage(dbPath, triggeringErr));
+    }
+};
 export async function quarantineWalForMissingShadow(dbPath, options) {
     const walPath = `${dbPath}.wal`;
     const quarantinePath = `${walPath}.missing-shadow.${Date.now()}-${Math.random()
@@ -254,6 +354,227 @@ export async function finalizeLbugSidecarsAfterClose(dbPath, options) {
             'keeping it for recovery. If this repeats, run `gitnexus analyze --force --index-only` or the sidecar repair command.');
     }
 }
+/**
+ * Corrected parking-failure warning (tri-review 4669518496 P2-3). The old
+ * text promised "the rebuild will wipe it in place instead" — false: the
+ * recovery run's pre-wipe DB open would replay the poisoned WAL and die
+ * before any wipe could happen. Mirrors {@link renameFailureMessage}'s
+ * EBUSY/EPERM framing via the shared {@link lbugLockRemediation} copy
+ * (FIX 7): the problem is environmental (file lock, AV), not data
+ * integrity — fix the lock and re-run.
+ */
+const sidecarParkRefusedWarning = (from, err) => `Warning: could not park or remove ${path.basename(from)} before the recovery rebuild ` +
+    `(${err instanceof Error ? err.message : String(err)}). Another process likely holds an ` +
+    `open handle on it — ${lbugLockRemediation()}.`;
+/**
+ * The sidecar family parked by {@link quarantineSidecarsForDirtyRecovery}
+ * and enumerated by {@link listParkedDirtyRecoverySidecars} — one shared
+ * roster so the park and clean surfaces cannot drift apart (tri-review
+ * 4669518496 P2-7).
+ */
+const DIRTY_RECOVERY_SIDECAR_SUFFIXES = ['.wal', '.shadow'];
+/**
+ * Every fixed name the dirty-recovery park can leave beside `dbPath`: the
+ * two `.dirty-recovery` destinations PLUS their `.next` probe residues
+ * (this shipping review, FIX 5 — the residue used to be invisible to every
+ * cleanup surface while the docs said "remove manually"). Single roster
+ * authority for {@link listParkedDirtyRecoverySidecars}.
+ */
+const dirtyRecoveryParkedNames = (dbPath) => DIRTY_RECOVERY_SIDECAR_SUFFIXES.flatMap((suffix) => [
+    `${dbPath}${suffix}.dirty-recovery`,
+    `${dbPath}${suffix}.dirty-recovery.next`,
+]);
+/**
+ * Move the WAL/shadow sidecars aside before a dirty-flag recovery rebuild
+ * (#2409 defect 2).
+ *
+ * When `incrementalInProgress` forces a full rebuild, the previous run
+ * died mid-writeback — its WAL can be poisoned in a way that natively
+ * kills the process on replay. The recovery run used to open the DB
+ * BEFORE the rebuild wipe (the embedding-cache preservation open), replay
+ * the poisoned WAL, and die on the spot — so recovery never happened and
+ * only a manual rename-aside of the index dir escaped the loop. The
+ * rebuild discards every pending WAL byte anyway (the DB files are wiped),
+ * so parking the sidecars first costs nothing and makes every subsequent
+ * open replay-free.
+ *
+ * Renamed when possible, so the bytes stay available for post-mortem
+ * debugging — and, like {@link quarantineWalForMissingShadow}'s quarantine
+ * files, the parked copies are surfaced and removable by
+ * `gitnexus clean --lbug-sidecars` (tri-review 4669518496 P2-7; before
+ * that, this comment claimed a "same philosophy" parity while the
+ * dirty-recovery files were invisible to every cleanup surface). Real
+ * lifecycle: the destinations are FIXED names — no timestamp, see
+ * {@link listParkedDirtyRecoverySidecars} — so each new crash overwrites
+ * the previous parked copy, capping accumulation at one file per sidecar;
+ * remove them via `clean --lbug-sidecars` or manually once their
+ * post-mortem value has passed.
+ *
+ * Escalation ladder per suffix (this shipping review, FIX 1 — replacing
+ * the drop-shape design, whose park had ZERO retry while the wipe path
+ * retried the very same lock class):
+ *
+ *   1. `rename(from, to)` retried over the shared handle-release budget
+ *      (HANDLE_RELEASE_PROBE_ATTEMPTS × linear HANDLE_RELEASE_PROBE_DELAY_MS,
+ *      lbug-config.ts) — a transient AV/handle-lag EBUSY must not cost the
+ *      run anything.
+ *   2. Structural confirm probe: a bare "does `to` exist?" check cannot
+ *      discriminate a Windows rename-onto-existing collision from a locked
+ *      source that happens to have a leftover parked copy. Renaming the
+ *      source to the collision-free `${to}.next` can — success proves the
+ *      failure was the collision, so the stale copy is replaced (newest
+ *      forensics win). The crash window between the `rm(to)` and the final
+ *      promote rename strands the bytes at `.next` — acceptable: `.next`
+ *      residues are enumerated by the dirty-recovery lister and removed by
+ *      `clean --lbug-sidecars` (FIX 5). Never pre-delete the previous
+ *      crash's parked copy on the bet that a rename will then succeed
+ *      (tri-review 4669518496 P2-3: the old rm-first shape destroyed the
+ *      prior forensics exactly when the source was locked and nothing
+ *      replaced them).
+ *   3. rm-fallback: the source itself is locked for RENAME, but Windows
+ *      lets some holders' files be unlink-marked — retry
+ *      `rm(from, {force:true})` over the same budget and require the file
+ *      verifiably GONE. Success eliminates the replay risk at the cost of
+ *      the post-mortem forensics (logged exactly so).
+ *   4. Report in `failed` with the corrected lock guidance — the caller
+ *      must abort (run-analyze throws a LbugWipeError in seconds instead
+ *      of running the whole pipeline and dying at the wipe on the same
+ *      handle).
+ *
+ * Per-suffix isolation: a `.wal` failure never skips the `.shadow`
+ * attempt.
+ *
+ * INVARIANT: after this function returns, either no original sidecar
+ * remains adjacent to the DB — every entry is in `moved` or `removed`, so
+ * every subsequent open this run performs is replay-free — or the entry is
+ * in `failed` and the caller MUST abort before any DB open.
+ *
+ * @returns `moved` — destination paths now holding the parked bytes;
+ * `removed` — source sidecars whose bytes are GONE (forensics lost, replay
+ * risk eliminated); `failed` — source sidecars still in place: a
+ * possibly-poisoned sidecar sits next to the DB and any pre-wipe open
+ * would replay it and die (there is no "wipe it in place" fallback).
+ */
+export async function quarantineSidecarsForDirtyRecovery(dbPath, log) {
+    const moved = [];
+    const removed = [];
+    const failed = [];
+    for (const suffix of DIRTY_RECOVERY_SIDECAR_SUFFIXES) {
+        const from = `${dbPath}${suffix}`;
+        const to = `${from}.dirty-recovery`;
+        try {
+            if (!(await statIfExists(from)))
+                continue;
+        }
+        catch (err) {
+            // Non-ENOENT stat failure (EPERM/EBUSY class — statIfExists swallows
+            // ENOENT itself): assume the sidecar exists and is unreachable; the
+            // caller must fail safe.
+            failed.push(from);
+            log(sidecarParkRefusedWarning(from, err));
+            continue;
+        }
+        // 1. Rename, retried over the shared handle-release budget for the
+        //    transient lock class only (EACCES/EPERM/EBUSY — an AV scan or
+        //    handle-release lag clears within it; a structural failure like
+        //    EEXIST goes straight to the confirm probe).
+        let outcome = 'rename-failed';
+        let renameErr;
+        for (let attempt = 1; attempt <= HANDLE_RELEASE_PROBE_ATTEMPTS; attempt++) {
+            try {
+                await fs.rename(from, to);
+                outcome = 'moved';
+                break;
+            }
+            catch (err) {
+                if (missing(err)) {
+                    outcome = 'raced'; // source raced away between stat and rename
+                    break;
+                }
+                renameErr = err;
+                if (!isPermissionRenameError(err) || attempt === HANDLE_RELEASE_PROBE_ATTEMPTS)
+                    break;
+                await sleep(HANDLE_RELEASE_PROBE_DELAY_MS * attempt);
+            }
+        }
+        if (outcome === 'moved') {
+            moved.push(to);
+            continue;
+        }
+        if (outcome === 'raced')
+            continue;
+        // 2. Structural confirm probe (see TSDoc step 2).
+        const probe = `${to}.next`;
+        let probeLanded = false;
+        try {
+            await fs.rename(from, probe);
+            probeLanded = true;
+        }
+        catch (probeErr) {
+            if (missing(probeErr))
+                continue; // source raced away mid-probe
+            // Source locked for rename — fall through to the rm-fallback below.
+        }
+        if (probeLanded) {
+            try {
+                // True collision — replace the stale parked copy: newest forensics win.
+                await fs.rm(to, { force: true });
+                await fs.rename(probe, to);
+                moved.push(to);
+            }
+            catch {
+                // Double failure: the stale copy is itself locked/undeletable. The
+                // interrupted run's sidecar is already out of the replay path at the
+                // probe name, so the recovery open stays safe — keep both files.
+                moved.push(probe);
+                log(`Warning: parked ${path.basename(from)} as ${path.basename(probe)} — the stale ` +
+                    `${path.basename(to)} from an earlier crash is locked and could not be replaced.`);
+            }
+            continue;
+        }
+        // 3. rm-fallback, retried over the same budget. `force: true` swallows
+        //    ENOENT, so a resolving rm proves nothing on Windows (delete-pending
+        //    keeps the name visible) — only a verifiably-absent file counts.
+        let removedOk = false;
+        for (let attempt = 1; attempt <= HANDLE_RELEASE_PROBE_ATTEMPTS; attempt++) {
+            try {
+                await fs.rm(from, { force: true });
+            }
+            catch {
+                /* verified below — the absence probe is authoritative */
+            }
+            let stillPresent = true;
+            try {
+                stillPresent = (await statIfExists(from)) !== null;
+            }
+            catch {
+                // Non-ENOENT stat failure: not verifiably gone — keep retrying.
+            }
+            if (!stillPresent) {
+                removedOk = true;
+                break;
+            }
+            if (attempt < HANDLE_RELEASE_PROBE_ATTEMPTS) {
+                await sleep(HANDLE_RELEASE_PROBE_DELAY_MS * attempt);
+            }
+        }
+        if (removedOk) {
+            removed.push(from);
+            log(`Removed ${path.basename(from)} from the interrupted run — it could not be parked ` +
+                'aside (rename locked), so its bytes were deleted instead: post-mortem forensics ' +
+                'are lost, but the replay risk is eliminated and recovery can proceed.');
+            continue;
+        }
+        // 4. Everything failed — the poisoned bytes still sit next to the DB.
+        failed.push(from);
+        log(sidecarParkRefusedWarning(from, renameErr));
+    }
+    if (moved.length > 0) {
+        log(`Parked ${moved.map((p) => path.basename(p)).join(', ')} from the interrupted run ` +
+            'so the recovery rebuild opens without replaying it.');
+    }
+    return { moved, removed, failed };
+}
 export async function listQuarantinedMissingShadowWals(dbPath) {
     const dir = path.dirname(dbPath);
     const base = path.basename(dbPath);
@@ -271,14 +592,95 @@ export async function listQuarantinedMissingShadowWals(dbPath) {
         .map((entry) => path.join(dir, entry))
         .sort();
 }
-export async function cleanQuarantinedMissingShadowWals(dbPath) {
-    const files = await listQuarantinedMissingShadowWals(dbPath);
+/**
+ * Shared unlink walker for the parked-sidecar cleaners (this shipping
+ * review, FIX 5). Per-file error policy: ENOENT is skipped silently (a
+ * list→delete race means the file is already gone — the desired state);
+ * EBUSY/EPERM/anything else lands in `failed` and the walk CONTINUES —
+ * the old per-family cleaners threw on the first locked file, crashing
+ * the whole clean mid-command after a partial deletion.
+ */
+const unlinkParkedFiles = async (files) => {
     const deleted = [];
+    const failed = [];
     for (const file of files) {
-        await fs.unlink(file);
-        deleted.push(file);
+        try {
+            await fs.unlink(file);
+            deleted.push(file);
+        }
+        catch (err) {
+            if (missing(err))
+                continue;
+            failed.push(file);
+        }
+    }
+    return { deleted, failed };
+};
+/**
+ * Delete the missing-shadow WAL quarantines for `dbPath` and return the
+ * deleted paths. Locked files are skipped, not thrown (FIX 5) — user-facing
+ * surfaces should call {@link cleanParkedLbugSidecars}, which also REPORTS
+ * the skipped files.
+ */
+export async function cleanQuarantinedMissingShadowWals(dbPath) {
+    return (await unlinkParkedFiles(await listQuarantinedMissingShadowWals(dbPath))).deleted;
+}
+/**
+ * List the `.dirty-recovery` sidecars parked beside `dbPath` by
+ * {@link quarantineSidecarsForDirtyRecovery}, so `gitnexus clean
+ * --lbug-sidecars` can surface them next to the missing-shadow quarantines
+ * (tri-review 4669518496 P2-7 — they were previously invisible to every
+ * cleanup surface). Only fixed names can exist (see
+ * {@link dirtyRecoveryParkedNames}: `<dbPath>.wal.dirty-recovery`,
+ * `<dbPath>.shadow.dirty-recovery`, and their `.next` probe residues from a
+ * double park failure — enumerated since FIX 5 of this shipping review; the
+ * docs used to say "remove manually" while no surface even listed them), so
+ * this stats them directly instead of prefix-scanning the directory the way
+ * the timestamped missing-shadow lister must.
+ *
+ * Returns existing parked files as sorted absolute paths. Branch-scoped
+ * index slots (`branches/<slug>/`) are outside `clean.ts`'s flat-path
+ * resolution — the same documented limitation as the missing-shadow pair.
+ */
+export async function listParkedDirtyRecoverySidecars(dbPath) {
+    const present = [];
+    for (const parked of dirtyRecoveryParkedNames(dbPath)) {
+        if (await statIfExists(parked))
+            present.push(parked);
     }
-    return deleted;
+    return present.sort();
+}
+/**
+ * Delete the `.dirty-recovery` parked sidecars for `dbPath` and return the
+ * deleted paths. Sibling of {@link cleanQuarantinedMissingShadowWals}; same
+ * skip-not-throw policy (FIX 5) — user-facing surfaces should call
+ * {@link cleanParkedLbugSidecars}, which also reports locked files.
+ */
+export async function cleanParkedDirtyRecoverySidecars(dbPath) {
+    return (await unlinkParkedFiles(await listParkedDirtyRecoverySidecars(dbPath))).deleted;
+}
+/**
+ * Aggregate roster of every parked/quarantined sidecar family beside
+ * `dbPath` (this shipping review, FIX 5): the timestamped missing-shadow
+ * WAL quarantines plus the fixed-name dirty-recovery parks (`.next`
+ * residues included). Single roster authority for `clean --lbug-sidecars`
+ * — the command previously concatenated the families inline in two places,
+ * which is how the `.next` residue stayed invisible.
+ */
+export async function listParkedLbugSidecars(dbPath) {
+    return [
+        ...(await listQuarantinedMissingShadowWals(dbPath)),
+        ...(await listParkedDirtyRecoverySidecars(dbPath)),
+    ];
+}
+/**
+ * Delete every file {@link listParkedLbugSidecars} enumerates. Per-file
+ * error policy via {@link unlinkParkedFiles}: ENOENT skipped silently,
+ * locked files collected into `failed` while the rest are still deleted —
+ * a locked parked file must not crash the whole clean mid-command.
+ */
+export async function cleanParkedLbugSidecars(dbPath) {
+    return unlinkParkedFiles(await listParkedLbugSidecars(dbPath));
 }
 export const _resetSidecarRecoveryWarningsForTest = () => {
     warnedKeyCounts.clear();

package/dist/core/platform/capabilities.js

@@ -1,4 +1,6 @@
+import fs from 'fs';
 import os from 'os';
+import path from 'path';
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 const packageVersion = (name) => {
@@ -6,7 +8,31 @@ const packageVersion = (name) => {
         return require(`${name}/package.json`).version;
     }
     catch {
-        return undefined;
+        // Packages whose `exports` map omits ./package.json (e.g. @ladybugdb/core)
+        // reject the direct require with ERR_PACKAGE_PATH_NOT_EXPORTED, which made
+        // doctor print "LadybugDB: unknown" on every platform (#2374). Resolve the
+        // entry point instead and walk up to the package's own package.json.
+        try {
+            let dir = path.dirname(require.resolve(name));
+            // Entry points sit at the package root or a shallow dist/ dir; a few
+            // hops always reach the package's own package.json.
+            for (let hops = 0; hops < 5; hops++) {
+                const candidate = path.join(dir, 'package.json');
+                if (fs.existsSync(candidate)) {
+                    const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+                    if (pkg.name === name)
+                        return pkg.version;
+                }
+                const parent = path.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
     }
 };
 const gitnexusVersion = () => {