gitnexus 1.6.10-rc.3 → 1.6.10-rc.4

package/README.md

@@ -444,14 +444,14 @@ The prefix defaults to `~/.gitnexus/embedding-runtime`; set `GITNEXUS_EMBEDDING_
 
 ### Analyze warns about unavailable FTS or VECTOR extensions
 
-GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
+GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process install if `LOAD` fails (a plain `INSTALL` to download a missing extension, escalating to `FORCE INSTALL` only when the `LOAD` error shows the existing file is broken or truncated, so a permanent non-file failure does not re-download on every run) and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
 
 Configure the behavior with these environment variables:
 
 | Variable                                     | Values                       | Default             | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | -------------------------------------------- | ---------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process `INSTALL` child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded install if LOAD fails — a plain `INSTALL`, escalating to `FORCE INSTALL` only when the LOAD error shows the present extension file is broken. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process extension-install child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer  | `porter`            | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`             | `none`              | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run. |
 | `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`              | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.                                                                                                                                                                                                                                                                                                                                                                                                                |

package/dist/cli/doctor.js

@@ -4,7 +4,7 @@ import { isHttpMode } from '../core/embeddings/http-client.js';
 import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
 import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
-import { checkLbugNative } from '../core/lbug/native-check.js';
+import { checkLbugNative, probeFtsExtensionLoad } from '../core/lbug/native-check.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
 function isCombiningMark(codePoint) {
@@ -108,7 +108,15 @@ export const doctorCommand = async () => {
     console.log('');
     console.log(t('doctor.capabilities'));
     console.log(`  ${label('doctor.labels.graphStore', 18)}${capabilities.graph}`);
-    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${capabilities.fts}`);
+    // Live LOAD probe, not the static platform capability — the static value
+    // said "available" while analyze failed to load the extension (#2374).
+    const ftsProbe = nativeCheck.ok
+        ? await probeFtsExtensionLoad()
+        : { loaded: false, reason: 'LadybugDB native module (lbugjs.node) failed to load' };
+    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${ftsProbe.loaded ? 'available' : 'unavailable'}`);
+    if (!ftsProbe.loaded && ftsProbe.reason) {
+        console.log(`  ${padDisplayEnd('', 18)}${ftsProbe.reason}`);
+    }
     console.log(`  ${label('doctor.labels.vectorIndex', 18)}${capabilities.vector}`);
     console.log(`  ${label('doctor.labels.semanticMode', 18)}${capabilities.semanticMode}`);
     // Surface the optional-extension install policy so offline users can see

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

@@ -29,7 +29,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 +58,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 +90,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

@@ -7,6 +7,8 @@ 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 +53,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 +62,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 +83,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 +102,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,39 +157,51 @@ 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) {

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/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,7 @@ 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 { 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';
@@ -365,9 +365,16 @@ 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 ftsReason = getExtensionCapabilities()
+                    .find((c) => c.name === 'fts')
+                    ?.reason?.replace(/\.$/, '');
+                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.');
             }
             progress('fts', 85, 'Repairing search indexes...');
             await createSearchFTSIndexes({

package/dist/core/search/fts-indexes.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Warning attached to search responses when BM25/FTS is degraded. Prefers the
+ * live extension-load failure (with LadybugDB's real reason, #2374) over the
+ * generic indexes-missing message, so "indexes exist but the extension broke"
+ * is not misreported as missing indexes.
+ */
+export declare const ftsDegradedWarning: () => string;
 export declare const SUPPORTED_FTS_STEMMERS: ReadonlySet<string>;
 export interface CreateSearchFTSIndexesOptions {
     onIndexStart?: (table: string, indexName: string) => void;

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

@@ -1,5 +1,32 @@
 import { createFTSIndex, dropFTSIndex, DEFAULT_FTS_STEMMER } from '../lbug/lbug-adapter.js';
+import { getExtensionCapabilities } from '../lbug/extension-loader.js';
 import { FTS_INDEXES } from './fts-schema.js';
+/**
+ * Strip filesystem paths from a LadybugDB error before it reaches the HTTP
+ * `/api/search` and MCP query surfaces (#2374, PR #2375): the raw LOAD error
+ * embeds the absolute extension path (username, home dir) which must not leak to
+ * a network client. The error class words ("Failed to load library", "invalid
+ * ELF header", "has not been installed") have no leading path separator and
+ * survive. CLI/doctor/log surfaces keep the full path (they read the reason
+ * directly, not through this function).
+ */
+const redactPaths = (reason) => reason.replace(/(?:[A-Za-z]:\\|\/)[^\s'"]+/g, '<path>');
+/**
+ * Warning attached to search responses when BM25/FTS is degraded. Prefers the
+ * live extension-load failure (with LadybugDB's real reason, #2374) over the
+ * generic indexes-missing message, so "indexes exist but the extension broke"
+ * is not misreported as missing indexes.
+ */
+export const ftsDegradedWarning = () => {
+    const fts = getExtensionCapabilities().find((c) => c.name === 'fts');
+    if (fts && !fts.loaded) {
+        const reason = fts.reason ? redactPaths(fts.reason).replace(/\.$/, '') : undefined;
+        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.');
+    }
+    return 'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.';
+};
 // Stemmers shipped by the LadybugDB FTS extension. Mirrors the lowercase token
 // set in the extension bundled with @ladybugdb/core 0.18.x (see package.json).
 // Keep in sync on a LadybugDB minor bump — a value here that the installed

package/dist/mcp/local/local-backend.js

@@ -26,6 +26,7 @@ import { rankExactEmbeddingRows, } from '../../core/embeddings/exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
 import { getExactScanLimit, isVectorExtensionSupportedByPlatform, } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
+import { ftsDegradedWarning } from '../../core/search/fts-indexes.js';
 import { cjkSegmentationModeMismatch, containsSegmentableCjkRun, getSearchFTSCjkSegmentation, isSupportedCjkSegmentationMode, MAX_CJK_SEGMENTATION_QUERY_LENGTH, } from '../../core/search/cjk-segmentation.js';
 import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
 import { logger } from '../../core/logger.js';
@@ -1659,7 +1660,7 @@ export class LocalBackend {
         // path, leaving the success-path response shape byte-identical.
         const warnings = [];
         if (!ftsUsed) {
-            warnings.push('FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.');
+            warnings.push(ftsDegradedWarning());
         }
         // #2331: a CJK query against a server process resolving
         // GITNEXUS_FTS_CJK_SEGMENTATION to 'none' silently misses sub-phrase

package/dist/server/api.js

@@ -18,6 +18,7 @@ import { isValidQueryParams } from '../core/lbug/query-params.js';
 import { NODE_TABLES } from '../_shared/index.js';
 import { searchFTSFromLbug } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
+import { ftsDegradedWarning } from '../core/search/fts-indexes.js';
 import { LocalBackend } from '../mcp/local/local-backend.js';
 import { mountMCPEndpoints } from './mcp-http.js';
 import { fileURLToPath } from 'url';
@@ -1140,8 +1141,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
             }, { readOnly: true });
             const response = { results: results.searchResults ?? results };
             if (results.ftsAvailable === false) {
-                response.warning =
-                    'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.';
+                response.warning = ftsDegradedWarning();
             }
             res.json(response);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.3",
+  "version": "1.6.10-rc.4",
   "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

@@ -100,6 +100,10 @@ const SPAWN_CLI = [
   'test/integration/cli-limit-e2e.test.ts',
   'test/integration/hooks-e2e.test.ts',
   'test/integration/skills-e2e.test.ts',
+  // Spawns the real CLI across hermetic HOME/USERPROFILE homes to exercise the
+  // FTS extension lifecycle — the #2374 bug was Windows-reported, so this must
+  // run on the Windows/macOS matrix, not just the Ubuntu full suite.
+  'test/integration/fts-extension-e2e.test.ts',
   'test/integration/server-http-startup.test.ts',
   'test/integration/mcp/server-startup.test.ts',
   'test/integration/analyze-heap-oom-e2e.test.ts',

package/scripts/install-duckdb-extension.mjs

@@ -3,9 +3,39 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 
 const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
 
+// Positive on-disk-corruption signatures. `FORCE INSTALL` re-downloads even when
+// a file is already present; we only want that when the LOAD error proves the
+// existing file is bad (truncated/wrong-platform, #2374). For everything else —
+// 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 = [
+  /invalid elf/i,
+  /file too short/i,
+  /not a valid/i,
+  /bad magic/i,
+  /wrong architecture/i,
+  /mach-o/i,
+  /truncat/i,
+];
+
+/**
+ * Decide the install verb from the LOAD error that triggered this install.
+ * `FORCE INSTALL` only when the error positively indicates file-level breakage;
+ * otherwise plain `INSTALL` (missing file, missing-dependency dlopen failure,
+ * or unknown/absent error).
+ */
+export function chooseInstallVerb(loadError) {
+  if (loadError && FILE_CORRUPTION_SIGNATURES.some((re) => re.test(loadError))) {
+    return 'FORCE INSTALL';
+  }
+  return 'INSTALL';
+}
+
 function parseLbugMaxDbSize(raw) {
   const parsed = raw ? Number(raw) : NaN;
   if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -14,28 +44,54 @@ function parseLbugMaxDbSize(raw) {
   return Math.floor(parsed);
 }
 
-async function installDuckDbExtension(extensionName, verifyOnly = false) {
-  if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
-    throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
-  }
-
-  const require = createRequire(import.meta.url);
-  const lbugModule = require('@ladybugdb/core');
-  const lbug = lbugModule.default ?? lbugModule;
+function resolveMaxDbSize() {
   // argv[3] is the optional positional size; ignore it when it is actually a
   // flag token (e.g. `--verify-only`) and fall back to the env default.
   const sizeArg =
     process.argv[3] && !process.argv[3].startsWith('--') ? process.argv[3] : undefined;
-  const lbugMaxDbSize = parseLbugMaxDbSize(sizeArg ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE);
+  return parseLbugMaxDbSize(sizeArg ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE);
+}
+
+/** Open a scratch LadybugDB and return its connection plus a disposer. */
+async function defaultConnect(lbugMaxDbSize) {
+  const require = createRequire(import.meta.url);
+  const lbugModule = require('@ladybugdb/core');
+  const lbug = lbugModule.default ?? lbugModule;
 
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ext-install-'));
   const dbPath = path.join(tmpDir, 'install.lbug');
-  let db;
-  let conn;
+  const db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
+  const conn = new lbug.Connection(db);
+  return {
+    conn,
+    dispose: async () => {
+      await conn.close().catch(() => {});
+      await db.close().catch(() => {});
+      await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    },
+  };
+}
+
+/**
+ * Install (or verify) an optional LadybugDB extension in this short-lived process.
+ *
+ * @param {string} extensionName
+ * @param {object} [options]
+ * @param {boolean} [options.verifyOnly] LOAD-only Docker build gate — no install.
+ * @param {string} [options.loadError] The parent's LOAD failure; selects the verb.
+ * @param {(size: number) => Promise<{conn: {query: (sql: string) => Promise<unknown>}, dispose: () => Promise<void>}>} [options.connect]
+ *        Connection factory; injectable for offline unit tests.
+ */
+export async function installDuckDbExtension(extensionName, options = {}) {
+  const { verifyOnly = false, loadError, connect } = options;
+  if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
+    throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
+  }
+
+  const makeConnection = connect ?? (() => defaultConnect(resolveMaxDbSize()));
+  const { conn, dispose } = await makeConnection();
 
   try {
-    db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
-    conn = new lbug.Connection(db);
     if (verifyOnly) {
       // Prove a previously-baked extension is resolvable by a FRESH process
       // under the current HOME (the runtime `LOAD EXTENSION` path) — no INSTALL,
@@ -46,19 +102,22 @@ async function installDuckDbExtension(extensionName, verifyOnly = false) {
         `[install-ext] LOAD-only verify OK for '${extensionName}' (HOME=${process.env.HOME})`,
       );
     } else {
-      await conn.query(`INSTALL ${extensionName}`);
+      // Plain INSTALL is a no-op when the file already exists; escalate to FORCE
+      // only when the LOAD error proves the on-disk file is broken (#2374).
+      await conn.query(`${chooseInstallVerb(loadError)} ${extensionName}`);
     }
   } finally {
-    if (conn) await conn.close().catch(() => {});
-    if (db) await db.close().catch(() => {});
-    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    await dispose();
   }
 }
 
-installDuckDbExtension(
-  process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME,
-  process.argv.includes('--verify-only'),
-).catch((err) => {
-  console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
-  process.exitCode = 1;
-});
+// Only run when executed directly — imported (e.g. by unit tests) it stays inert.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  installDuckDbExtension(process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME, {
+    verifyOnly: process.argv.includes('--verify-only'),
+    loadError: process.env.GITNEXUS_LBUG_EXTENSION_LOAD_ERROR,
+  }).catch((err) => {
+    console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+    process.exitCode = 1;
+  });
+}