gitnexus 1.6.4-rc.92 → 1.6.4-rc.94

package/dist/core/augmentation/engine.js

@@ -90,7 +90,7 @@ export async function augment(pattern, cwd) {
             await initLbug(repoId, repo.lbugPath);
         }
         // Step 1: BM25 search (fast, no embeddings)
-        const bm25Results = await searchFTSFromLbug(pattern, 10, repoId);
+        const { results: bm25Results } = await searchFTSFromLbug(pattern, 10, repoId);
         if (bm25Results.length === 0)
             return '';
         // Step 2: Map BM25 file results to symbols

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

@@ -32,12 +32,6 @@ export interface RelCsvSplitResult {
 export declare const splitRelCsvByLabelPair: (csvPath: string, csvDir: string, validTables: Set<string>, getNodeLabel: (id: string) => string, wsFactory?: WriteStreamFactory) => Promise<RelCsvSplitResult>;
 /** Expose the current Database for pool adapter reuse in tests. */
 export declare const getDatabase: () => lbug.Database | null;
-/**
- * Return true when the error message indicates that another process holds
- * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
- * `gitnexus serve` running at the same time).
- */
-export declare const isDbBusyError: (err: unknown) => boolean;
 /**
  * Return true when the error message indicates a write was attempted against
  * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,

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

@@ -8,7 +8,7 @@ import lbug from '@ladybugdb/core';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { extensionManager } from './extension-loader.js';
-import { closeLbugConnection, openLbugConnection, } from './lbug-config.js';
+import { closeLbugConnection, isDbBusyError, isOpenRetryExhausted, openLbugConnection, waitForWindowsHandleRelease, } from './lbug-config.js';
 import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 /**
@@ -140,18 +140,6 @@ let sessionLock = Promise.resolve();
 const DB_LOCK_RETRY_ATTEMPTS = 3;
 /** Base back-off in ms between BUSY retries (multiplied by attempt number). */
 const DB_LOCK_RETRY_DELAY_MS = 500;
-/**
- * Return true when the error message indicates that another process holds
- * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
- * `gitnexus serve` running at the same time).
- */
-export const isDbBusyError = (err) => {
-    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
-    return (msg.includes('busy') ||
-        msg.includes('lock') ||
-        msg.includes('already in use') ||
-        msg.includes('could not set lock'));
-};
 /**
  * Return true when the error message indicates a write was attempted against
  * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,
@@ -201,7 +189,11 @@ export const withLbugDb = async (dbPath, operation) => {
         }
         catch (err) {
             lastError = err;
-            if (!isDbBusyError(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
+            // Skip outer retry when the inner open-retry already exhausted: the
+            // ~1.5s open-time budget was just spent, repeating the full reset+
+            // reopen cycle would only add 4-5s of tail latency without changing
+            // the outcome (both layers consult the same isDbBusyError matcher).
+            if (!isDbBusyError(err) || isOpenRetryExhausted(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
                 throw err;
             }
             // Close stale connection inside the session lock to prevent race conditions
@@ -274,7 +266,16 @@ const doInitLbug = async (dbPath) => {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            if (!msg.includes('already exists')) {
+            // Suppression list:
+            //   - "already exists": expected idempotent re-create on existing DBs
+            //   - "could not set lock on file": LadybugDB v0.16.1 emits this on
+            //     Windows when CREATE NODE TABLE runs against a path that was
+            //     just opened (the WAL handle from a fresh Database briefly
+            //     contests the table's first-write lock). The table is created
+            //     anyway and any genuine cross-process lock contention surfaces
+            //     on the next operation via withLbugDb's retry. Logging it here
+            //     would just be noise in CI.
+            if (!msg.includes('already exists') && !isDbBusyError(err)) {
                 logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
             }
         }
@@ -940,6 +941,9 @@ export const flushWAL = async () => {
  */
 export const safeClose = async () => {
     await flushWAL();
+    // Capture before close — currentDbPath stays set so the Windows post-close
+    // probe below knows which file to wait on.
+    const closingDbPath = currentDbPath;
     if (conn) {
         try {
             // eslint-disable-next-line no-restricted-syntax -- sole authorised close site
@@ -960,6 +964,21 @@ export const safeClose = async () => {
         }
         db = null;
     }
+    // Windows: libuv reports `db.close()` resolved before the kernel has
+    // released the file handle. A subsequent `new Database(samePath)` in
+    // the same process can race the release. The probe (lbug-config.ts)
+    // forces any residual lock to surface as EBUSY/EPERM/EACCES so the
+    // open-time retry absorbs the lag.
+    if (process.platform === 'win32' && closingDbPath) {
+        const released = await waitForWindowsHandleRelease(closingDbPath);
+        if (!released) {
+            // Probe exhausted with a lock code still in flight. The next
+            // openLbugConnection will absorb whatever residual lag remains, but
+            // a chronic warning helps operators spot AV interference (Windows
+            // Defender holding the file far past the 250ms budget).
+            logger.warn({ dbPath: closingDbPath }, '⚠️ LadybugDB file handle still locked after close (Windows). If this repeats, check antivirus/Defender exclusions for the GitNexus storage directory.');
+        }
+    }
 };
 export const closeLbug = async () => {
     await safeClose();

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

@@ -43,7 +43,60 @@ export interface LbugConnectionHandle {
     db: lbug.Database;
     conn: lbug.Connection;
 }
+/**
+ * Return true when the error message indicates that a LadybugDB file lock
+ * could not be acquired — either at construction time
+ * (`new lbug.Database(...)` raises from `local_file_system.cpp`) or during
+ * a query (another writer holds the exclusive lock).
+ *
+ * Lives here (not in `lbug-adapter.ts`) so both the construction-time
+ * retry (`openWithLockRetry` in this file) and the query-time retry
+ * (`withLbugDb` in `lbug-adapter.ts`) consult the same matcher. Callers
+ * import directly from this module — no re-export to keep in sync.
+ */
+export declare const isDbBusyError: (err: unknown) => boolean;
 export declare function createLbugDatabase(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): lbug.Database;
+/**
+ * Marker symbol attached to lock errors after `openWithLockRetry` exhausts
+ * its budget. `withLbugDb`'s outer query-time retry consults this so it
+ * does not re-retry a path that just spent up to ~1.5s in the open-time
+ * loop — preventing 6s tail latencies (3× outer × 5× inner attempts).
+ *
+ * The symbol is internal to GitNexus; consumers should treat the underlying
+ * error message as the user-visible signal.
+ */
+export declare const LBUG_OPEN_RETRY_EXHAUSTED: unique symbol;
+export declare const isOpenRetryExhausted: (err: unknown) => boolean;
+/** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
+export declare const _isTestFixturePathForTest: (dbPath: string) => boolean;
 export declare function openLbugConnection(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): Promise<LbugConnectionHandle>;
 export declare function closeLbugConnection(handle: LbugConnectionHandle): Promise<void>;
+/**
+ * Probe `dbPath` AND its `.wal` sidecar after `db.close()` so any
+ * residual native file handle surfaces as EBUSY/EPERM/EACCES and the
+ * bounded retry absorbs the release lag. Windows-only — Linux/macOS do
+ * not exhibit this race.
+ *
+ * Both files matter. Empirically, on rapid open→close→reopen cycles the
+ * main `dbPath` handle releases first; the `.wal` handle from the
+ * previous Database lingers and the new Database's first write (CREATE
+ * NODE TABLE during schema init) fails with "Could not set lock on
+ * file". Probing both makes safeClose actually return when the kernel
+ * is fully done with the path.
+ *
+ * Returns `true` when both probes succeeded (or skipped on non-lock
+ * errors / missing files). Returns `false` when either probe exhausted
+ * its budget with a lock code still in flight.
+ *
+ * Defensive shape:
+ *   - Opens read+write (`'r+'`) so the probe actually surfaces exclusive
+ *     locks held by the previous Database. A read-only probe (`'r'`) is
+ *     insufficient — Windows will grant read access while the previous
+ *     handle's exclusive write lock is still in flight, which lets
+ *     `safeClose` return before the next CREATE NODE TABLE can lock the
+ *     file.
+ *   - `try/finally` around `handle.close()` guarantees no fd leak even
+ *     if close itself throws.
+ */
+export declare const waitForWindowsHandleRelease: (dbPath: string) => Promise<boolean>;
 export {};

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

@@ -1,3 +1,6 @@
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
 /**
  * Shared configuration for `@ladybugdb/core` `Database` construction.
  *
@@ -48,6 +51,27 @@ export function isWalCorruptionError(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return WAL_CORRUPTION_RE.test(msg);
 }
+/**
+ * Return true when the error message indicates that a LadybugDB file lock
+ * could not be acquired — either at construction time
+ * (`new lbug.Database(...)` raises from `local_file_system.cpp`) or during
+ * a query (another writer holds the exclusive lock).
+ *
+ * Lives here (not in `lbug-adapter.ts`) so both the construction-time
+ * retry (`openWithLockRetry` in this file) and the query-time retry
+ * (`withLbugDb` in `lbug-adapter.ts`) consult the same matcher. Callers
+ * import directly from this module — no re-export to keep in sync.
+ */
+export const isDbBusyError = (err) => {
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    // `lock` already subsumes `could not set lock`; the broader term is kept
+    // because graph-DB transient errors include "deadlock", "lock contention",
+    // and the LadybugDB native module's "could not set lock on file" — all of
+    // which deserve a retry. If a non-transient lock-shaped error ever
+    // surfaces (e.g., "lock file missing" during recovery), tighten this
+    // matcher rather than raising the retry budget.
+    return msg.includes('busy') || msg.includes('lock') || msg.includes('already in use');
+};
 export function createLbugDatabase(lbugModule, databasePath, options = {}) {
     // .d.ts declares fewer args than the native constructor accepts.
     return new lbugModule.Database(databasePath, 0, // bufferManagerSize
@@ -56,10 +80,155 @@ export function createLbugDatabase(lbugModule, databasePath, options = {}) {
     -1, // checkpointThreshold
     options.throwOnWalReplayFailure ?? true, true);
 }
+// ─── Lock-busy retry tuning knobs ───────────────────────────────────────────
+//
+// All four GitNexus retry pairs that touch native LadybugDB locks live with
+// a comment cross-reference here so an SRE tuning Windows flakes finds them
+// in one grep:
+//
+//   1. OPEN_LOCK_RETRY_ATTEMPTS / OPEN_LOCK_RETRY_DELAY_MS  (this file)
+//      → `new lbug.Database()` constructor lock failures
+//   2. HANDLE_RELEASE_PROBE_ATTEMPTS / HANDLE_RELEASE_PROBE_DELAY_MS  (this file)
+//      → post-close fs.open probe to absorb Windows handle-release lag
+//   3. DB_LOCK_RETRY_ATTEMPTS / DB_LOCK_RETRY_DELAY_MS  (lbug-adapter.ts withLbugDb)
+//      → query-time busy/lock retry around already-open connections
+//
+// `new lbug.Database()` calls into the native module which performs an
+// OS-level exclusive lock on `<dbPath>`. On Windows that lock can fail
+// for reasons specific to the OS (Defender briefly opens new files,
+// libuv handle release lags the JS-side close). 5 attempts × 100ms
+// linear back-off (max sleep 100+200+300+400 = 1s, plus 5 ctor RTTs
+// of 10–50ms each = ~1.0–1.2s worst case) clears the typical
+// AV-scanner hold without masking real cross-process conflicts.
+//
+// Source: https://github.com/LadybugDB/ladybug/blob/v0.16.1/src/common/file_system/local_file_system.cpp#L126
+const OPEN_LOCK_RETRY_ATTEMPTS = 5;
+const OPEN_LOCK_RETRY_DELAY_MS = 100;
+const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
+const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
+const HANDLE_RELEASE_LOCK_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+/**
+ * Test-fixture directory prefixes recognized by `isTestFixturePath`.
+ *
+ * IMPORTANT: this list must stay in sync with the prefixes passed to
+ * `createTempDir` in `gitnexus/test/helpers/test-db.ts` and the prefixes
+ * used by `withTestLbugDB` (`gitnexus/test/helpers/test-indexed-db.ts`).
+ * If you add a new test that passes a custom prefix to `createTempDir`,
+ * add it here too — otherwise the stale-sidecar sweep silently won't
+ * fire for that fixture and CI flakes return.
+ *
+ * The default `createTempDir('gitnexus-test-')` and the lbug variant
+ * `'gitnexus-lbug-'` cover today's call sites.
+ */
+const TEST_FIXTURE_PREFIXES = ['gitnexus-lbug-', 'gitnexus-test-'];
+/**
+ * Marker symbol attached to lock errors after `openWithLockRetry` exhausts
+ * its budget. `withLbugDb`'s outer query-time retry consults this so it
+ * does not re-retry a path that just spent up to ~1.5s in the open-time
+ * loop — preventing 6s tail latencies (3× outer × 5× inner attempts).
+ *
+ * The symbol is internal to GitNexus; consumers should treat the underlying
+ * error message as the user-visible signal.
+ */
+export const LBUG_OPEN_RETRY_EXHAUSTED = Symbol.for('gitnexus.lbug.openRetryExhausted');
+export const isOpenRetryExhausted = (err) => {
+    if (err === null || err === undefined || typeof err !== 'object')
+        return false;
+    return err[LBUG_OPEN_RETRY_EXHAUSTED] === true;
+};
+const tagOpenRetryExhausted = (err) => {
+    if (err && typeof err === 'object') {
+        err[LBUG_OPEN_RETRY_EXHAUSTED] = true;
+    }
+    return err;
+};
+/**
+ * True when `dbPath` resolves to a recognized test fixture under the OS
+ * temp directory. Used to gate the stale-sidecar sweep so production
+ * paths never have their `.wal` / `.lock` files deleted.
+ *
+ * Defensive shape:
+ *   - `path.resolve` normalizes `..` segments before the prefix check, so
+ *     `<tmp>/gitnexus-lbug-x/../../etc/passwd` is rejected.
+ *   - The tmpRoot check trims any trailing separator returned by some
+ *     Windows TMP configurations (`C:\Users\X\Temp\`) so the startsWith
+ *     comparison stays correct.
+ *   - Only the IMMEDIATE parent directory is matched against the prefix
+ *     list. An ancestor walk would let a tmpdir whose own basename starts
+ *     with `gitnexus-lbug-` accept arbitrary nested paths under it.
+ */
+const isTestFixturePath = (dbPath) => {
+    const tmpRoot = os.tmpdir().replace(new RegExp(`${path.sep === '\\' ? '\\\\' : path.sep}+$`), '');
+    const resolved = path.resolve(dbPath);
+    if (!resolved.startsWith(tmpRoot + path.sep) && resolved !== tmpRoot)
+        return false;
+    const parentBase = path.basename(path.dirname(resolved));
+    return TEST_FIXTURE_PREFIXES.some((p) => parentBase.startsWith(p));
+};
+/** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
+export const _isTestFixturePathForTest = isTestFixturePath;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Attempt to remove stale `.wal` / `.lock` sidecars that a previous aborted
+ * test run may have left behind. Best-effort: ENOENT is normal, anything
+ * else is swallowed so the caller's retry can surface the original error.
+ */
+const sweepStaleSidecars = async (dbPath) => {
+    for (const suffix of ['.wal', '.lock']) {
+        try {
+            await fs.unlink(dbPath + suffix);
+        }
+        catch {
+            /* missing sidecar or permission error — let the open retry surface it */
+        }
+    }
+};
+/**
+ * Run `construct` with bounded retries when `new lbug.Database(...)` throws
+ * a busy/lock error. The original (loop-captured) error is preferred over
+ * any post-sweep error so triage sees the real LadybugDB lock message.
+ * On exhaustion the rethrown error is tagged via
+ * `LBUG_OPEN_RETRY_EXHAUSTED` so the outer query-time retry in
+ * `withLbugDb` skips re-retrying a freshly-exhausted path.
+ */
+const openWithLockRetry = async (construct, dbPath) => {
+    let originalLockError;
+    for (let attempt = 1; attempt <= OPEN_LOCK_RETRY_ATTEMPTS; attempt++) {
+        try {
+            return construct();
+        }
+        catch (err) {
+            if (!isDbBusyError(err))
+                throw err;
+            originalLockError = err;
+            if (attempt === OPEN_LOCK_RETRY_ATTEMPTS)
+                break;
+            await sleep(OPEN_LOCK_RETRY_DELAY_MS * attempt);
+        }
+    }
+    // Final defense: only for recognized test fixtures, sweep stale sidecars
+    // (a prior aborted test run can leave a `.wal` lock that survives the
+    // tmp dir cleanup). Production paths never reach this branch — the guard
+    // requires the immediate parent dir to match a test prefix AND the
+    // resolved path to live under the OS temp directory.
+    if (isTestFixturePath(dbPath)) {
+        await sweepStaleSidecars(dbPath);
+        try {
+            return construct();
+        }
+        catch {
+            // Intentionally do NOT overwrite originalLockError. The user-actionable
+            // signal is "we exhausted lock retries" — a different error from the
+            // post-sweep attempt is less useful than the lock failure that drove
+            // the sweep in the first place.
+        }
+    }
+    throw tagOpenRetryExhausted(originalLockError);
+};
 export async function openLbugConnection(lbugModule, databasePath, options = {}) {
     let db;
     try {
-        db = createLbugDatabase(lbugModule, databasePath, options);
+        db = await openWithLockRetry(() => createLbugDatabase(lbugModule, databasePath, options), databasePath);
         return { db, conn: new lbugModule.Connection(db) };
     }
     catch (err) {
@@ -72,3 +241,63 @@ export async function closeLbugConnection(handle) {
     await handle.conn.close().catch(() => { });
     await handle.db.close().catch(() => { });
 }
+/**
+ * Probe `dbPath` AND its `.wal` sidecar after `db.close()` so any
+ * residual native file handle surfaces as EBUSY/EPERM/EACCES and the
+ * bounded retry absorbs the release lag. Windows-only — Linux/macOS do
+ * not exhibit this race.
+ *
+ * Both files matter. Empirically, on rapid open→close→reopen cycles the
+ * main `dbPath` handle releases first; the `.wal` handle from the
+ * previous Database lingers and the new Database's first write (CREATE
+ * NODE TABLE during schema init) fails with "Could not set lock on
+ * file". Probing both makes safeClose actually return when the kernel
+ * is fully done with the path.
+ *
+ * Returns `true` when both probes succeeded (or skipped on non-lock
+ * errors / missing files). Returns `false` when either probe exhausted
+ * its budget with a lock code still in flight.
+ *
+ * Defensive shape:
+ *   - Opens read+write (`'r+'`) so the probe actually surfaces exclusive
+ *     locks held by the previous Database. A read-only probe (`'r'`) is
+ *     insufficient — Windows will grant read access while the previous
+ *     handle's exclusive write lock is still in flight, which lets
+ *     `safeClose` return before the next CREATE NODE TABLE can lock the
+ *     file.
+ *   - `try/finally` around `handle.close()` guarantees no fd leak even
+ *     if close itself throws.
+ */
+export const waitForWindowsHandleRelease = async (dbPath) => {
+    const mainReleased = await probeSinglePath(dbPath);
+    const walReleased = await probeSinglePath(dbPath + '.wal');
+    return mainReleased && walReleased;
+};
+const probeSinglePath = async (filePath) => {
+    for (let attempt = 1; attempt <= HANDLE_RELEASE_PROBE_ATTEMPTS; attempt++) {
+        let handle;
+        try {
+            handle = await fs.open(filePath, 'r+');
+            return true;
+        }
+        catch (err) {
+            const code = err?.code;
+            if (!code || !HANDLE_RELEASE_LOCK_CODES.has(code))
+                return true; // ENOENT / unrelated → not our problem
+            if (attempt === HANDLE_RELEASE_PROBE_ATTEMPTS)
+                return false;
+            await sleep(HANDLE_RELEASE_PROBE_DELAY_MS * attempt);
+        }
+        finally {
+            if (handle) {
+                try {
+                    await handle.close();
+                }
+                catch {
+                    /* swallow — caller cannot do anything useful with a probe-close failure */
+                }
+            }
+        }
+    }
+    return false;
+};

package/dist/core/search/bm25-index.d.ts

@@ -10,6 +10,11 @@ export interface BM25SearchResult {
     rank: number;
     nodeIds?: string[];
 }
+export interface FTSSearchResponse {
+    results: BM25SearchResult[];
+    /** True when at least one FTS index query succeeded (index exists). */
+    ftsAvailable: boolean;
+}
 /**
  * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
  *
@@ -21,4 +26,4 @@ export interface BM25SearchResult {
  * @param repoId - If provided, queries will be routed via the MCP connection pool
  * @returns Ranked search results from FTS indexes
  */
-export declare const searchFTSFromLbug: (query: string, limit?: number, repoId?: string) => Promise<BM25SearchResult[]>;
+export declare const searchFTSFromLbug: (query: string, limit?: number, repoId?: string) => Promise<FTSSearchResponse>;

package/dist/core/search/bm25-index.js

@@ -8,7 +8,8 @@ import { queryFTS } from '../lbug/lbug-adapter.js';
 import { FTS_INDEXES } from './fts-schema.js';
 /**
  * Execute a single FTS query via a custom executor (for MCP connection pool).
- * Returns the same shape as core queryFTS (from LadybugDB adapter).
+ * Returns `null` when the query fails (e.g. FTS index does not exist) so the
+ * caller can distinguish "zero matches" from "index missing".
  */
 async function queryFTSViaExecutor(executor, tableName, indexName, query, limit) {
     // Escape single quotes and backslashes to prevent Cypher injection
@@ -32,7 +33,7 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
         });
     }
     catch {
-        return [];
+        return null;
     }
 }
 /**
@@ -48,6 +49,7 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
  */
 export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
     const resultsByIndex = [];
+    let queriesSucceeded = 0;
     if (repoId) {
         // Use MCP connection pool via dynamic import
         // IMPORTANT: FTS queries run sequentially to avoid connection contention.
@@ -56,15 +58,27 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         const { executeQuery } = poolMod;
         const executor = (cypher) => executeQuery(repoId, cypher);
         for (const { table, indexName } of FTS_INDEXES) {
-            resultsByIndex.push(await queryFTSViaExecutor(executor, table, indexName, query, limit));
+            const result = await queryFTSViaExecutor(executor, table, indexName, query, limit);
+            if (result !== null) {
+                queriesSucceeded++;
+                resultsByIndex.push(result);
+            }
         }
     }
     else {
         // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
         for (const { table, indexName } of FTS_INDEXES) {
-            resultsByIndex.push(await queryFTS(table, indexName, query, limit, false).catch(() => []));
+            try {
+                const result = await queryFTS(table, indexName, query, limit, false);
+                queriesSucceeded++;
+                resultsByIndex.push(result);
+            }
+            catch {
+                // FTS index may not exist — count as failed
+            }
         }
     }
+    const ftsAvailable = queriesSucceeded > 0;
     // Collect all node scores per filePath to track which nodes actually matched
     const fileNodeScores = new Map();
     const addResults = (results) => {
@@ -92,10 +106,13 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
     const sorted = Array.from(merged.values())
         .sort((a, b) => b.score - a.score)
         .slice(0, limit);
-    return sorted.map((r, index) => ({
-        filePath: r.filePath,
-        score: r.score,
-        rank: index + 1,
-        nodeIds: r.nodeIds,
-    }));
+    return {
+        results: sorted.map((r, index) => ({
+            filePath: r.filePath,
+            score: r.score,
+            rank: index + 1,
+            nodeIds: r.nodeIds,
+        })),
+        ftsAvailable,
+    };
 };

package/dist/core/search/hybrid-search.d.ts

@@ -32,9 +32,10 @@ export interface HybridSearchResult {
  */
 export declare const mergeWithRRF: (bm25Results: BM25SearchResult[], semanticResults: SemanticSearchResult[], limit?: number) => HybridSearchResult[];
 /**
- * Check if hybrid search is available
- * LadybugDB FTS is always available once the database is initialized.
- * Semantic search is optional - hybrid works with just FTS if embeddings aren't ready.
+ * Check if hybrid search is available.
+ * FTS indexes may be missing on read-only MCP connections (see #1403);
+ * callers should inspect `ftsAvailable` from searchFTSFromLbug for
+ * per-query availability. This helper is a coarse gate only.
  */
 export declare const isHybridSearchReady: () => boolean;
 /**

package/dist/core/search/hybrid-search.js

@@ -79,12 +79,13 @@ export const mergeWithRRF = (bm25Results, semanticResults, limit = 10) => {
     return sorted;
 };
 /**
- * Check if hybrid search is available
- * LadybugDB FTS is always available once the database is initialized.
- * Semantic search is optional - hybrid works with just FTS if embeddings aren't ready.
+ * Check if hybrid search is available.
+ * FTS indexes may be missing on read-only MCP connections (see #1403);
+ * callers should inspect `ftsAvailable` from searchFTSFromLbug for
+ * per-query availability. This helper is a coarse gate only.
  */
 export const isHybridSearchReady = () => {
-    return true; // FTS is always available via LadybugDB when DB is open
+    return true; // FTS is attempted on every query; ftsAvailable signals actual availability
 };
 /**
  * Format hybrid results for LLM consumption
@@ -112,7 +113,7 @@ export const formatHybridResults = (results) => {
  */
 export const hybridSearch = async (query, limit, executeQuery, semanticSearch) => {
     // Use LadybugDB FTS for always-fresh BM25 results
-    const bm25Results = await searchFTSFromLbug(query, limit);
+    const { results: bm25Results } = await searchFTSFromLbug(query, limit);
     const semanticResults = await semanticSearch(executeQuery, query, limit);
     return mergeWithRRF(bm25Results, semanticResults, limit);
 };

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

@@ -818,7 +818,7 @@ export class LocalBackend {
             definitions: definitions.slice(0, 20), // cap standalone definitions
             timing,
             ...(!ftsUsed && {
-                warning: 'FTS extension unavailable - keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.',
+                warning: 'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.',
             }),
         };
     }
@@ -827,15 +827,16 @@ export class LocalBackend {
      */
     async bm25Search(repo, query, limit) {
         const { searchFTSFromLbug } = await import('../../core/search/bm25-index.js');
-        let bm25Results;
+        let ftsResponse;
         try {
-            bm25Results = await searchFTSFromLbug(query, limit, repo.id);
+            ftsResponse = await searchFTSFromLbug(query, limit, repo.id);
         }
         catch (err) {
             logger.error({ err: err.message }, 'GitNexus: BM25/FTS search failed (FTS indexes may not exist) -');
             return { results: [], ftsUsed: false };
         }
-        const ftsUsed = bm25Results.length === 0 || bm25Results[0]?.ftsUsed !== false;
+        const bm25Results = ftsResponse.results;
+        const ftsUsed = ftsResponse.ftsAvailable;
         const results = [];
         for (const bm25Result of bm25Results) {
             const fullPath = bm25Result.filePath;

package/dist/server/api.js

@@ -932,10 +932,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
             const enrich = req.body.enrich !== false; // default true
             const results = await withLbugDb(lbugPath, async () => {
                 let searchResults;
+                let ftsAvailable;
                 if (mode === 'semantic') {
                     const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
                     if (!isEmbedderReady()) {
-                        return [];
+                        return { searchResults: [], ftsAvailable: undefined };
                     }
                     const { semanticSearch: semSearch } = await import('../core/embeddings/embedding-pipeline.js');
                     searchResults = await semSearch(executeQuery, query, limit);
@@ -948,8 +949,9 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     }));
                 }
                 else if (mode === 'bm25') {
-                    searchResults = await searchFTSFromLbug(query, limit);
-                    searchResults = searchResults.map((r, i) => ({
+                    const ftsResponse = await searchFTSFromLbug(query, limit);
+                    ftsAvailable = ftsResponse.ftsAvailable;
+                    searchResults = ftsResponse.results.map((r, i) => ({
                         ...r,
                         rank: i + 1,
                         sources: ['bm25'],
@@ -963,11 +965,13 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         searchResults = await hybridSearch(query, limit, executeQuery, semSearch);
                     }
                     else {
-                        searchResults = await searchFTSFromLbug(query, limit);
+                        const ftsResponse = await searchFTSFromLbug(query, limit);
+                        ftsAvailable = ftsResponse.ftsAvailable;
+                        searchResults = ftsResponse.results;
                     }
                 }
                 if (!enrich)
-                    return searchResults;
+                    return { searchResults, ftsAvailable };
                 // Server-side enrichment: add connections, cluster, processes per result
                 // Uses parameterized queries to prevent Cypher injection via nodeId
                 const validLabel = (label) => NODE_TABLES.includes(label);
@@ -1029,9 +1033,14 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     }
                     return { ...r, ...enrichment };
                 }));
-                return enriched;
+                return { searchResults: enriched, ftsAvailable };
             });
-            res.json({ results });
+            const response = { results: results.searchResults ?? results };
+            if (results.ftsAvailable === false) {
+                response.warning =
+                    'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.';
+            }
+            res.json(response);
         }
         catch (err) {
             res.status(500).json({ error: err.message || 'Search failed' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.4-rc.92",
+  "version": "1.6.4-rc.94",
   "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",