gitnexus 1.6.10-rc.5 → 1.6.10-rc.7

package/dist/cli/analyze.js

@@ -27,7 +27,7 @@ import { cliError } from './cli-message.js';
 import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
-import { isHttpMode, safeUrl } from '../core/embeddings/http-client.js';
+import { isHttpEmbeddingDimsError, isHttpEmbeddingError, isHttpMode, safeUrl, } from '../core/embeddings/http-client.js';
 import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
 import { ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS, getEmbeddingInstallTimeoutMs, getEmbeddingRuntimeDir, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { warnIfNpm11NpxRisk } from './resolve-invocation.js';
@@ -1262,10 +1262,54 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // Malformed GITNEXUS_EMBEDDING_DIMS env var (#2385). readConfig() throws a
+        // plain Error (a config mistake, not an endpoint failure), surfacing here from
+        // httpEmbed()->readConfig() inside the analysis run. Show a clean config
+        // message rather than a raw stack dump. The --embedding-dims CLI flag is
+        // validated up front (EMBEDDING_DIMS_ERROR); this covers the env-var path.
+        // Checked before the endpoint/HF branches: it is a plain Error, so
+        // isHttpEmbeddingError() is false and the HF network heuristic must not claim it.
+        if (isHttpEmbeddingDimsError(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'embedding-dims-invalid',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Custom HTTP embedding endpoint failure (#2385). When a `--embedding-base-url`
+        // is configured, HTTP mode never downloads a model — so a failure talking to
+        // that endpoint must NOT show the huggingface-download guidance. Keyed on the
+        // error *type* (HttpEmbeddingError), not its message text, so it stays correct
+        // regardless of locale or wording. Checked before the HF branch, whose network
+        // heuristic (`fetch failed` / `ECONNREFUSED`) would otherwise also match a
+        // wrapped endpoint-connection error. The header is deliberately neutral: this
+        // type covers both never-reached failures (connection/timeout/DNS) and
+        // reached-but-failed ones (4xx/5xx, dimension/shape mismatch), so it must not
+        // assert "unreachable". The thrown `msg` carries the specific reason (and the
+        // masked URL where one applies), so it is surfaced verbatim.
+        if (isHttpEmbeddingError(err)) {
+            cliError(`  The custom embedding endpoint request failed.\n` +
+                `  ${msg.replace(/\n/g, '\n  ')}\n` +
+                `  Suggestions:\n` +
+                `    1. Verify the endpoint URL is reachable and running ` +
+                `(--embedding-base-url / GITNEXUS_EMBEDDING_URL: host, port, /v1 path).\n` +
+                `    2. Confirm the model name and embedding dimensions match what the endpoint serves.\n` +
+                `    3. Re-run without --embeddings to index without vectors.\n`, { recoveryHint: 'http-embedding-endpoint-error' });
+            process.exitCode = 1;
+            return;
+        }
+        // isHttpMode() is a pure presence probe (URL+MODEL) that never throws — a
+        // malformed GITNEXUS_EMBEDDING_DIMS is handled by the dims branch above — so
+        // no defensive try/catch is needed here (#2385).
+        const inHttpMode = isHttpMode();
         // HF download failure — show clean guidance without the raw stack trace.
         // Checked before writeFatalToStderr so the user sees one focused message
         // rather than a stack-trace dump followed by a second remediation block.
-        if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
+        // Gated on !inHttpMode: with a custom endpoint configured no model download
+        // is ever attempted, so a network error there is the endpoint's, handled by
+        // the HttpEmbeddingError branch above — never HF's (#2385).
+        if ((isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) &&
+            !inHttpMode) {
             cliError(`  The embedding model could not be downloaded.\n` +
                 `  huggingface.co may be unreachable from your network\n` +
                 `  (e.g. behind a corporate proxy or a regional firewall).\n` +

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/doctor.js

@@ -5,6 +5,7 @@ import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage,
 import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
 import { checkLbugNative, probeFtsExtensionLoad } from '../core/lbug/native-check.js';
+import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
 function isCombiningMark(codePoint) {
@@ -116,6 +117,15 @@ export const doctorCommand = async () => {
     console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${ftsProbe.loaded ? 'available' : 'unavailable'}`);
     if (!ftsProbe.loaded && ftsProbe.reason) {
         console.log(`  ${padDisplayEnd('', 18)}${ftsProbe.reason}`);
+        // Add an actionable remedy for recognized failure classes (#2374). The
+        // Windows missing-dependency case is the point of this: the raw error 126
+        // ("specified module could not be found") is opaque, so name the fix (VC++
+        // redist, then OpenSSL) instead of leaving the user to reinstall in vain.
+        // `unknown`'s remedy is "run doctor", which would be circular here.
+        const { kind, remedy } = diagnoseExtensionLoad(ftsProbe.reason);
+        if (kind !== 'unknown') {
+            console.log(`  ${padDisplayEnd('', 18)}${remedy}`);
+        }
     }
     console.log(`  ${label('doctor.labels.vectorIndex', 18)}${capabilities.vector}`);
     console.log(`  ${label('doctor.labels.semanticMode', 18)}${capabilities.semanticMode}`);

package/dist/core/embeddings/http-client.d.ts

@@ -11,7 +11,13 @@
  * via `AbortSignal.timeout` on the underlying fetch.
  */
 /**
- * Check whether HTTP embedding mode is active (env vars are set).
+ * Whether HTTP embedding mode is active — i.e. both `GITNEXUS_EMBEDDING_URL` and
+ * `GITNEXUS_EMBEDDING_MODEL` are set. A pure presence probe: it deliberately does
+ * NOT call {@link readConfig}, so it never throws on a malformed
+ * `GITNEXUS_EMBEDDING_DIMS`. This lets its ~13 call sites (analyze, doctor,
+ * run-analyze, embedder, mcp) probe the mode without a defensive try/catch; the
+ * DIMS value is validated where it is actually used (`readConfig` in
+ * `httpEmbed`/`httpEmbedQuery`), surfacing a recognizable config error. See #2385.
  */
 export declare const isHttpMode: () => boolean;
 /**
@@ -26,6 +32,27 @@ export declare const getHttpDimensions: () => number | undefined;
  * custom-endpoint confirmation can mask the same way.
  */
 export declare const safeUrl: (url: string) => string;
+/**
+ * Error thrown by this module's HTTP embedding path (`httpEmbedBatch` /
+ * `httpEmbed` / `httpEmbedQuery`) for any endpoint failure — a
+ * connection/timeout/DNS error, an open circuit, a non-OK status, an
+ * unparseable or wrong-shape response body, an empty response, or a dimension
+ * mismatch.
+ *
+ * Carrying a distinct type (rather than a plain `Error`) lets the CLI tell a
+ * *custom endpoint* failure apart from a HuggingFace *model download* failure
+ * without matching message text: the two share the same underlying network
+ * substrings (`fetch failed`, `ECONNREFUSED`, …), which is exactly why
+ * `isNetworkFetchError` in `hf-env.ts` cannot tell them apart. Keying on the
+ * type instead of the message is also locale-proof and survives message
+ * rewording. The human-readable `.message` (built with `safeUrl` and the
+ * underlying reason) is what the CLI surfaces to the user. See #2385.
+ */
+export declare class HttpEmbeddingError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Embed texts via the HTTP backend, splitting into batches.
  * Reads config from env vars on every call.

package/dist/core/embeddings/http-client.js

@@ -17,10 +17,26 @@ const HTTP_RETRY_BACKOFF_MS = 1_000;
 const HTTP_BATCH_SIZE = 64;
 const DEFAULT_DIMS = 384;
 const HTTP_BREAKER_KEY = 'embeddings-http';
+/**
+ * Stable lead of the {@link readConfig} malformed-`GITNEXUS_EMBEDDING_DIMS`
+ * error. `readConfig` throws a plain `Error` (not an {@link HttpEmbeddingError})
+ * because this is a *config* mistake, not an endpoint failure — so the CLI
+ * recognizes it by this lead ({@link isHttpEmbeddingDimsError}) and prints a
+ * clean config message instead of a raw stack dump. See #2385.
+ */
+const EMBEDDING_DIMS_ENV_ERROR_LEAD = 'GITNEXUS_EMBEDDING_DIMS must be a positive integer';
+/**
+ * @internal Exported for the CLI analyze error handler. True when `message` is
+ * the {@link readConfig} malformed-DIMS config error (a plain `Error`).
+ */
+export const isHttpEmbeddingDimsError = (message) => message.includes(EMBEDDING_DIMS_ENV_ERROR_LEAD);
 /**
  * Build config from the current process.env snapshot.
  * Returns null when GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL are unset.
  * Not cached — env vars are read fresh so late configuration takes effect.
+ * Validates GITNEXUS_EMBEDDING_DIMS and throws on a malformed value; callers
+ * that only need to know whether HTTP mode is *configured* must use
+ * {@link isHttpMode} (a presence probe that never throws), not this.
  */
 const readConfig = () => {
     const baseUrl = process.env.GITNEXUS_EMBEDDING_URL;
@@ -31,11 +47,11 @@ const readConfig = () => {
     let dimensions;
     if (rawDims !== undefined) {
         if (!/^\d+$/.test(rawDims)) {
-            throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
+            throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got "${rawDims}"`);
         }
         const parsed = parseInt(rawDims, 10);
         if (parsed <= 0) {
-            throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
+            throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got "${rawDims}"`);
         }
         dimensions = parsed;
     }
@@ -47,9 +63,15 @@ const readConfig = () => {
     };
 };
 /**
- * Check whether HTTP embedding mode is active (env vars are set).
+ * Whether HTTP embedding mode is active — i.e. both `GITNEXUS_EMBEDDING_URL` and
+ * `GITNEXUS_EMBEDDING_MODEL` are set. A pure presence probe: it deliberately does
+ * NOT call {@link readConfig}, so it never throws on a malformed
+ * `GITNEXUS_EMBEDDING_DIMS`. This lets its ~13 call sites (analyze, doctor,
+ * run-analyze, embedder, mcp) probe the mode without a defensive try/catch; the
+ * DIMS value is validated where it is actually used (`readConfig` in
+ * `httpEmbed`/`httpEmbedQuery`), surfacing a recognizable config error. See #2385.
  */
-export const isHttpMode = () => readConfig() !== null;
+export const isHttpMode = () => Boolean(process.env.GITNEXUS_EMBEDDING_URL && process.env.GITNEXUS_EMBEDDING_MODEL);
 /**
  * Return the configured embedding dimensions for HTTP mode, or undefined
  * if HTTP mode is not active or no explicit dimensions are set.
@@ -70,6 +92,63 @@ export const safeUrl = (url) => {
         return '<invalid-url>';
     }
 };
+/**
+ * Strip credentials from an underlying transport error message before it is
+ * surfaced. A credential-bearing endpoint URL (`https://user:secret@host/v1`)
+ * makes undici throw `TypeError: Request cannot be constructed from a URL that
+ * includes credentials: <that full URL>`; interpolating `err.message` verbatim
+ * would re-leak the secret to stderr + logs even though the URL argument is
+ * already masked with {@link safeUrl}. First swap the exact configured `url` for
+ * its masked form, then strip any residual `scheme://userinfo@` the transport may
+ * have echoed in a normalized (non-exact) form. See #2385.
+ */
+const sanitizeReason = (reason, url) => reason
+    .split(url)
+    .join(safeUrl(url))
+    .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/gi, '$1');
+/**
+ * Error thrown by this module's HTTP embedding path (`httpEmbedBatch` /
+ * `httpEmbed` / `httpEmbedQuery`) for any endpoint failure — a
+ * connection/timeout/DNS error, an open circuit, a non-OK status, an
+ * unparseable or wrong-shape response body, an empty response, or a dimension
+ * mismatch.
+ *
+ * Carrying a distinct type (rather than a plain `Error`) lets the CLI tell a
+ * *custom endpoint* failure apart from a HuggingFace *model download* failure
+ * without matching message text: the two share the same underlying network
+ * substrings (`fetch failed`, `ECONNREFUSED`, …), which is exactly why
+ * `isNetworkFetchError` in `hf-env.ts` cannot tell them apart. Keying on the
+ * type instead of the message is also locale-proof and survives message
+ * rewording. The human-readable `.message` (built with `safeUrl` and the
+ * underlying reason) is what the CLI surfaces to the user. See #2385.
+ */
+export class HttpEmbeddingError extends Error {
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'HttpEmbeddingError';
+    }
+}
+/**
+ * @internal Exported for the CLI analyze error handler and unit tests.
+ *
+ * Type-guard for {@link HttpEmbeddingError}. The `name` fallback keeps the
+ * check working across module-realm boundaries where `instanceof` can fail
+ * (two loaded copies of the class) — mirroring the codebase's existing
+ * `err.name === 'TimeoutError'` idiom. Matches on the stable class
+ * discriminator, never on the human-readable (potentially localized) message.
+ */
+export const isHttpEmbeddingError = (err) => err instanceof HttpEmbeddingError || (err instanceof Error && err.name === 'HttpEmbeddingError');
+/**
+ * Runtime guard for a single response item. The `Array.isArray(data.data)` shape
+ * check only validates the outer array — a 200 body like `{"data":[null]}` passes
+ * it, then crashes at `new Float32Array(item.embedding)` (`httpEmbed`) or
+ * `items[0].embedding` (`httpEmbedQuery`) with a raw `TypeError` that escapes the
+ * typed boundary, landing on the CLI's generic stack-dump path — the exact class
+ * #2385 closes. Validate each item so every wrong-shape body stays classifiable.
+ */
+const isEmbeddingItem = (item) => typeof item === 'object' &&
+    item !== null &&
+    Array.isArray(item.embedding);
 /**
  * Send a single batch of texts to the embedding endpoint with retry.
  *
@@ -111,23 +190,36 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
     }
     catch (err) {
         if (err instanceof CircuitOpenError) {
-            throw new Error(`Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`);
+            throw new HttpEmbeddingError(`Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`, { cause: err });
         }
         if (err instanceof DOMException && err.name === 'TimeoutError') {
-            throw new Error(`Embedding request timed out after ${HTTP_TIMEOUT_MS}ms (${safeUrl(url)}, batch ${batchIndex})`);
+            throw new HttpEmbeddingError(`Embedding request timed out after ${HTTP_TIMEOUT_MS}ms (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
         }
         if (err instanceof ResilientFetchExhaustedError) {
-            throw new Error(`Embedding endpoint returned ${err.response.status} (${safeUrl(url)}, batch ${batchIndex})`);
+            throw new HttpEmbeddingError(`Embedding endpoint returned ${err.response.status} (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
         }
-        const reason = err instanceof Error ? err.message : String(err);
-        throw new Error(`Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`);
+        const reason = sanitizeReason(err instanceof Error ? err.message : String(err), url);
+        throw new HttpEmbeddingError(`Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`, { cause: err });
     }
     if (!resp.ok) {
         // resilientFetch already retried 5xx/429; any non-OK response here is
         // a terminal client error (4xx other than 429).
-        throw new Error(`Embedding endpoint returned ${resp.status} (${safeUrl(url)}, batch ${batchIndex})`);
+        throw new HttpEmbeddingError(`Embedding endpoint returned ${resp.status} (${safeUrl(url)}, batch ${batchIndex})`);
+    }
+    // A reachable-but-wrong endpoint (e.g. a captive portal or a non-embeddings
+    // service) can answer 200 with an HTML/truncated body. Parse inside the
+    // typed-error boundary so that lands as an endpoint failure the CLI can
+    // classify, not a raw SyntaxError/TypeError on the generic stack-dump path.
+    let data;
+    try {
+        data = (await resp.json());
+    }
+    catch (err) {
+        throw new HttpEmbeddingError(`Embedding endpoint returned an unparseable response (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
+    }
+    if (!Array.isArray(data?.data) || !data.data.every(isEmbeddingItem)) {
+        throw new HttpEmbeddingError(`Embedding endpoint returned an unexpected response shape (${safeUrl(url)}, batch ${batchIndex})`);
     }
-    const data = (await resp.json());
     return data.data;
 };
 /**
@@ -150,7 +242,7 @@ export const httpEmbed = async (texts) => {
         const batchIndex = Math.floor(i / HTTP_BATCH_SIZE);
         const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.dimensions);
         if (items.length !== batch.length) {
-            throw new Error(`Embedding endpoint returned ${items.length} vectors for ${batch.length} texts ` +
+            throw new HttpEmbeddingError(`Embedding endpoint returned ${items.length} vectors for ${batch.length} texts ` +
                 `(${safeUrl(url)}, batch ${batchIndex})`);
         }
         for (const item of items) {
@@ -162,7 +254,7 @@ export const httpEmbed = async (texts) => {
                 const hint = config.dimensions
                     ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'
                     : `Set GITNEXUS_EMBEDDING_DIMS=${vec.length} to match your model output.`;
-                throw new Error(`Embedding dimension mismatch: endpoint returned ${vec.length}d vector, ` +
+                throw new HttpEmbeddingError(`Embedding dimension mismatch: endpoint returned ${vec.length}d vector, ` +
                     `but expected ${expected}d. ${hint}`);
             }
             allVectors.push(vec);
@@ -184,7 +276,7 @@ export const httpEmbedQuery = async (text) => {
     const url = `${config.baseUrl}/embeddings`;
     const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.dimensions);
     if (!items.length) {
-        throw new Error(`Embedding endpoint returned empty response (${safeUrl(url)})`);
+        throw new HttpEmbeddingError(`Embedding endpoint returned empty response (${safeUrl(url)})`);
     }
     const embedding = items[0].embedding;
     // Same dimension checks as httpEmbed — catch mismatches before they
@@ -194,7 +286,7 @@ export const httpEmbedQuery = async (text) => {
         const hint = config.dimensions
             ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'
             : `Set GITNEXUS_EMBEDDING_DIMS=${embedding.length} to match your model output.`;
-        throw new Error(`Embedding dimension mismatch: endpoint returned ${embedding.length}d vector, ` +
+        throw new HttpEmbeddingError(`Embedding dimension mismatch: endpoint returned ${embedding.length}d vector, ` +
             `but expected ${expected}d. ${hint}`);
     }
     return embedding;

package/dist/core/lbug/extension-load-error.d.ts

@@ -0,0 +1,67 @@
+export type ExtensionLoadErrorKind = 'missing_file' | 'corrupt_file' | 'missing_dependency' | 'unknown';
+export interface ExtensionLoadDiagnosis {
+    readonly kind: ExtensionLoadErrorKind;
+    /** Actionable, literal-English remedy suited to the class. */
+    readonly remedy: string;
+}
+/**
+ * On-disk file corruption / wrong-platform. FORCE INSTALL re-downloads.
+ * Kept byte-identical to `FILE_CORRUPTION_SIGNATURES` in
+ * scripts/install-duckdb-extension.mjs (that `.mjs` cannot import this `.ts`;
+ * the duplication is deliberate — the two serve different call sites). Note
+ * `/not a valid/i` already covers Windows error 193 ("is not a valid Win32
+ * application"), so a truncated Windows download is caught here, before the
+ * missing-dependency branch.
+ */
+export declare const FILE_CORRUPTION_SIGNATURES: readonly RegExp[];
+/**
+ * Classify a collapsed LadybugDB LOAD error. Order is most-specific-first and is
+ * load-bearing: corrupt-file is tested before missing-dependency so a truncated
+ * Windows download (error 193, matched by `/not a valid/i`) routes to
+ * FORCE-reinstall rather than to the runtime-install remedy.
+ */
+export declare function classifyExtensionLoadError(reason: string | undefined | null): ExtensionLoadDiagnosis;
+/** Well-formedness of the extension binary for the host platform + arch. */
+export type ExtensionBinaryState = 'absent' | 'corrupt' | 'valid' | 'indeterminate';
+/**
+ * Pull the extension file path out of lbug's load error. lbug's wrapper is
+ * English regardless of OS language — `Failed to load library: {path} which is
+ * needed by extension: {name}` (real lbug), or the quoted `Failed to load
+ * library '{path}': {reason}` variant — so the path is recoverable in any locale.
+ * Only paths ending in `.lbug_extension` are accepted, so a regex misfire can
+ * never point the inspector at an arbitrary file.
+ */
+export declare function extractExtensionPath(reason: string | undefined | null): string | null;
+/**
+ * A structural verdict on a binary header. `indeterminate` means the probe could
+ * not prove validity OR corruption from what it read (e.g. the PE header sits past
+ * the BINARY_HEADER_BYTES window) — the caller defers to the string classifier
+ * rather than assert a false verdict.
+ */
+type HeaderVerdict = 'valid' | 'corrupt' | 'indeterminate';
+/**
+ * Decide whether a binary header is a well-formed shared library for the given
+ * platform + architecture — using only the file's structure, no localized text.
+ * Pure and injectable (platform/arch as params) so every format+arch combination
+ * is unit-testable regardless of the host it runs on.
+ */
+export declare function classifyBinaryHeader(buf: Buffer, bytesRead: number, platform: NodeJS.Platform, arch: string): HeaderVerdict;
+/**
+ * Best-effort language-independent inspection of the extension file. Reads the
+ * header and classifies it; never throws — a missing file is `absent`, an
+ * unreadable one is `indeterminate`.
+ */
+export declare function inspectExtensionBinary(extensionPath: string | null | undefined): ExtensionBinaryState;
+/**
+ * Diagnose a LadybugDB load failure, preferring a LANGUAGE-INDEPENDENT structural
+ * check of the extension binary over the localized error text:
+ *   - file absent             → missing_file
+ *   - present but malformed    → corrupt_file       (bad magic / wrong architecture)
+ *   - present and well-formed   → missing_dependency (a valid binary the loader rejected)
+ * The path comes from lbug's own English wrapper, so this holds in any OS display
+ * language. When the file cannot be located or read, it falls back to the string
+ * classifier (which still carries the language-independent hedged fallback). This
+ * is the entry point every surface should call.
+ */
+export declare function diagnoseExtensionLoad(reason: string | undefined | null): ExtensionLoadDiagnosis;
+export {};

package/dist/core/lbug/extension-load-error.js

@@ -0,0 +1,320 @@
+/**
+ * Classify a LadybugDB `LOAD EXTENSION` failure into one of four actionable
+ * classes and produce an accurate, literal-English remedy.
+ *
+ * Background (#2374): PR #2375 made the real LadybugDB LOAD error visible
+ * (instead of a false "not pre-installed" message). The rc.4 reproduction then
+ * showed the remaining defect — on Windows the extension file downloads and
+ * INSTALLs fine, but `LoadLibrary` fails with error 126 ("the specified module
+ * could not be found" / `找不到指定的模块`) because the extension dynamically
+ * imports OpenSSL 3 / MSVC 14 DLLs that ship nowhere. For that class, telling
+ * the user to reinstall/redownload is wrong — the file is fine; a *runtime
+ * dependency* is missing. This module decides which class an error is so each
+ * surface (doctor, --repair-fts, the analyze degrade warning, and
+ * ftsDegradedWarning) can emit the right remedy instead of a one-size-fits-all
+ * "reinstall over the network".
+ *
+ * `classifyExtensionLoadError` is pure string logic — no `@ladybugdb/core`
+ * import, no filesystem — which keeps `native-check.ts` free of a static lbug
+ * dependency. `diagnoseExtensionLoad` layers a LANGUAGE-INDEPENDENT structural
+ * check on top: it pulls the extension's file path out of lbug's own (English)
+ * wrapper and inspects the binary header directly (PE/ELF/Mach-O magic +
+ * architecture), so corrupt-vs-valid is decided by the file itself, not by the
+ * localized OS error tail. It reads the file (node:fs core module only, still no
+ * lbug) and never throws — any read failure degrades to the string classifier.
+ */
+import { closeSync, openSync, readSync } from 'node:fs';
+/** LadybugDB says the extension file was never installed. INSTALL can heal it. */
+const MISSING_FILE_SIGNATURES = [
+    /has not been installed/i,
+    /not been installed/i,
+];
+/**
+ * On-disk file corruption / wrong-platform. FORCE INSTALL re-downloads.
+ * Kept byte-identical to `FILE_CORRUPTION_SIGNATURES` in
+ * scripts/install-duckdb-extension.mjs (that `.mjs` cannot import this `.ts`;
+ * the duplication is deliberate — the two serve different call sites). Note
+ * `/not a valid/i` already covers Windows error 193 ("is not a valid Win32
+ * application"), so a truncated Windows download is caught here, before the
+ * missing-dependency branch.
+ */
+// Exported so a parity test can assert this stays byte-identical to the copy in
+// scripts/install-duckdb-extension.mjs (that `.mjs` cannot import this `.ts`), #2383 F5b.
+export const FILE_CORRUPTION_SIGNATURES = [
+    /invalid elf/i,
+    /file too short/i,
+    /not a valid/i,
+    /bad magic/i,
+    /wrong architecture/i,
+    /mach-o/i,
+    /truncat/i,
+];
+/**
+ * A *transitive dependency* of the extension is missing — the file loaded far
+ * enough to be found, but a library it needs is absent. Reinstalling the
+ * extension is a no-op for this class.
+ *
+ * WINDOWS CATCH-ALL GUARD (adversarial review): LadybugDB wraps *every* Windows
+ * load failure in `Failed to load library … which is needed by extension`, so
+ * that generic wrapper must NOT be sufficient — otherwise error 127 (wrong
+ * OpenSSL minor / unresolved procedure), 5 (AV/permission lock), and 1114
+ * (dependency DllMain failure) would all be mislabeled `missing_dependency` and
+ * told to install a runtime, the opposite of their real fix. We key strictly on
+ * the specific error-126 tail. Linux/macOS loaders name the missing library
+ * directly, so their signals are unambiguous.
+ *
+ * Localized Windows tails we do not enumerate (French, German, Japanese, …) and
+ * mojibake renderings of the Chinese text won't match here — but they still
+ * carry lbug's language-independent `Failed to load library` wrapper, so they
+ * are caught by the hedged fallback (LOAD_FAILURE_WRAPPER) with a non-committal
+ * remedy, never a wrong confident "reinstall" instruction.
+ */
+const WINDOWS_MISSING_DEPENDENCY_SIGNATURES = [
+    /找不到指定的模块/,
+    /specified module could not be found/i,
+];
+const POSIX_MISSING_DEPENDENCY_SIGNATURES = [
+    /cannot open shared object file/i, // Linux ld.so
+    /image not found/i, // macOS dyld
+    /library not loaded/i, // macOS dyld
+];
+/**
+ * LadybugDB's own English wrapper for a dlopen/LoadLibrary failure
+ * (extension.cpp: `Failed to load library: {path} which is needed by extension:
+ * {name}`). It is emitted for EVERY extension load failure regardless of the OS
+ * display language — the only localized part is the OS-error tail after it. So
+ * it is the language-independent fallback signal once the specific tails miss: a
+ * French/German/Japanese Windows 126 has a localized tail we cannot enumerate,
+ * but it still carries this wrapper. See HEDGED_LOAD_FAILURE_REMEDY.
+ */
+const LOAD_FAILURE_WRAPPER = /failed to load library/i;
+const MISSING_FILE_REMEDY = 'The FTS extension is not installed. Re-run with network access and ' +
+    'GITNEXUS_LBUG_EXTENSION_INSTALL=auto (or `gitnexus analyze --repair-fts`) to download it.';
+const CORRUPT_FILE_REMEDY = 'The FTS extension file is present but unreadable (corrupt, truncated, or built for another ' +
+    'platform). Re-download it with network access and GITNEXUS_LBUG_EXTENSION_INSTALL=auto ' +
+    '(`gitnexus analyze --repair-fts`).';
+// Single source of truth for the VC++ runtime-install pointer, shared by the
+// Windows-126 and structural missing-dependency remedies so the name/URL cannot
+// drift between them (#2383 F5).
+const VC_REDIST_INSTALL_HINT = 'the Microsoft Visual C++ 2015-2022 Redistributable (x64) from ' +
+    'https://aka.ms/vs/17/release/vc_redist.x64.exe';
+// MSVC-first per DuckDB's canonical answer for this exact error; OpenSSL second.
+const WINDOWS_MISSING_DEPENDENCY_REMEDY = 'The FTS extension is present but a required runtime library is missing (Windows error 126). ' +
+    'Reinstalling the extension will NOT help. Install ' +
+    VC_REDIST_INSTALL_HINT +
+    '; if the error persists, the extension also needs OpenSSL 3 ' +
+    '(libcrypto-3-x64.dll / libssl-3-x64.dll) on the DLL search path.';
+const POSIX_MISSING_DEPENDENCY_REMEDY = 'The FTS extension is present but a shared library it depends on could not be loaded (named in ' +
+    'the error above). Reinstalling the extension will NOT help — install that library or add it to ' +
+    'your loader search path.';
+// Language-independent fallback: we know the extension failed to load, but the
+// OS-error tail is in a locale we did not enumerate, so we cannot say which class
+// it is. Hedge honestly — point at the user's own localized error and give both
+// branches — rather than confidently prescribing the wrong single fix. The clean
+// long-term fix is upstream: have LadybugDB include the numeric GetLastError/errno
+// in the message (as it already does elsewhere), so this becomes a code match.
+const HEDGED_LOAD_FAILURE_REMEDY = 'The FTS extension file was found but could not be loaded — see the "Error:" text above (shown ' +
+    "in your system's language). Reinstalling usually will not help. If it names a missing module or " +
+    'library, install the required runtime (on Windows: the Microsoft Visual C++ 2015-2022 ' +
+    'Redistributable x64 and OpenSSL 3); if it names a corrupt or invalid file, run ' +
+    '`gitnexus analyze --repair-fts` to re-download.';
+const UNKNOWN_REMEDY = 'The FTS extension failed to load for an unrecognized reason. Run `gitnexus doctor` for live ' +
+    'FTS status and verify the extension file and platform.';
+const matchesAny = (reason, signatures) => signatures.some((re) => re.test(reason));
+/**
+ * Classify a collapsed LadybugDB LOAD error. Order is most-specific-first and is
+ * load-bearing: corrupt-file is tested before missing-dependency so a truncated
+ * Windows download (error 193, matched by `/not a valid/i`) routes to
+ * FORCE-reinstall rather than to the runtime-install remedy.
+ */
+export function classifyExtensionLoadError(reason) {
+    const text = reason ?? '';
+    if (matchesAny(text, MISSING_FILE_SIGNATURES)) {
+        return { kind: 'missing_file', remedy: MISSING_FILE_REMEDY };
+    }
+    if (matchesAny(text, FILE_CORRUPTION_SIGNATURES)) {
+        return { kind: 'corrupt_file', remedy: CORRUPT_FILE_REMEDY };
+    }
+    if (matchesAny(text, WINDOWS_MISSING_DEPENDENCY_SIGNATURES)) {
+        return { kind: 'missing_dependency', remedy: WINDOWS_MISSING_DEPENDENCY_REMEDY };
+    }
+    if (matchesAny(text, POSIX_MISSING_DEPENDENCY_SIGNATURES)) {
+        return { kind: 'missing_dependency', remedy: POSIX_MISSING_DEPENDENCY_REMEDY };
+    }
+    // Language-independent fallback: the extension demonstrably failed to load
+    // (lbug's English wrapper is present) but the localized OS tail matched no
+    // specific class. Treat as a dependency/runtime load failure with a hedged
+    // remedy — strictly better than the generic `unknown` for non-English hosts,
+    // and it never prescribes the wrong fix.
+    if (LOAD_FAILURE_WRAPPER.test(text)) {
+        return { kind: 'missing_dependency', remedy: HEDGED_LOAD_FAILURE_REMEDY };
+    }
+    return { kind: 'unknown', remedy: UNKNOWN_REMEDY };
+}
+const STRUCTURAL_MISSING_DEPENDENCY_REMEDY = 'The FTS extension file is valid, so the failure is a missing or incompatible runtime dependency, ' +
+    'not the extension itself — reinstalling will NOT help. On Windows, install ' +
+    VC_REDIST_INSTALL_HINT +
+    ' and ensure OpenSSL 3 is available; on Linux/macOS install the shared library named in the error above.';
+/**
+ * Pull the extension file path out of lbug's load error. lbug's wrapper is
+ * English regardless of OS language — `Failed to load library: {path} which is
+ * needed by extension: {name}` (real lbug), or the quoted `Failed to load
+ * library '{path}': {reason}` variant — so the path is recoverable in any locale.
+ * Only paths ending in `.lbug_extension` are accepted, so a regex misfire can
+ * never point the inspector at an arbitrary file.
+ */
+export function extractExtensionPath(reason) {
+    const text = reason ?? '';
+    const m = /failed to load library:?\s*['"]?(.+?\.lbug_extension)/i.exec(text);
+    const path = m?.[1]?.trim();
+    return path && path.length > 0 ? path : null;
+}
+/** Node `process.arch` → PE `Machine`. Undefined for arches we don't map. */
+const PE_MACHINE = { x64: 0x8664, arm64: 0xaa64 };
+/** Node `process.arch` → ELF `e_machine`. */
+const ELF_MACHINE = { x64: 0x3e, arm64: 0xb7 };
+/** Node `process.arch` → Mach-O `cputype`. */
+const MACHO_CPUTYPE = { x64: 0x01000007, arm64: 0x0100000c };
+function classifyPE(buf, bytesRead, arch) {
+    if (bytesRead < 0x40 || buf[0] !== 0x4d || buf[1] !== 0x5a)
+        return 'corrupt'; // 'MZ'
+    const peOffset = buf.readUInt32LE(0x3c);
+    // The PE header (e_lfanew) points beyond what we read. A large-DOS-stub VALID PE
+    // and a garbage e_lfanew are indistinguishable from here, so don't claim 'corrupt'
+    // — defer to the loader's own report (#2383 F1-secondary).
+    if (peOffset + 6 > bytesRead)
+        return 'indeterminate';
+    const isPE = buf[peOffset] === 0x50 &&
+        buf[peOffset + 1] === 0x45 &&
+        buf[peOffset + 2] === 0 &&
+        buf[peOffset + 3] === 0;
+    if (!isPE)
+        return 'corrupt';
+    const expected = PE_MACHINE[arch];
+    if (expected === undefined)
+        return 'valid'; // arch we don't map: don't claim corrupt
+    return buf.readUInt16LE(peOffset + 4) === expected ? 'valid' : 'corrupt';
+}
+function classifyELF(buf, bytesRead, arch) {
+    if (bytesRead < 20)
+        return 'corrupt';
+    if (buf[0] !== 0x7f || buf[1] !== 0x45 || buf[2] !== 0x4c || buf[3] !== 0x46)
+        return 'corrupt'; // 0x7F ELF
+    const littleEndian = buf[5] === 1; // EI_DATA
+    const eMachine = littleEndian ? buf.readUInt16LE(18) : buf.readUInt16BE(18);
+    const expected = ELF_MACHINE[arch];
+    if (expected === undefined)
+        return 'valid';
+    return eMachine === expected ? 'valid' : 'corrupt';
+}
+function classifyMachO(buf, bytesRead, arch) {
+    if (bytesRead < 8)
+        return 'corrupt';
+    const magicLE = buf.readUInt32LE(0);
+    const magicBE = buf.readUInt32BE(0);
+    // Universal ("fat") binary — assume it carries the host slice.
+    if (magicBE === 0xcafebabe || magicLE === 0xcafebabe)
+        return 'valid';
+    const thin = magicLE === 0xfeedfacf || magicLE === 0xfeedface;
+    const thinSwapped = magicBE === 0xfeedfacf || magicBE === 0xfeedface;
+    if (!thin && !thinSwapped)
+        return 'corrupt';
+    const cpuType = thin ? buf.readUInt32LE(4) : buf.readUInt32BE(4);
+    const expected = MACHO_CPUTYPE[arch];
+    if (expected === undefined)
+        return 'valid';
+    return cpuType === expected ? 'valid' : 'corrupt';
+}
+/**
+ * Decide whether a binary header is a well-formed shared library for the given
+ * platform + architecture — using only the file's structure, no localized text.
+ * Pure and injectable (platform/arch as params) so every format+arch combination
+ * is unit-testable regardless of the host it runs on.
+ */
+export function classifyBinaryHeader(buf, bytesRead, platform, arch) {
+    if (platform === 'win32')
+        return classifyPE(buf, bytesRead, arch);
+    if (platform === 'linux')
+        return classifyELF(buf, bytesRead, arch);
+    if (platform === 'darwin')
+        return classifyMachO(buf, bytesRead, arch);
+    return 'valid'; // unknown host: never claim corrupt
+}
+const BINARY_HEADER_BYTES = 4096;
+/**
+ * Best-effort language-independent inspection of the extension file. Reads the
+ * header and classifies it; never throws — a missing file is `absent`, an
+ * unreadable one is `indeterminate`.
+ */
+export function inspectExtensionBinary(extensionPath) {
+    if (!extensionPath)
+        return 'indeterminate';
+    let fd;
+    try {
+        fd = openSync(extensionPath, 'r');
+    }
+    catch (err) {
+        return err?.code === 'ENOENT' ? 'absent' : 'indeterminate';
+    }
+    try {
+        const buf = Buffer.alloc(BINARY_HEADER_BYTES);
+        const bytesRead = readSync(fd, buf, 0, BINARY_HEADER_BYTES, 0);
+        return classifyBinaryHeader(buf, bytesRead, process.platform, process.arch);
+    }
+    catch {
+        return 'indeterminate';
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* closing the probe fd must never surface */
+        }
+    }
+}
+/**
+ * Diagnose a LadybugDB load failure, preferring a LANGUAGE-INDEPENDENT structural
+ * check of the extension binary over the localized error text:
+ *   - file absent             → missing_file
+ *   - present but malformed    → corrupt_file       (bad magic / wrong architecture)
+ *   - present and well-formed   → missing_dependency (a valid binary the loader rejected)
+ * The path comes from lbug's own English wrapper, so this holds in any OS display
+ * language. When the file cannot be located or read, it falls back to the string
+ * classifier (which still carries the language-independent hedged fallback). This
+ * is the entry point every surface should call.
+ */
+export function diagnoseExtensionLoad(reason) {
+    const text = reason ?? '';
+    const stringResult = classifyExtensionLoadError(text);
+    const fileState = inspectExtensionBinary(extractExtensionPath(text));
+    if (fileState === 'corrupt') {
+        return { kind: 'corrupt_file', remedy: CORRUPT_FILE_REMEDY };
+    }
+    if (fileState === 'valid') {
+        // The structural probe only inspects the first BINARY_HEADER_BYTES, so a file
+        // truncated AFTER its header still reads 'valid'. When the loader itself reported
+        // corruption (e.g. "file too short" / Windows error 193 "not a valid Win32
+        // application"), that whole-file verdict is stronger evidence than an intact-looking
+        // header — honor it and route to re-download, not a runtime-dependency install (#2383
+        // F1). Localized corrupt tails classify as hedged missing_dependency (not
+        // corrupt_file), so they still fall through to the dependency remedy below.
+        if (stringResult.kind === 'corrupt_file') {
+            return stringResult;
+        }
+        // A structurally sound binary that still failed to load ⇒ a dependency/runtime
+        // problem, decided WITHOUT the localized tail. Keep the string classifier's
+        // sharper remedy when it recognized the specific case (e.g. English 126).
+        const remedy = stringResult.kind === 'missing_dependency'
+            ? stringResult.remedy
+            : STRUCTURAL_MISSING_DEPENDENCY_REMEDY;
+        return { kind: 'missing_dependency', remedy };
+    }
+    // 'absent' or 'indeterminate' → no positive structural evidence, so defer to the
+    // string classifier. Note a real never-installed extension has NO path in its
+    // reason (lbug says "has not been installed"), so it lands here via
+    // 'indeterminate' and the string classifier reports missing_file correctly; a
+    // path that lbug named but that is now gone (stale/racy) is better judged by
+    // what lbug actually reported than by re-deriving from disk.
+    return stringResult;
+}

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 {

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

@@ -1,6 +1,7 @@
 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_]*$/;
@@ -208,7 +209,14 @@ export class ExtensionManager {
         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/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/run-analyze.js

@@ -17,6 +17,7 @@ import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReuse
 import { createSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSIndexes, } from './search/fts-indexes.js';
 import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSearchFTSCjkSegmentation, } from './search/cjk-segmentation.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.';
@@ -368,13 +373,20 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 // 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 ftsReason = getExtensionCapabilities()
-                    .find((c) => c.name === 'fts')
-                    ?.reason?.replace(/\.$/, '');
+                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}` : '') +
-                    '. 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.');
+                    remedyTail);
             }
             progress('fts', 85, 'Repairing search indexes...');
             await createSearchFTSIndexes({
@@ -963,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 ────────────────────────

package/dist/core/search/fts-indexes.js

@@ -1,5 +1,6 @@
 import { createFTSIndex, dropFTSIndex, DEFAULT_FTS_STEMMER } from '../lbug/lbug-adapter.js';
 import { getExtensionCapabilities } from '../lbug/extension-loader.js';
+import { classifyExtensionLoadError } from '../lbug/extension-load-error.js';
 import { FTS_INDEXES } from './fts-schema.js';
 /**
  * Strip filesystem paths from a LadybugDB error before it reaches the HTTP
@@ -21,9 +22,18 @@ export const ftsDegradedWarning = () => {
     const fts = getExtensionCapabilities().find((c) => c.name === 'fts');
     if (fts && !fts.loaded) {
         const reason = fts.reason ? redactPaths(fts.reason).replace(/\.$/, '') : undefined;
+        // A missing *runtime dependency* (Windows error 126, etc.) is not healed by
+        // reinstalling (#2374) — surface the classified remedy instead of the generic
+        // reinstall tail. Read the diagnosis cached at mark-unavailable time so this
+        // per-request path (HTTP /api/search + MCP query) does NO file I/O (#2383 F3);
+        // fall back to the pure, no-I/O string classifier if it is somehow absent.
+        const { kind, remedy } = fts.diagnosis ?? classifyExtensionLoadError(fts.reason);
+        const tail = kind === 'missing_dependency'
+            ? ` ${remedy}`
+            : '. Run `gitnexus doctor` for details, then `gitnexus analyze --repair-fts` with network access to reinstall.';
         return ('FTS extension failed to load — keyword search degraded' +
             (reason ? ` (${reason})` : '') +
-            '. Run `gitnexus doctor` for details, then `gitnexus analyze --repair-fts` with network access to reinstall.');
+            tail);
     }
     return 'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.';
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.5",
+  "version": "1.6.10-rc.7",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/scripts/cross-platform-tests.ts

@@ -43,6 +43,7 @@ const PLATFORM_LOGIC = [
   'test/unit/cursor-hook.test.ts',
   'test/unit/sidecar-recovery.test.ts',
   'test/unit/pool-wal-recovery.test.ts',
+  'test/unit/lbug-adapter-wal-schema.test.ts',
   'test/unit/detect-changes-worktree.test.ts',
   'test/unit/eval-server-bind-restriction.test.ts',
   'test/unit/ignore-service.test.ts',
@@ -61,6 +62,11 @@ const PLATFORM_LOGIC = [
   // array form. Runs on every platform (the ubuntu suite covers Linux; this
   // registration adds windows + macos).
   'test/unit/embedding-install-arg-delivery.test.ts',
+  // Structural FTS-extension classifier against REAL binaries (#2374): on this
+  // matrix `process.execPath` / `lbugjs.node` are a real PE (windows) and Mach-O
+  // (macos), so the header parsing is proven on genuine binaries, not synthetic
+  // buffers (the ubuntu suite covers the ELF path).
+  'test/integration/extension-binary-real.test.ts',
 ];
 
 // Native LadybugDB integration tests — exercise the @ladybugdb/core

package/scripts/install-duckdb-extension.mjs

@@ -13,7 +13,9 @@ const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
 // a missing file (plain INSTALL downloads it), or a permanent non-file failure a
 // re-download can never fix (missing runtime dep: "cannot open shared object") —
 // plain INSTALL avoids re-downloading ~2 MB on every analyze run forever.
-const FILE_CORRUPTION_SIGNATURES = [
+// Exported so a parity test keeps this byte-identical to the copy in
+// src/core/lbug/extension-load-error.ts (this `.mjs` cannot import that `.ts`), #2383 F5b.
+export const FILE_CORRUPTION_SIGNATURES = [
   /invalid elf/i,
   /file too short/i,
   /not a valid/i,