gitnexus 1.6.9 → 1.6.10-rc.10

package/dist/core/lbug/extension-loader.d.ts

@@ -1,3 +1,4 @@
+import { type ExtensionLoadDiagnosis } from './extension-load-error.js';
 /**
  * Lifecycle policy for an optional DuckDB extension.
  *
@@ -20,6 +21,12 @@ export interface ExtensionCapability {
     loaded: boolean;
     /** Human-readable reason when `loaded` is false. */
     reason?: string;
+    /**
+     * Classified diagnosis of `reason`, computed ONCE at mark-unavailable time so
+     * per-request surfaces (ftsDegradedWarning on /api/search + MCP query) read the
+     * cached remedy instead of re-inspecting the extension file on every call (#2383 F3).
+     */
+    diagnosis?: ExtensionLoadDiagnosis;
 }
 /** Per-call overrides applied on top of `ExtensionManager` defaults. */
 export interface ExtensionEnsureOptions {
@@ -29,7 +36,7 @@ export interface ExtensionEnsureOptions {
 export interface ExtensionManagerOptions {
     policy?: ExtensionInstallPolicy;
     installTimeoutMs?: number;
-    installExtension?: (extensionName: string, timeoutMs: number) => Promise<ExtensionInstallResult>;
+    installExtension?: (extensionName: string, timeoutMs: number, loadError?: string) => Promise<ExtensionInstallResult>;
     warn?: (message: string) => void;
 }
 export declare const getExtensionInstallPolicy: () => ExtensionInstallPolicy;
@@ -58,7 +65,7 @@ export declare const getExtensionInstallChildProcessArgs: (extensionName: string
  * If the child exceeds `timeoutMs` the parent kills it with SIGKILL and
  * resolves with `timedOut: true`.
  */
-export declare const installDuckDbExtensionOutOfProcess: (extensionName: string, timeoutMs?: number) => Promise<ExtensionInstallResult>;
+export declare const installDuckDbExtensionOutOfProcess: (extensionName: string, timeoutMs?: number, loadError?: string) => Promise<ExtensionInstallResult>;
 /**
  * Centralized lifecycle manager for optional LadybugDB extensions.
  *
@@ -90,6 +97,14 @@ export declare class ExtensionManager {
      * paths are expected to degrade gracefully.
      */
     ensure(query: (sql: string) => Promise<unknown>, name: string, label: string, opts?: ExtensionEnsureOptions): Promise<boolean>;
+    /**
+     * Attempt `LOAD EXTENSION <name>`; returns `null` on success and the
+     * collapsed error message on failure. The message is the load-side ground
+     * truth — LadybugDB distinguishes a missing extension file from a present
+     * but unloadable one (wrong platform, truncated download, version mismatch),
+     * and discarding it left users staring at "not pre-installed" when the file
+     * existed all along (#2374).
+     */
     private tryLoad;
     private markLoaded;
     private markUnavailable;

package/dist/core/lbug/extension-loader.js

@@ -1,12 +1,15 @@
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'node:url';
 import { LBUG_MAX_DB_SIZE } from './lbug-config.js';
+import { diagnoseExtensionLoad } from './extension-load-error.js';
 import { logger } from '../logger.js';
 const DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS = 15_000;
 const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
 const alreadyAvailable = (message) => message.includes('already loaded') ||
     message.includes('already installed') ||
     message.includes('already exists');
+/** LadybugDB errors are multi-line; collapse for single-line warn/reason strings. */
+const oneLine = (value) => value.replace(/\s+/g, ' ').trim();
 const resolvePolicyFromEnv = () => {
     const raw = process.env.GITNEXUS_LBUG_EXTENSION_INSTALL;
     if (raw === 'load-only' || raw === 'never' || raw === 'auto')
@@ -51,7 +54,7 @@ export const getExtensionInstallChildProcessArgs = (extensionName, maxDbSize = L
  * If the child exceeds `timeoutMs` the parent kills it with SIGKILL and
  * resolves with `timedOut: true`.
  */
-export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutMs = getExtensionInstallTimeoutMs()) => {
+export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutMs = getExtensionInstallTimeoutMs(), loadError) => {
     if (!EXTENSION_NAME_PATTERN.test(extensionName)) {
         throw new Error(`Invalid DuckDB extension name: ${extensionName}`);
     }
@@ -60,6 +63,9 @@ export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutM
             env: {
                 ...process.env,
                 GITNEXUS_LBUG_EXTENSION_NAME: extensionName,
+                // The child picks INSTALL vs FORCE INSTALL from this LOAD error so it
+                // only re-downloads when the on-disk extension file is actually broken.
+                ...(loadError ? { GITNEXUS_LBUG_EXTENSION_LOAD_ERROR: loadError } : {}),
             },
             stdio: ['ignore', 'ignore', 'pipe'],
             windowsHide: true,
@@ -78,7 +84,7 @@ export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutM
             resolve({
                 success: false,
                 timedOut: true,
-                message: `INSTALL ${extensionName} timed out after ${timeoutMs}ms`,
+                message: `extension install for ${extensionName} timed out after ${timeoutMs}ms`,
             });
         }, timeoutMs);
         child.on('error', (err) => {
@@ -97,8 +103,8 @@ export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutM
                 success: code === 0,
                 timedOut: false,
                 message: code === 0
-                    ? `INSTALL ${extensionName} completed`
-                    : `INSTALL ${extensionName} failed with ${signal ?? `exit code ${code}`}${stderr ? `: ${stderr.trim()}` : ''}`,
+                    ? `extension install for ${extensionName} completed`
+                    : `extension install for ${extensionName} failed with ${signal ?? `exit code ${code}`}${stderr ? `: ${stderr.trim()}` : ''}`,
             });
         });
     });
@@ -152,46 +158,65 @@ export class ExtensionManager {
             this.markUnavailable(name, label, 'extension install policy is "never"', warn);
             return false;
         }
-        if (await this.tryLoad(query, name)) {
+        const loadError = await this.tryLoad(query, name);
+        if (loadError === null) {
             this.markLoaded(name);
             return true;
         }
         if (policy === 'load-only') {
-            this.markUnavailable(name, label, 'load-only policy: extension not pre-installed', warn);
+            this.markUnavailable(name, label, `load-only policy (no install attempted); LOAD ${name} failed: ${loadError}`, warn);
             return false;
         }
         let install = this.installAttempted.get(name);
         if (!install) {
             const installFn = this.options.installExtension ?? installDuckDbExtensionOutOfProcess;
-            install = await installFn(name, timeoutMs);
+            // Hand the child the LOAD error so it re-downloads (FORCE) only when the
+            // present extension file is provably broken, not on every LOAD failure.
+            install = await installFn(name, timeoutMs, loadError);
             this.installAttempted.set(name, install);
         }
         if (!install.success) {
-            this.markUnavailable(name, label, install.message, warn);
+            this.markUnavailable(name, label, `${install.message}; LOAD ${name} had failed: ${loadError}`, warn);
             return false;
         }
-        if (await this.tryLoad(query, name)) {
+        const retryError = await this.tryLoad(query, name);
+        if (retryError === null) {
             this.markLoaded(name);
             return true;
         }
-        this.markUnavailable(name, label, `LOAD ${name} failed after successful INSTALL`, warn);
+        this.markUnavailable(name, label, `LOAD ${name} failed after successful INSTALL: ${retryError}`, warn);
         return false;
     }
+    /**
+     * Attempt `LOAD EXTENSION <name>`; returns `null` on success and the
+     * collapsed error message on failure. The message is the load-side ground
+     * truth — LadybugDB distinguishes a missing extension file from a present
+     * but unloadable one (wrong platform, truncated download, version mismatch),
+     * and discarding it left users staring at "not pre-installed" when the file
+     * existed all along (#2374).
+     */
     async tryLoad(query, name) {
         try {
             await query(`LOAD EXTENSION ${name}`);
-            return true;
+            return null;
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            return alreadyAvailable(msg);
+            return alreadyAvailable(msg) ? null : oneLine(msg);
         }
     }
     markLoaded(name) {
         this.capabilities.set(name, { name, loaded: true });
     }
     markUnavailable(name, label, reason, warn) {
-        this.capabilities.set(name, { name, loaded: false, reason });
+        // Classify once here (the single load-failure sink, run per Database not per
+        // request) so the hot per-request warning path does no file I/O (#2383 F3).
+        this.capabilities.set(name, {
+            name,
+            loaded: false,
+            reason,
+            diagnosis: diagnoseExtensionLoad(reason),
+        });
         const key = `${name}:${reason}`;
         if (this.warnedKeys.has(key))
             return;

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

@@ -13,7 +13,7 @@ import { streamAllCSVsToDisk } from './csv-generator.js';
 import { getNodeLabel as deriveNodeLabel } from './rel-pair-routing.js';
 import { extensionManager } from './extension-loader.js';
 import { classifyDeleteAllError, closeLbugConnection, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
-import { finalizeLbugSidecarsAfterClose, inspectLbugSidecars, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, } from './sidecar-recovery.js';
+import { finalizeLbugSidecarsAfterClose, guardWalQuarantine, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, } from './sidecar-recovery.js';
 import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 /**
@@ -409,23 +409,14 @@ const queryAndDrain = async (targetConn, cypher) => {
 };
 const READ_ONLY_SHADOW_REPLAY_PROBE = 'MATCH (n) RETURN n LIMIT 1';
 /**
- * Reject the quarantine path when the orphan WAL is too large to safely
- * discard (>TINY_ORPHAN_WAL_BYTES). Mirrors the preflight policy at
- * sidecar-recovery.ts:153-160 ("warn, do not quarantine"). Symmetric across
- * read-only and writable recovery paths (PR #1747 review D2).
- *
- * Throws shadowSidecarRecoveryMessage immediately when the WAL is large,
- * preserving the uncheckpointed pages for explicit operator recovery.
- * Returns silently when the WAL is absent, tiny, or in any other state
- * where the existing recovery path is safe to proceed.
+ * Serve-side entry to the shared WAL-quarantine safety gate. Refuses (throws)
+ * when the `.shadow` is present on disk or the orphan WAL is too large to
+ * safely discard; returns silently otherwise. The policy itself lives in
+ * `guardWalQuarantine` (sidecar-recovery.ts) so serve and the MCP pool share
+ * one source of truth (PR #1747 review D2; issue #2382 review, Finding B).
  */
 const refuseLargeWalQuarantine = async (dbPath, mode, triggeringErr) => {
-    const state = await inspectLbugSidecars(dbPath);
-    if (state.kind === 'orphan-wal') {
-        logger.warn(`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));
-    }
+    await guardWalQuarantine(dbPath, mode, triggeringErr, logger);
 };
 const reopenReadOnlyAfterMissingShadow = async (dbPath, err) => {
     await refuseLargeWalQuarantine(dbPath, 'read-only', err);

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,6 +32,16 @@ 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;
 /**
  * Classify a failure surfaced by quarantine rename into an actionable user-facing
@@ -50,6 +60,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';

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

@@ -87,16 +87,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,6 +145,24 @@ 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;
@@ -165,6 +214,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()

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 = () => {

package/dist/core/run-analyze.js

@@ -16,7 +16,8 @@ import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, deleteAllInjects, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
 import { createSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSIndexes, } from './search/fts-indexes.js';
 import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSearchFTSCjkSegmentation, } from './search/cjk-segmentation.js';
-import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
+import { getExtensionCapabilities, resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
+import { diagnoseExtensionLoad } from './lbug/extension-load-error.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, adoptFlatBranchLabel, isReadOnlyFilesystemError, isRepoRegistered, cleanupOldKuzuFiles, reconcileMetadataFiles, isMissingFilesystemError, INDEX_METADATA_FILE, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { DEFAULT_PDG_MAX_FUNCTION_LINES } from './ingestion/cfg/collect.js';
@@ -41,7 +42,11 @@ import { STALE_HASH_SENTINEL } from './lbug/schema.js';
  * a full analyze. Kept as a named constant so the env-var/command guidance
  * stays in one place (mirrors the VECTOR message in embedding-pipeline.ts).
  */
-const FTS_UNAVAILABLE_MESSAGE = 'FTS extension unavailable; skipping search-index creation. ' +
+// Class-neutral lead, reused for the missing-dependency degrade path (#2383 F2):
+// its remedy already explains that reinstalling will NOT help, so appending the
+// generic "install with network access" tail below would contradict it.
+const FTS_UNAVAILABLE_LEAD = 'FTS extension unavailable; skipping search-index creation.';
+const FTS_UNAVAILABLE_MESSAGE = `${FTS_UNAVAILABLE_LEAD} ` +
     'Full-text/BM25 search will be disabled until the LadybugDB FTS extension is ' +
     'installed once with network access (GITNEXUS_LBUG_EXTENSION_INSTALL=auto) or ' +
     'pre-installed for offline use. Run `gitnexus doctor` for details.';
@@ -365,9 +370,23 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 policy: resolveAnalyzeInstallPolicy(),
             });
             if (!repairFtsAvailable) {
-                throw new Error('Cannot repair FTS indexes: the LadybugDB FTS extension is unavailable ' +
-                    '(not pre-installed and could not be installed on this machine). ' +
-                    'Run `gitnexus doctor` to install it, then retry `--repair-fts`.');
+                // Surface the load-side reason (#2374): "not pre-installed" was wrong
+                // and doctor never installed anything, so the old message trapped
+                // users in a query → repair-fts → doctor loop with no way out.
+                const rawFtsReason = getExtensionCapabilities().find((c) => c.name === 'fts')?.reason;
+                const ftsReason = rawFtsReason?.replace(/\.$/, '');
+                // A missing runtime dependency (Windows error 126, #2374) is not healed
+                // by re-installing — the file is already present. Route that class to the
+                // classified remedy (install VC++ redist / OpenSSL) instead of the old
+                // "retry the network install" text that trapped the user in a loop.
+                const { kind, remedy } = diagnoseExtensionLoad(rawFtsReason);
+                const remedyTail = kind === 'missing_dependency'
+                    ? ` ${remedy}`
+                    : '. Retry with network access and GITNEXUS_LBUG_EXTENSION_INSTALL=auto to install it, ' +
+                        'or pre-install the extension file; run `gitnexus doctor` for live FTS status.';
+                throw new Error('Cannot repair FTS indexes: the LadybugDB FTS extension failed to load' +
+                    (ftsReason ? ` — ${ftsReason}` : '') +
+                    remedyTail);
             }
             progress('fts', 85, 'Repairing search indexes...');
             await createSearchFTSIndexes({
@@ -956,7 +975,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             progress('fts', 90, 'Search indexes ready');
         }
         else {
-            log(FTS_UNAVAILABLE_MESSAGE);
+            // For a missing runtime dependency (#2374) the file is present, so the
+            // generic "install it with network access" tail in FTS_UNAVAILABLE_MESSAGE
+            // contradicts the remedy's own "reinstalling will NOT help" (#2383 F2). Lead
+            // with the class-neutral sentence and append only the classified remedy.
+            const ftsReason = getExtensionCapabilities().find((c) => c.name === 'fts')?.reason;
+            const { kind, remedy } = diagnoseExtensionLoad(ftsReason);
+            log(kind === 'missing_dependency'
+                ? `${FTS_UNAVAILABLE_LEAD} ${remedy}`
+                : FTS_UNAVAILABLE_MESSAGE);
             progress('fts', 90, 'Search indexes skipped (FTS unavailable)');
         }
         // ── Phase 3.5: Re-insert cached embeddings ────────────────────────