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

package/dist/core/lbug/lbug-config.d.ts

@@ -62,6 +62,31 @@ export declare function isWalCorruptionError(err: unknown): boolean;
  * back to the permissive matcher.
  */
 export declare const isLbugCheckpointIoError: (err: unknown) => boolean;
+/**
+ * True when `err` looks like the LadybugDB buffer manager failing to release
+ * frame memory — the failure mode of a 4 KiB page-size assumption on a
+ * 16 KiB/64 KiB-page kernel (#1231). Deliberately does NOT match the
+ * generic "buffer pool is full" exhaustion error, which is a sizing
+ * problem, not a page-size one.
+ */
+export declare const isLbugPageSizeFrameError: (err: unknown) => boolean;
+/**
+ * True when the given `@ladybugdb/core` version contains the runtime
+ * OS-page-size detection introduced in 0.18.0 (see the matcher comment
+ * above). Unknown/unparseable versions return false so callers err on the
+ * side of showing the upgrade hint.
+ */
+export declare const isPageSizeAwareLadybug: (version: string | undefined) => boolean;
+/**
+ * OS memory page size in bytes, or `undefined` when it cannot be determined
+ * (Windows, missing getconf, sandboxed exec). Node exposes no page-size API,
+ * so this shells out to POSIX `getconf PAGE_SIZE` — same execFileSync shape
+ * as the Windows 8.3 short-path probe above, but with a tighter timeout and
+ * an explicit killSignal (see the options comment below).
+ */
+export declare const getOsPageSize: () => number | undefined;
+/** Exported only for unit tests — clears the getconf probe cache. */
+export declare const _resetOsPageSizeCacheForTest: () => void;
 type LbugModule = typeof lbug;
 export interface LbugDatabaseOptions {
     readOnly?: boolean;
@@ -108,6 +133,8 @@ export type DeleteAllErrorClass = 'benign-missing-table' | 'rethrow';
  */
 export declare const classifyDeleteAllError: (err: unknown) => DeleteAllErrorClass;
 export declare function createLbugDatabase(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): lbug.Database;
+export declare const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
+export declare const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
 /**
  * Marker symbol attached to lock errors after `openWithLockRetry` exhausts
  * its budget. `withLbugDb`'s outer query-time retry consults this so it
@@ -121,6 +148,7 @@ export declare const LBUG_OPEN_RETRY_EXHAUSTED: unique symbol;
 export declare const isOpenRetryExhausted: (err: unknown) => boolean;
 /** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
 export declare const _isTestFixturePathForTest: (dbPath: string) => boolean;
+export declare const sleep: (ms: number) => Promise<void>;
 export declare function openLbugConnection(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): Promise<LbugConnectionHandle>;
 export declare function closeLbugConnection(handle: LbugConnectionHandle): Promise<void>;
 /**

package/dist/core/lbug/lbug-config.js

@@ -337,6 +337,106 @@ export const isLbugCheckpointIoError = (err) => {
         return true;
     return LBUG_CHECKPOINT_PERMISSIVE_RE.test(msg);
 };
+// ─── Ladybug non-4K page-size frame-release matcher (#1231) ─────────────────
+//
+// LadybugDB <= 0.17.x hardcoded a 4 KiB OS-page assumption in its buffer
+// manager: evicting a frame released physical memory with
+// `madvise(frame, frameSize, MADV_DONTNEED)` on 4 KiB-aligned frame
+// addresses (verified by disassembling `VMRegion::releaseFrame` in
+// @ladybugdb/core-linux-arm64 0.17.1 — `mov w2, #0x4` = MADV_DONTNEED,
+// throw on non-zero return). On kernels with 16 KiB pages (Raspberry Pi 5
+// default 2712 kernel, Asahi Linux) or 64 KiB pages (some enterprise arm64
+// distros), madvise rejects addresses that are not multiples of the real
+// page size with EINVAL, surfacing as:
+//   "Buffer manager exception: Releasing physical memory associated with a
+//    frame failed with error code -1: Invalid argument."
+// which aborts `gitnexus analyze` mid-COPY.
+//
+// @ladybugdb/core 0.18.0 rewrote the release path with runtime OS-page-size
+// detection and discard-granule-aligned madvise (new binary strings:
+// "Failed to detect the operating system page size.", "Unsupported page
+// size combination: frame size {}, discard granule size {}, frame group
+// size {}."), so upgrading is the fix. The residual 0.18.0 guard
+// ("Unsupported page size combination") is matched here too so exotic
+// configurations receive the same actionable guidance instead of a raw
+// native message.
+const LBUG_FRAME_RELEASE_RE = /releasing physical memory associated with a frame failed/i;
+const LBUG_PAGE_COMBO_RE = /unsupported page size combination/i;
+/**
+ * True when `err` looks like the LadybugDB buffer manager failing to release
+ * frame memory — the failure mode of a 4 KiB page-size assumption on a
+ * 16 KiB/64 KiB-page kernel (#1231). Deliberately does NOT match the
+ * generic "buffer pool is full" exhaustion error, which is a sizing
+ * problem, not a page-size one.
+ */
+export const isLbugPageSizeFrameError = (err) => {
+    if (!err)
+        return false;
+    const msg = err instanceof Error ? err.message : String(err);
+    return LBUG_FRAME_RELEASE_RE.test(msg) || LBUG_PAGE_COMBO_RE.test(msg);
+};
+/**
+ * True when the given `@ladybugdb/core` version contains the runtime
+ * OS-page-size detection introduced in 0.18.0 (see the matcher comment
+ * above). Unknown/unparseable versions return false so callers err on the
+ * side of showing the upgrade hint.
+ */
+export const isPageSizeAwareLadybug = (version) => {
+    if (!version)
+        return false;
+    const m = /^(\d+)\.(\d+)/.exec(version.trim());
+    if (!m)
+        return false;
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    return major > 0 || minor >= 18;
+};
+// `undefined` = not probed yet; `null` = probed and unavailable. Cached
+// because analyze error paths and doctor may both ask, and getconf forks.
+let cachedOsPageSize;
+/**
+ * OS memory page size in bytes, or `undefined` when it cannot be determined
+ * (Windows, missing getconf, sandboxed exec). Node exposes no page-size API,
+ * so this shells out to POSIX `getconf PAGE_SIZE` — same execFileSync shape
+ * as the Windows 8.3 short-path probe above, but with a tighter timeout and
+ * an explicit killSignal (see the options comment below).
+ */
+export const getOsPageSize = () => {
+    if (cachedOsPageSize !== undefined)
+        return cachedOsPageSize ?? undefined;
+    if (process.platform === 'win32') {
+        // Windows allocation granularity is not what madvise alignment is about;
+        // the #1231 failure mode is POSIX-only.
+        cachedOsPageSize = null;
+        return undefined;
+    }
+    try {
+        // killSignal SIGKILL (first use in this repo): the default SIGTERM is
+        // catchable, so a signal-trapping child held the "5s" timeout for 9s in
+        // review reproduction — SIGKILL makes the timeout real for everything
+        // except a child stuck in uninterruptible I/O (D state). 2000ms, not
+        // 5000: doctor runs this probe on its happy path and real getconf
+        // answers in ~2ms, but keep margin for loaded Pi-class hardware — a
+        // too-tight ceiling would silently drop the very #1231 diagnostics this
+        // probe exists to provide (the catch caches the failure). (#2424 review)
+        const out = execFileSync('getconf', ['PAGE_SIZE'], {
+            encoding: 'utf-8',
+            timeout: 2000,
+            killSignal: 'SIGKILL',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const parsed = Number(out.trim());
+        cachedOsPageSize = Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+    }
+    catch {
+        cachedOsPageSize = null;
+    }
+    return cachedOsPageSize ?? undefined;
+};
+/** Exported only for unit tests — clears the getconf probe cache. */
+export const _resetOsPageSizeCacheForTest = () => {
+    cachedOsPageSize = undefined;
+};
 /**
  * Return true when the error message indicates that a LadybugDB write
  * transaction could not proceed due to lock contention — either a file
@@ -411,7 +511,10 @@ export function createLbugDatabase(lbugModule, databasePath, options = {}) {
 //   1. OPEN_LOCK_RETRY_ATTEMPTS / OPEN_LOCK_RETRY_DELAY_MS  (this file)
 //      → `new lbug.Database()` constructor lock failures
 //   2. HANDLE_RELEASE_PROBE_ATTEMPTS / HANDLE_RELEASE_PROBE_DELAY_MS  (this file)
-//      → post-close fs.open probe to absorb Windows handle-release lag
+//      → post-close fs.open probe to absorb Windows handle-release lag; also
+//        the shared budget for wipeLbugDbFiles' ENOENT-verified removal
+//        (lbug-adapter.ts) and the dirty-recovery sidecar park's
+//        rename/rm retries (sidecar-recovery.ts) — same lock class
 //   3. DB_LOCK_RETRY_ATTEMPTS / DB_LOCK_RETRY_DELAY_MS  (lbug-adapter.ts withLbugDb)
 //      → query-time busy/lock retry around already-open connections
 //
@@ -429,8 +532,13 @@ export function createLbugDatabase(lbugModule, databasePath, options = {}) {
 // matches on is unchanged.)
 const OPEN_LOCK_RETRY_ATTEMPTS = 5;
 const OPEN_LOCK_RETRY_DELAY_MS = 100;
-const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
-const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
+// Exported (this shipping review, FIX 1/2): the dirty-recovery sidecar park
+// (sidecar-recovery.ts) and the ENOENT-verified wipe (lbug-adapter.ts
+// wipeLbugDbFiles) retry the SAME Windows handle-release/AV lock class, and
+// their previous private mirror constants were documentation-coupled copies
+// that could drift from this tuning-knob registry silently.
+export const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
+export const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
 const HANDLE_RELEASE_LOCK_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
 /**
  * Test-fixture directory prefixes recognized by `isTestFixturePath`.
@@ -492,7 +600,9 @@ const isTestFixturePath = (dbPath) => {
 };
 /** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
 export const _isTestFixturePathForTest = isTestFixturePath;
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Exported alongside HANDLE_RELEASE_PROBE_* (this shipping review, FIX 1/2)
+// so the consumers of the shared retry budget do not each grow a private copy.
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Attempt to remove stale `.wal` / `.lock` sidecars that a previous aborted
  * test run may have left behind. Best-effort: ENOENT is normal, anything

package/dist/core/lbug/native-check.d.ts

@@ -4,3 +4,25 @@ export interface NativeCheckResult {
     message?: string;
 }
 export declare function checkLbugNative(overridePkgDir?: string): NativeCheckResult;
+export interface FtsProbeResult {
+    loaded: boolean;
+    /** Collapsed LadybugDB error when `loaded` is false. */
+    reason?: string;
+}
+/**
+ * Live-probe `LOAD EXTENSION fts` on a throwaway in-memory database.
+ *
+ * `doctor` used to print the static platform capability, which contradicted
+ * analyze whenever the extension file was missing or unloadable (#2374).
+ * LOAD never touches the network, so the probe is safe offline, and it
+ * surfaces LadybugDB's real error — which distinguishes a missing extension
+ * file from a present-but-broken one (wrong platform, truncated download).
+ * Dynamic import so doctor still runs when the native module itself is broken.
+ *
+ * Bounded by `timeoutMs`: an unresponsive extension file (e.g. on a hung
+ * network home dir) must never freeze `doctor` — the tool the degradation
+ * warnings send users to. `Promise.race` lets doctor report and move on; it
+ * cannot cancel an in-flight native call, so a future thread-blocking case
+ * would need an out-of-process probe.
+ */
+export declare function probeFtsExtensionLoad(timeoutMs?: number): Promise<FtsProbeResult>;

package/dist/core/lbug/native-check.js

@@ -81,3 +81,69 @@ export function checkLbugNative(overridePkgDir) {
     }
     return { ok: true, binaryPath };
 }
+const DEFAULT_FTS_PROBE_TIMEOUT_MS = 10_000;
+/** Close each result, swallowing close-time errors so a successful LOAD is not
+ *  misreported as a failure (native-check keeps no static lbug dependency, so it
+ *  cannot reuse the adapter's closeQueryResults — that would eagerly load the
+ *  module and defeat the dynamic import below). */
+const closeProbeResults = (result) => {
+    for (const r of Array.isArray(result) ? result : [result]) {
+        try {
+            r?.close?.();
+        }
+        catch {
+            // ignore — a close failure must not flip a successful LOAD to failed
+        }
+    }
+};
+/**
+ * Live-probe `LOAD EXTENSION fts` on a throwaway in-memory database.
+ *
+ * `doctor` used to print the static platform capability, which contradicted
+ * analyze whenever the extension file was missing or unloadable (#2374).
+ * LOAD never touches the network, so the probe is safe offline, and it
+ * surfaces LadybugDB's real error — which distinguishes a missing extension
+ * file from a present-but-broken one (wrong platform, truncated download).
+ * Dynamic import so doctor still runs when the native module itself is broken.
+ *
+ * Bounded by `timeoutMs`: an unresponsive extension file (e.g. on a hung
+ * network home dir) must never freeze `doctor` — the tool the degradation
+ * warnings send users to. `Promise.race` lets doctor report and move on; it
+ * cannot cancel an in-flight native call, so a future thread-blocking case
+ * would need an out-of-process probe.
+ */
+export async function probeFtsExtensionLoad(timeoutMs = DEFAULT_FTS_PROBE_TIMEOUT_MS) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({
+            loaded: false,
+            reason: 'probe timed out — extension file or filesystem unresponsive',
+        }), timeoutMs);
+    });
+    const probe = (async () => {
+        try {
+            const { default: lbug } = await import('@ladybugdb/core');
+            const db = new lbug.Database(':memory:');
+            // Nested finallys so `db` is closed even if the Connection ctor throws.
+            try {
+                const conn = new lbug.Connection(db);
+                try {
+                    const result = await conn.query('LOAD EXTENSION fts');
+                    closeProbeResults(result);
+                    return { loaded: true };
+                }
+                finally {
+                    await conn.close().catch(() => { });
+                }
+            }
+            finally {
+                await db.close().catch(() => { });
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { loaded: false, reason: message.replace(/\s+/g, ' ').trim() };
+        }
+    })();
+    return await Promise.race([probe, timeout]).finally(() => clearTimeout(timer));
+}

package/dist/core/lbug/pool-adapter.js

@@ -19,7 +19,7 @@ import lbug from '@ladybugdb/core';
 import { isReadOnlyDbError, loadFTSExtension } from './lbug-adapter.js';
 import { closeQueryResults } from './query-result-utils.js';
 import { createLbugDatabase, isWalCorruptionError, toNativeSafePath, WAL_RECOVERY_SUGGESTION, } from './lbug-config.js';
-import { isMissingFsError, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, statIfExists, } from './sidecar-recovery.js';
+import { guardWalQuarantine, isMissingFsError, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, statIfExists, } from './sidecar-recovery.js';
 const pool = new Map();
 const poolCloseListeners = new Set();
 /**
@@ -349,6 +349,12 @@ const poolSidecarLogger = {
  * See plan: docs/plans/2026-05-21-001-fix-pr-1747-quarantine-enoent-and-large-wal-plan.md (U2)
  */
 async function tryQuarantineForMissingShadow(dbPath, opts) {
+    // Refuse (throw) before renaming a live WAL when the shadow is present on
+    // disk or the orphan WAL is too large — parity with the serve path's
+    // refuseLargeWalQuarantine (issue #2382 review, Finding B). Kept OUTSIDE the
+    // try so the actionable recovery message propagates to the MCP caller rather
+    // than being re-wrapped as a rename failure.
+    await guardWalQuarantine(dbPath, opts.reason, opts.err, poolSidecarLogger);
     try {
         const quarantinePath = await quarantineWalForMissingShadow(dbPath, {
             logger: poolSidecarLogger,
@@ -396,6 +402,7 @@ async function replayShadowPagesWithWritableOpen(dbPath) {
         if (isMissingShadowSidecarError(err)) {
             await tryQuarantineForMissingShadow(dbPath, {
                 reason: 'pool writable replay recovery',
+                err,
             });
             return;
         }
@@ -429,6 +436,7 @@ async function openReadOnlyDatabase(dbPath) {
                 db = undefined;
                 await tryQuarantineForMissingShadow(dbPath, {
                     reason: 'pool read-only recovery',
+                    err,
                 });
                 await preflightLbugSidecars(dbPath, {
                     mode: 'read-only',
@@ -559,6 +567,7 @@ async function doInitLbug(repoId, dbPath) {
                     }
                 }
                 if (lastError.message.startsWith('LadybugDB checkpoint sidecar is missing') ||
+                    lastError.message.startsWith('LadybugDB checkpoint sidecar is present but unreachable') ||
                     lastError.message.startsWith('GitNexus could not move the LadybugDB WAL sidecar') ||
                     isMissingShadowSidecarError(lastError)) {
                     throw lastError;

package/dist/core/lbug/sidecar-recovery.d.ts

@@ -32,7 +32,31 @@ export declare const statIfExists: (filePath: string) => Promise<{
 export declare const isMissingShadowSidecarError: (err: unknown) => boolean;
 export declare const isReadOnlyShadowReplayError: (err: unknown) => boolean;
 export declare const shadowSidecarRecoveryMessage: (dbPath: string, err: unknown) => string;
+/**
+ * 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 declare const presentShadowUnreachableMessage: (dbPath: string, err: unknown) => string;
 export declare const isPermissionRenameError: (err: unknown) => boolean;
+/**
+ * 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 declare const lbugLockRemediation: (rerun?: string) => string;
 /**
  * Classify a failure surfaced by quarantine rename into an actionable user-facing
  * message.
@@ -50,6 +74,28 @@ export declare const isPermissionRenameError: (err: unknown) => boolean;
  */
 export declare const renameFailureMessage: (dbPath: string, err: unknown) => string;
 export declare function inspectLbugSidecars(dbPath: string): Promise<LbugSidecarState>;
+/**
+ * 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 declare const guardWalQuarantine: (dbPath: string, mode: string, triggeringErr: unknown, logger: SidecarRecoveryLogger) => Promise<void>;
 export declare function quarantineWalForMissingShadow(dbPath: string, options: {
     logger: SidecarRecoveryLogger;
     level?: 'debug' | 'info' | 'warn';
@@ -63,6 +109,132 @@ export declare function preflightLbugSidecars(dbPath: string, options: {
 export declare function finalizeLbugSidecarsAfterClose(dbPath: string, options: {
     logger: SidecarRecoveryLogger;
 }): Promise<void>;
+/**
+ * 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 declare function quarantineSidecarsForDirtyRecovery(dbPath: string, log: (message: string) => void): Promise<{
+    moved: string[];
+    removed: string[];
+    failed: string[];
+}>;
 export declare function listQuarantinedMissingShadowWals(dbPath: string): Promise<string[]>;
+/**
+ * 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 declare function cleanQuarantinedMissingShadowWals(dbPath: string): Promise<string[]>;
+/**
+ * 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 declare function listParkedDirtyRecoverySidecars(dbPath: string): Promise<string[]>;
+/**
+ * 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 declare function cleanParkedDirtyRecoverySidecars(dbPath: string): Promise<string[]>;
+/**
+ * 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 declare function listParkedLbugSidecars(dbPath: string): Promise<string[]>;
+/**
+ * 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 declare function cleanParkedLbugSidecars(dbPath: string): Promise<{
+    deleted: string[];
+    failed: string[];
+}>;
 export declare const _resetSidecarRecoveryWarningsForTest: () => void;