gitnexus 1.6.10-rc.135 → 1.6.10-rc.136

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

@@ -563,6 +563,42 @@ export declare const ensureEmbeddingRowDmlSafe: () => Promise<boolean>;
  * exists or will be created on the next analyze.
  */
 export declare const ensureFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
+export type FtsQueryFailureClass = 'missing-index' | 'missing-table' | 'other';
+/**
+ * Classify a `QUERY_FTS_INDEX` failure so a genuinely-missing index (normal —
+ * this table's FTS index hasn't been built yet) is distinguished from a real
+ * query-time error that would otherwise look identical (#2767), and from the
+ * table itself being missing (schema drift / a corrupted or partial DB — a
+ * much more serious condition than an unbuilt index).
+ *
+ * tri-review Residual-1: this used to be a second, independently-maintained
+ * classifier living in `core/search/bm25-index.ts` (re-exported from there
+ * for backward compatibility), duplicating this function's job for the
+ * IDENTICAL `QUERY_FTS_INDEX` cypher call. `queryFTS` below now uses this
+ * same classifier for its own catch instead of a bare, unanchored
+ * `.includes('does not exist')` check that could not tell "index missing"
+ * from "table missing" apart, and silently swallowed both alike.
+ *
+ * Three real message shapes were confirmed empirically against a live
+ * `CALL QUERY_FTS_INDEX(...)`:
+ * `"Prepare failed: Binder exception: Table <T> doesn't have an index with
+ * name <name>."` — the table exists, only its FTS index is missing (normal,
+ * benign — `missing-index`) — `"Prepare failed: Binder exception: Table <T>
+ * does not exist."` — the TABLE ITSELF is missing (`missing-table`) — and a
+ * `Catalog exception: function QUERY_FTS_INDEX is not defined...` when the
+ * FTS extension isn't loaded at all (`other`; mirrors the confirmed
+ * `DROP_FTS_INDEX` shape in {@link isBenignDropFtsIndexError}'s doc comment).
+ *
+ * Anchored to the exception class (after stripping the optional "Prepare
+ * failed: " wrapper LadybugDB adds for statement-preparation failures),
+ * mirroring `isBenignDropFtsIndexError`'s START-of-message anchor: a bare
+ * substring search would misclassify a genuine, differently-classed error
+ * (e.g. a `Runtime exception` from the FTS parser that echoes the user's
+ * own search text back into its message) as benign whenever that echoed
+ * text happened to contain "does not exist" — silently dropping a real
+ * error, the exact #2767 failure mode this function exists to prevent.
+ */
+export declare const classifyFtsQueryError: (message: string) => FtsQueryFailureClass;
 /**
  * Query a full-text search index
  * @param tableName - The node table name

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

@@ -2721,6 +2721,54 @@ export const ensureFTSIndex = async (tableName, indexName, properties, stemmer =
         throw e;
     }
 };
+/**
+ * Classify a `QUERY_FTS_INDEX` failure so a genuinely-missing index (normal —
+ * this table's FTS index hasn't been built yet) is distinguished from a real
+ * query-time error that would otherwise look identical (#2767), and from the
+ * table itself being missing (schema drift / a corrupted or partial DB — a
+ * much more serious condition than an unbuilt index).
+ *
+ * tri-review Residual-1: this used to be a second, independently-maintained
+ * classifier living in `core/search/bm25-index.ts` (re-exported from there
+ * for backward compatibility), duplicating this function's job for the
+ * IDENTICAL `QUERY_FTS_INDEX` cypher call. `queryFTS` below now uses this
+ * same classifier for its own catch instead of a bare, unanchored
+ * `.includes('does not exist')` check that could not tell "index missing"
+ * from "table missing" apart, and silently swallowed both alike.
+ *
+ * Three real message shapes were confirmed empirically against a live
+ * `CALL QUERY_FTS_INDEX(...)`:
+ * `"Prepare failed: Binder exception: Table <T> doesn't have an index with
+ * name <name>."` — the table exists, only its FTS index is missing (normal,
+ * benign — `missing-index`) — `"Prepare failed: Binder exception: Table <T>
+ * does not exist."` — the TABLE ITSELF is missing (`missing-table`) — and a
+ * `Catalog exception: function QUERY_FTS_INDEX is not defined...` when the
+ * FTS extension isn't loaded at all (`other`; mirrors the confirmed
+ * `DROP_FTS_INDEX` shape in {@link isBenignDropFtsIndexError}'s doc comment).
+ *
+ * Anchored to the exception class (after stripping the optional "Prepare
+ * failed: " wrapper LadybugDB adds for statement-preparation failures),
+ * mirroring `isBenignDropFtsIndexError`'s START-of-message anchor: a bare
+ * substring search would misclassify a genuine, differently-classed error
+ * (e.g. a `Runtime exception` from the FTS parser that echoes the user's
+ * own search text back into its message) as benign whenever that echoed
+ * text happened to contain "does not exist" — silently dropping a real
+ * error, the exact #2767 failure mode this function exists to prevent.
+ */
+export const classifyFtsQueryError = (message) => {
+    const PREPARE_FAILED_PREFIX = 'Prepare failed: ';
+    const body = message.startsWith(PREPARE_FAILED_PREFIX)
+        ? message.slice(PREPARE_FAILED_PREFIX.length)
+        : message;
+    if (!body.startsWith('Binder exception:') && !body.startsWith('Catalog exception:')) {
+        return 'other';
+    }
+    if (body.includes("doesn't have an index"))
+        return 'missing-index';
+    if (body.includes('does not exist'))
+        return 'missing-table';
+    return 'other';
+};
 /**
  * Query a full-text search index
  * @param tableName - The node table name
@@ -2755,8 +2803,13 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
         });
     }
     catch (e) {
-        // Return empty if index doesn't exist yet
-        if (e.message?.includes('does not exist')) {
+        // Return empty only for a genuinely-missing index — the ordinary,
+        // expected case. A missing TABLE (schema drift) or any other real error
+        // rethrows instead of being silently swallowed (tri-review Residual-1 /
+        // NEW-6 — this used to be a bare `.includes('does not exist')` check
+        // that could not tell the two apart).
+        const message = e instanceof Error ? e.message : String(e);
+        if (classifyFtsQueryError(message) === 'missing-index') {
             return [];
         }
         throw e;

package/dist/core/run-analyze.js

@@ -603,6 +603,44 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                     'if that also fails, verify FTS extension availability via `gitnexus doctor`.');
             }
             await ensureGitNexusIgnored(repoPath);
+            // #2767: stamp ONLY capabilities.fts so a long-lived MCP session's
+            // ensureInitialized() has an explicit, correctly-scoped signal that FTS
+            // changed — indexedAt/lastCommit/runnerIdentity/stats are copied through
+            // untouched (see the "must not claim a new analyzer identity" comment
+            // below). capabilities is forensic/no-programmatic-readers-until-now, so
+            // graph/vectorSearch are backfilled with conservative, honest defaults
+            // when a legacy meta.json predates this field entirely — repair-fts
+            // never touched them and cannot claim a capability it did not verify.
+            // Best-effort: a write failure must not turn an already-successful FTS
+            // rebuild into a reported repair failure.
+            try {
+                // Re-read the on-disk meta immediately before writing, rather than
+                // reusing `existingMeta` (captured before the FTS rebuild ran, which
+                // can span real wall-clock time). Another writer to this same
+                // gitnexus.json in the interim — e.g. the HTTP server's background
+                // embedding-checkpoint job — must not have its update silently
+                // reverted by this stamp overwriting a stale snapshot. Falls back to
+                // `existingMeta` only if the file became unreadable in that window.
+                const latestMeta = (await loadMeta(metaDir)) ?? existingMeta;
+                await saveMeta(metaDir, {
+                    ...latestMeta,
+                    capabilities: {
+                        graph: latestMeta.capabilities?.graph ?? {
+                            provider: 'ladybugdb',
+                            status: 'available',
+                        },
+                        fts: { provider: 'ladybugdb-fts', status: 'available' },
+                        vectorSearch: latestMeta.capabilities?.vectorSearch ?? {
+                            provider: 'exact-scan',
+                            status: 'unavailable',
+                            exactScanLimit: 0,
+                        },
+                    },
+                });
+            }
+            catch (err) {
+                log(`FTS capability stamp write failed (non-critical, repair itself succeeded${err instanceof Error ? `: ${err.message}` : ''}); continuing.`);
+            }
             progress('fts', 90, 'Search indexes ready');
             progress('done', 100, 'Done');
             return {

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

@@ -14,6 +14,17 @@ export interface FTSSearchResponse {
     results: BM25SearchResult[];
     /** True when at least one FTS index query succeeded (index exists). */
     ftsAvailable: boolean;
+    /**
+     * Redacted (via {@link redactPaths}) message(s) from per-table
+     * `QUERY_FTS_INDEX` calls that failed for a reason OTHER than "index
+     * doesn't exist" (#2767) — a real query/connection error was previously
+     * indistinguishable from a genuinely-missing index. Populated whenever ANY
+     * table hit a non-benign error, regardless of whether other tables
+     * succeeded, so a caller can always log it; whether to also surface it in
+     * a client-facing warning is a caller decision (see `LocalBackend.query()`,
+     * which only does so when every table failed).
+     */
+    nonBenignErrors?: string[];
 }
 /**
  * Search using LadybugDB's built-in FTS (always fresh, reads from disk)

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

@@ -4,14 +4,23 @@
  * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
  * Always reads from the database (no cached state to drift).
  */
-import { queryFTS } from '../lbug/lbug-adapter.js';
+// tri-review Residual-1: `classifyFtsQueryError` now lives in lbug-adapter.ts
+// (see its doc comment) so `queryFTS`'s own catch can share the SAME
+// classifier instead of maintaining a second, independently-drifting copy
+// for the identical `QUERY_FTS_INDEX` cypher call.
+import { queryFTS, classifyFtsQueryError } from '../lbug/lbug-adapter.js';
 import { normalizeFtsText } from '../lbug/csv-generator.js';
+import { getExtensionCapabilities } from '../lbug/extension-loader.js';
+import { redactPaths } from './fts-indexes.js';
 import { FTS_INDEXES } from './fts-schema.js';
 import { applyCjkSegmentationIfEnabled, MAX_CJK_SEGMENTATION_QUERY_LENGTH, } from './cjk-segmentation.js';
 /**
  * Execute a single FTS query via a custom executor (for MCP connection pool).
- * Returns `null` when the query fails (e.g. FTS index does not exist) so the
- * caller can distinguish "zero matches" from "index missing".
+ * Returns a benign failure when the query fails because the index doesn't
+ * exist (the normal, expected case), and a non-benign failure with the
+ * captured message for any other error, so the caller can distinguish "zero
+ * matches", "index missing", and "a real error occurred" instead of
+ * collapsing the latter two into the same silent `null`.
  */
 async function queryFTSViaExecutor(executor, tableName, indexName, query, limit) {
     const cypher = `
@@ -22,18 +31,21 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
   `;
     try {
         const rows = await executor(cypher, { query });
-        return rows.map((row) => {
-            const node = row.node || row[0] || {};
-            const score = row.score ?? row[1] ?? 0;
-            return {
-                filePath: node.filePath || '',
-                score: typeof score === 'number' ? score : parseFloat(score) || 0,
-                nodeId: node.nodeId || node.id || '',
-            };
-        });
+        return {
+            rows: rows.map((row) => {
+                const node = row.node || row[0] || {};
+                const score = row.score ?? row[1] ?? 0;
+                return {
+                    filePath: node.filePath || '',
+                    score: typeof score === 'number' ? score : parseFloat(score) || 0,
+                    nodeId: node.nodeId || node.id || '',
+                };
+            }),
+        };
     }
-    catch {
-        return null;
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return { benign: classifyFtsQueryError(message) === 'missing-index', message };
     }
 }
 /**
@@ -65,7 +77,23 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         : query);
     const resultsByIndex = [];
     let queriesSucceeded = 0;
-    if (repoId) {
+    const nonBenignErrors = [];
+    const ftsExtension = getExtensionCapabilities().find((c) => c.name === 'fts');
+    if (ftsExtension && !ftsExtension.loaded) {
+        // tri-review NEW-4 (applies to BOTH the MCP pool path and the CLI/pipeline
+        // path — a /simplify altitude pass caught the original repoId-only guard
+        // letting the CLI branch surface spurious "non-benign" errors for this
+        // exact expected state, which the pool branch correctly stayed silent on):
+        // extension-unavailable is an expected, already-diagnosed degraded-capability
+        // state (#2374/#2658), not a per-table query error — every configured table
+        // would throw the identical "function not defined" shape, which
+        // classifyFtsQueryError correctly refuses to call benign "missing-index"
+        // (it's a different, more serious condition). Skip the N redundant
+        // QUERY_FTS_INDEX round-trips and N nonBenignErrors entries; ftsAvailable
+        // stays false and ftsDegradedWarning() already reports this state
+        // accurately from the same extension-capabilities registry.
+    }
+    else if (repoId) {
         // Use MCP connection pool via dynamic import
         // IMPORTANT: FTS queries run sequentially to avoid connection contention.
         // The MCP pool supports multiple connections, but FTS is best run serially.
@@ -73,23 +101,31 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         const { executeParameterized } = poolMod;
         const executor = (cypher, params) => executeParameterized(repoId, cypher, params);
         for (const { table, indexName } of FTS_INDEXES) {
-            const result = await queryFTSViaExecutor(executor, table, indexName, searchQuery, limit);
-            if (result !== null) {
+            const outcome = await queryFTSViaExecutor(executor, table, indexName, searchQuery, limit);
+            if (outcome.rows) {
                 queriesSucceeded++;
-                resultsByIndex.push(result);
+                resultsByIndex.push(outcome.rows);
+            }
+            else if (!outcome.benign) {
+                nonBenignErrors.push(redactPaths(outcome.message ?? 'Unknown FTS query error'));
             }
         }
     }
     else {
         // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
+        // tri-review Residual-1: `queryFTS` itself only swallows a genuinely-missing
+        // index (via the SAME classifyFtsQueryError this module re-exports); a
+        // missing-table or real query error rethrows here — track it the same way
+        // the MCP pool path does instead of a bare `catch {}` that dropped it.
         for (const { table, indexName } of FTS_INDEXES) {
             try {
                 const result = await queryFTS(table, indexName, searchQuery, limit, false);
                 queriesSucceeded++;
                 resultsByIndex.push(result);
             }
-            catch {
-                // FTS index may not exist — count as failed
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                nonBenignErrors.push(redactPaths(message));
             }
         }
     }
@@ -129,5 +165,6 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
             nodeIds: r.nodeIds,
         })),
         ftsAvailable,
+        ...(nonBenignErrors.length > 0 && { nonBenignErrors }),
     };
 };

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

@@ -1,10 +1,59 @@
+/**
+ * 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).
+ *
+ * tri-review Residual-3: every real message shape observed from LadybugDB
+ * wraps the path in single quotes (`Failed to load library '<path>': ...`),
+ * so a QUOTED path is redacted first, consuming through its closing quote —
+ * spaces included (e.g. a Windows username like `alice smith`). The original
+ * unquoted-stop-at-first-whitespace pattern still runs afterward as a
+ * fallback for the rare case of a path appearing without quotes; that path's
+ * own known limitation (partial redaction if it itself contains a space) is
+ * unchanged, but is no longer the ONLY path this function knows how to redact.
+ */
+export declare const redactPaths: (reason: string) => string;
+/**
+ * Resolved-repo/index identity a caller can attach to a degraded-FTS warning
+ * (#2767) so a reader can tell whether *this* session even resolved the index
+ * they expect, instead of guessing between a stale connection, a different
+ * repo/branch, or a genuine build failure. MCP-`query`-only today — never
+ * forwarded into the HTTP `/api/search` response (see that call site).
+ */
+export interface FtsWarningContext {
+    repoName: string;
+    branch?: string;
+    indexedAt?: string;
+    /** Already redacted by the caller (e.g. via {@link redactPaths} on a captured query error). */
+    lastErrorRedacted?: string;
+}
 /**
  * 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.
+ *
+ * `context`, when supplied, appends the resolved repo/branch/indexed-at (and
+ * redacted query-error detail, if captured) so a CLI/MCP mismatch — or a real
+ * query error masquerading as "indexes missing" — is visible in the warning
+ * text itself (#2767). Optional and additive: omitting it reproduces today's
+ * exact message.
+ */
+export declare const ftsDegradedWarning: (context?: FtsWarningContext) => string;
+/**
+ * Warning for when the FTS extension is loaded and indexes exist, but every
+ * configured table's query failed for a real, non-benign reason (timeout,
+ * connection reset, native fault) — as opposed to `ftsDegradedWarning`'s
+ * missing-index case. `--repair-fts` will not fix a query/connection error,
+ * so this deliberately does NOT suggest it: reusing the missing-index
+ * message here would reproduce, for this cause, the exact misleading
+ * "run --repair-fts" guidance #2767 itself was about (tri-review NEW-1).
  */
-export declare const ftsDegradedWarning: () => string;
+export declare const ftsQueryFailedWarning: (context: FtsWarningContext) => 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

@@ -10,15 +10,43 @@ import { FTS_INDEXES } from './fts-schema.js';
  * 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).
+ *
+ * tri-review Residual-3: every real message shape observed from LadybugDB
+ * wraps the path in single quotes (`Failed to load library '<path>': ...`),
+ * so a QUOTED path is redacted first, consuming through its closing quote —
+ * spaces included (e.g. a Windows username like `alice smith`). The original
+ * unquoted-stop-at-first-whitespace pattern still runs afterward as a
+ * fallback for the rare case of a path appearing without quotes; that path's
+ * own known limitation (partial redaction if it itself contains a space) is
+ * unchanged, but is no longer the ONLY path this function knows how to redact.
  */
-const redactPaths = (reason) => reason.replace(/(?:[A-Za-z]:\\|\/)[^\s'"]+/g, '<path>');
+export const redactPaths = (reason) => reason
+    .replace(/'((?:[A-Za-z]:\\|\/)[^']*)'/g, "'<path>'")
+    .replace(/(?:[A-Za-z]:\\|\/)[^\s'"]+/g, '<path>');
+/** The repo/branch/indexed-at portion shared by both warning-context formatters below. */
+const formatResolvedSuffix = (context) => {
+    const branchSuffix = context.branch ? `/branch:${context.branch}` : '';
+    const indexedSuffix = context.indexedAt ? `, indexed ${context.indexedAt}` : '';
+    return `${context.repoName}${branchSuffix}${indexedSuffix}`;
+};
+const formatWarningContext = (context) => {
+    const errorSuffix = context.lastErrorRedacted ? `; last error: ${context.lastErrorRedacted}` : '';
+    return ` (resolved: ${formatResolvedSuffix(context)}${errorSuffix})`;
+};
 /**
  * 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.
+ *
+ * `context`, when supplied, appends the resolved repo/branch/indexed-at (and
+ * redacted query-error detail, if captured) so a CLI/MCP mismatch — or a real
+ * query error masquerading as "indexes missing" — is visible in the warning
+ * text itself (#2767). Optional and additive: omitting it reproduces today's
+ * exact message.
  */
-export const ftsDegradedWarning = () => {
+export const ftsDegradedWarning = (context) => {
+    const suffix = context ? formatWarningContext(context) : '';
     const fts = getExtensionCapabilities().find((c) => c.name === 'fts');
     if (fts && !fts.loaded) {
         const reason = fts.reason ? redactPaths(fts.reason).replace(/\.$/, '') : undefined;
@@ -33,10 +61,27 @@ export const ftsDegradedWarning = () => {
             : '. 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})` : '') +
-            tail);
+            tail +
+            suffix);
     }
-    return 'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.';
+    return ('FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts ' +
+        '(or gitnexus analyze --force) to rebuild indexes.' +
+        suffix);
 };
+/**
+ * Warning for when the FTS extension is loaded and indexes exist, but every
+ * configured table's query failed for a real, non-benign reason (timeout,
+ * connection reset, native fault) — as opposed to `ftsDegradedWarning`'s
+ * missing-index case. `--repair-fts` will not fix a query/connection error,
+ * so this deliberately does NOT suggest it: reusing the missing-index
+ * message here would reproduce, for this cause, the exact misleading
+ * "run --repair-fts" guidance #2767 itself was about (tri-review NEW-1).
+ */
+export const ftsQueryFailedWarning = (context) => 'FTS keyword search failed — every configured index query returned an error' +
+    (context.lastErrorRedacted ? ` (${context.lastErrorRedacted})` : '') +
+    '; results do not include keyword matches. This is not a missing-index ' +
+    'condition — see server logs for details.' +
+    ` (resolved: ${formatResolvedSuffix(context)})`;
 // 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.d.ts

@@ -156,8 +156,9 @@ export declare class LocalBackend {
     private reinitPromises;
     private lastStalenessCheck;
     private toolStalenessCache;
-    private lastObservedIndexedAt;
-    private lastObservedDbIdentity;
+    private lastObservedPoolState;
+    /** Merge-patch one poolKey's observed state, preserving fields not passed. */
+    private setObservedState;
     private groupToolSvc;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by

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

@@ -28,7 +28,7 @@ import { rankExactEmbeddingRows, } from '../../core/embeddings/exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
 import { getExactScanLimit } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
-import { ftsDegradedWarning } from '../../core/search/fts-indexes.js';
+import { ftsDegradedWarning, ftsQueryFailedWarning } 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';
@@ -525,17 +525,30 @@ export class LocalBackend {
     // lastCommit values, so a repoPath key would serve one handle's freshness for
     // the other; lbugPath is unique per flat/branch index.
     toolStalenessCache = new Map();
-    // Last meta.indexedAt observed for an open pool, keyed by lbugPath. Keyed by
-    // pool (not stored on the handle) because branch handles are produced fresh
-    // by applyBranchScope on every resolveRepo call, so mutating the handle would
-    // not persist across calls and the staleness check would reinit forever
-    // (#2106).
-    lastObservedIndexedAt = new Map();
-    // #2614 F1: file identity of the lbug the pool last opened. An atomic swap or
-    // an in-place incremental changes the inode; reiniting on that reinit-covers
-    // the window where meta.indexedAt hasn't caught up (and the incremental case),
-    // so a rebuilt index is never served stale even when the stamp looks current.
-    lastObservedDbIdentity = new Map();
+    // tri-review Residual-2: consolidates what were three parallel per-poolKey
+    // Maps (lastObservedIndexedAt / lastObservedDbIdentity / lastObservedFtsStatus)
+    // touched in lockstep at every call site below — one Map, one delete, one
+    // shape. Keyed by lbugPath (not stored on the repo handle) because branch
+    // handles are produced fresh by applyBranchScope on every resolveRepo call,
+    // so mutating the handle would not persist across calls and the staleness
+    // check would reinit forever (#2106).
+    //   - `indexedAt`: last meta.indexedAt observed for an open pool.
+    //   - `dbIdentity`: file identity of the lbug the pool last opened (#2614 F1)
+    //     — an atomic swap or in-place incremental changes the inode; reiniting
+    //     on that covers the window where meta.indexedAt hasn't caught up (and
+    //     the incremental case), so a rebuilt index is never served stale even
+    //     when the stamp looks current.
+    //   - `ftsStatus`: last meta.capabilities.fts.status observed (#2767).
+    //     `--repair-fts` intentionally never restamps `indexedAt` (it doesn't
+    //     regenerate the graph), so this is the dedicated signal a warm session
+    //     uses to notice a repair — independent of the file-identity heuristic,
+    //     which the repair path also triggers but only incidentally.
+    lastObservedPoolState = new Map();
+    /** Merge-patch one poolKey's observed state, preserving fields not passed. */
+    setObservedState(poolKey, patch) {
+        const current = this.lastObservedPoolState.get(poolKey) ?? { dbIdentity: null };
+        this.lastObservedPoolState.set(poolKey, { ...current, ...patch });
+    }
     groupToolSvc = null;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by
@@ -821,8 +834,7 @@ export class LocalBackend {
             this.initializedRepos.delete(key);
             this.lastStalenessCheck.delete(key);
             this.toolStalenessCache.delete(key);
-            this.lastObservedIndexedAt.delete(key);
-            this.lastObservedDbIdentity.delete(key);
+            this.lastObservedPoolState.delete(key);
             this.reinitPromises.delete(key);
             closeLbug(key).catch(() => { });
         }
@@ -1182,18 +1194,28 @@ export class LocalBackend {
                 // Reading the flat meta for a branch handle would compare the branch
                 // index's indexedAt against the primary's and thrash the pool (#2106).
                 const meta = await loadMeta(path.dirname(repo.lbugPath));
+                const observedState = this.lastObservedPoolState.get(poolKey);
                 // Compare against the last indexedAt OBSERVED for this pool (keyed by
                 // lbugPath), not the handle's — branch handles are fresh spreads so a
                 // handle mutation would not persist and would reinit on every check.
-                const observed = this.lastObservedIndexedAt.get(poolKey) ?? repo.indexedAt;
+                const observed = observedState?.indexedAt ?? repo.indexedAt;
                 const stampChanged = !!meta?.indexedAt && meta.indexedAt !== observed;
                 // #2614 F1: also reinit on a file-identity change. An atomic swap (or an
                 // in-place incremental) changes the lbug inode; keying only on
                 // meta.indexedAt let a reader that reinited inside the pre-swap window
                 // latch on the old inode forever (its stamp already == meta.indexedAt).
                 const currentIdentity = await statDbIdentity(repo.lbugPath);
-                const identityChanged = dbIdentityChanged(this.lastObservedDbIdentity.get(poolKey) ?? null, currentIdentity);
-                if (stampChanged || identityChanged) {
+                const identityChanged = dbIdentityChanged(observedState?.dbIdentity ?? null, currentIdentity);
+                // #2767: `--repair-fts` intentionally never restamps `indexedAt` (it
+                // doesn't regenerate the graph), so `stampChanged` alone can't notice
+                // a repair. `capabilities.fts.status` is the field repair-fts DOES
+                // write, so a change there is a third, independent reinit trigger —
+                // sibling to stampChanged/identityChanged, not a replacement for them
+                // (identityChanged still catches an in-place mutation even if the
+                // caps stamp were somehow missed).
+                const ftsStatus = meta?.capabilities?.fts?.status;
+                const ftsCapsChanged = observedState?.ftsStatus !== ftsStatus;
+                if (stampChanged || identityChanged || ftsCapsChanged) {
                     // Index was rebuilt/swapped — DELEGATE the close/reopen to the pool's
                     // initLbug, which refuses to evict (and close the shared Database)
                     // while a query is in flight (its checkedOut>0 guard). Calling
@@ -1202,18 +1224,24 @@ export class LocalBackend {
                     // reinitPromises to serialize concurrent detectors.
                     const reinit = (async () => {
                         try {
-                            // Advance the observed stamp regardless: a stamp change with an
-                            // unchanged file must not re-trigger on every check.
-                            if (meta?.indexedAt)
-                                this.lastObservedIndexedAt.set(poolKey, meta.indexedAt);
                             const reopened = await initLbug(poolKey, repo.lbugPath);
+                            // tri-review NEW-7: advance the observed stamp/caps watermarks
+                            // only AFTER initLbug completes, not before calling it — still
+                            // regardless of `reopened` true/false (a stamp/caps change with
+                            // an unchanged file must not re-trigger on every check), but if
+                            // initLbug THROWS the watermark must stay at its old value so
+                            // the next staleness check retries, instead of a failed reinit
+                            // silently latching as "already applied" and never trying again.
+                            const patch = { ftsStatus };
+                            if (meta?.indexedAt)
+                                patch.indexedAt = meta.indexedAt;
                             // Advance the observed IDENTITY only when the pool actually rolled
                             // over. If a query was in flight, initLbug served the current
                             // handle and returned false; leaving the identity divergent
                             // re-triggers the reopen on a later idle check instead of latching.
-                            if (reopened) {
-                                this.lastObservedDbIdentity.set(poolKey, await statDbIdentity(repo.lbugPath));
-                            }
+                            if (reopened)
+                                patch.dbIdentity = await statDbIdentity(repo.lbugPath);
+                            this.setObservedState(poolKey, patch);
                         }
                         finally {
                             this.reinitPromises.delete(poolKey);
@@ -1233,8 +1261,18 @@ export class LocalBackend {
         try {
             await initLbug(poolKey, repo.lbugPath);
             this.initializedRepos.add(poolKey);
-            this.lastObservedIndexedAt.set(poolKey, repo.indexedAt);
-            this.lastObservedDbIdentity.set(poolKey, await statDbIdentity(repo.lbugPath));
+            // #2767: ftsStatus is deliberately left unset (undefined) here rather
+            // than issuing an extra loadMeta read — every tool call already routes
+            // through ensureInitialized, so an extra per-cold-init read adds up,
+            // and the cost of skipping it is negligible: at most one redundant
+            // initLbug call on the first warm check (initLbug itself no-ops
+            // cheaply via a single fs.stat when the file identity is actually
+            // unchanged, per pool-adapter.ts's own "unchanged → reuse" guard), not
+            // a real reopen.
+            this.setObservedState(poolKey, {
+                indexedAt: repo.indexedAt,
+                dbIdentity: await statDbIdentity(repo.lbugPath),
+            });
         }
         catch (err) {
             // If lock error, mark as not initialized so next call retries
@@ -1628,6 +1666,21 @@ export class LocalBackend {
         // unavailable the search helper may return an unexpected shape.
         const bm25Results = bm25SearchResult?.results ?? [];
         const ftsUsed = bm25SearchResult?.ftsUsed ?? false;
+        // #2767: log every non-benign per-table FTS query error server-side,
+        // regardless of whether OTHER tables succeeded — previously a real error
+        // on N-1 of N tables while one succeeded left zero diagnostic trail.
+        const ftsQueryErrors = bm25SearchResult?.nonBenignErrors;
+        if (ftsQueryErrors) {
+            // tri-review NEW-5: these strings are already classified non-benign by
+            // classifyFtsQueryError — do NOT route them through logQueryError,
+            // whose own broader, unanchored isBenignMissingTableError regex (any
+            // "does not exist" substring, anywhere) could disagree and silently
+            // demote an already-flagged real error to debug, undercutting the
+            // severity signal this classification exists to preserve.
+            for (const err of ftsQueryErrors) {
+                logger.warn({ context: 'query:fts-search', err }, 'GitNexus query failed (degraded)');
+            }
+        }
         // Merge via reciprocal rank fusion
         timer.start('merge');
         const scoreMap = new Map();
@@ -1868,7 +1921,34 @@ export class LocalBackend {
         // path, leaving the success-path response shape byte-identical.
         const warnings = [];
         if (!ftsUsed) {
-            warnings.push(ftsDegradedWarning());
+            // #2767: attach what THIS session resolved (repo/branch/indexed-at) so a
+            // CLI/MCP mismatch is visible in the warning itself rather than requiring
+            // a separate debugging round-trip. tri-review NEW-3: `indexedAt` reads
+            // from `lastObservedPoolState` (kept current by ensureInitialized's
+            // staleness check, including a same-call reinit) rather than the `repo`
+            // handle resolved before that check ran — a warm backend that just
+            // reopened against a newer on-disk index must not warn with stale
+            // metadata. No extra I/O: the map is already maintained per-request.
+            const warningContext = {
+                repoName: repo.name,
+                branch: repo.branch,
+                indexedAt: this.lastObservedPoolState.get(repo.lbugPath)?.indexedAt ?? repo.indexedAt,
+            };
+            // tri-review NEW-1: every table failing for a REAL error (timeout,
+            // connection reset) is not a missing-index condition — `ftsDegradedWarning`'s
+            // "run --repair-fts" headline won't fix it. Route to a dedicated message
+            // instead of burying the real cause as a trailing suffix on bad advice.
+            warnings.push(ftsQueryErrors
+                ? ftsQueryFailedWarning({ ...warningContext, lastErrorRedacted: ftsQueryErrors[0] })
+                : ftsDegradedWarning(warningContext));
+        }
+        else if (ftsQueryErrors) {
+            // #2767: at least one FTS table succeeded (ftsUsed=true) but another
+            // hit a real, non-benign error — results may be silently missing
+            // matches from that table with no signal, the same "partial success"
+            // shape the enrichmentDegraded branch below already surfaces. Mirror
+            // that convention instead of only logging server-side.
+            warnings.push(`FTS keyword search partially failed — ${ftsQueryErrors.length} of the configured indexes hit a query error and were skipped; results may be missing matches from those node types (see server logs).`);
         }
         // #2331: a CJK query against a server process resolving
         // GITNEXUS_FTS_CJK_SEGMENTATION to 'none' silently misses sub-phrase
@@ -1935,13 +2015,17 @@ export class LocalBackend {
         if (enrichmentDegraded) {
             warnings.push('Symbol enrichment partially failed — some process/cohesion/content data may be missing from these results (see server logs).');
         }
+        // #2767: a partial FTS failure (some tables ok, one or more real errors)
+        // is as much a "results may be incomplete" signal as enrichmentDegraded —
+        // flag it the same way rather than only via the warning string.
+        const ftsPartial = ftsUsed && !!ftsQueryErrors;
         return {
             processes,
             process_symbols: dedupedSymbols,
             definitions: definitions.slice(0, 20), // cap standalone definitions
             timing,
             ...(warnings.length > 0 && { warning: warnings.join(' ') }),
-            ...(enrichmentDegraded && { partial: true }),
+            ...((enrichmentDegraded || ftsPartial) && { partial: true }),
         };
     }
     /**
@@ -1974,6 +2058,7 @@ export class LocalBackend {
         // could be undefined when the FTS extension is unavailable in the MCP process.
         const bm25Results = ftsResponse?.results ?? [];
         const ftsUsed = ftsResponse?.ftsAvailable ?? false;
+        const nonBenignErrors = ftsResponse?.nonBenignErrors;
         const results = [];
         for (const bm25Result of bm25Results) {
             const fullPath = bm25Result.filePath;
@@ -2036,7 +2121,7 @@ export class LocalBackend {
                 });
             }
         }
-        return { results, ftsUsed };
+        return { results, ftsUsed, ...(nonBenignErrors && { nonBenignErrors }) };
     }
     /**
      * Semantic vector search helper

package/dist/server/api.js

@@ -1558,8 +1558,16 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         }
                         const forceReembedNodeIds = new Set(priorCheckpoint?.pendingNodeIds ?? []);
                         const saveEmbeddingCheckpoint = async (checkpoint, pendingNodeIds) => {
+                            // tri-review NEW-2: re-read immediately before writing (mirrors
+                            // the pattern in run-analyze.ts's --repair-fts stamp) instead of
+                            // spreading the stale `embeddingMeta` snapshot captured once at
+                            // job start. This job can run up to EMBED_TIMEOUT_MS (30 min);
+                            // without a fresh read, a concurrent writer's update (e.g. a
+                            // --repair-fts capability stamp) would be silently reverted on
+                            // every checkpoint save for the job's whole lifetime.
+                            const latestMeta = (await loadMeta(entry.storagePath)) ?? embeddingMeta;
                             embeddingMeta = {
-                                ...embeddingMeta,
+                                ...latestMeta,
                                 embeddingCheckpoint: {
                                     at: new Date().toISOString(),
                                     ...checkpoint,
@@ -1610,7 +1618,9 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         // handles this during process exit, but the server keeps the
                         // connection open for other routes — a CHECKPOINT is enough.
                         await flushWAL();
-                        embeddingMeta = { ...embeddingMeta, embeddingCheckpoint: undefined };
+                        // Same re-read-before-write reasoning as saveEmbeddingCheckpoint above.
+                        const finalMeta = (await loadMeta(entry.storagePath)) ?? embeddingMeta;
+                        embeddingMeta = { ...finalMeta, embeddingCheckpoint: undefined };
                         await saveMeta(entry.storagePath, embeddingMeta);
                     });
                     // Don't overwrite 'failed' if the job was cancelled while the pipeline was running

package/dist/storage/repo-manager.d.ts

@@ -155,9 +155,12 @@ export interface RepoMeta {
      * the meta literal in run-analyze.ts — typed here so the stamp site is
      * compile-checked; tri-review 4669518496 P1/U3: `vectorSearch.status`
      * must never claim 'vector-index' unless the run verified or recreated
-     * the HNSW index). Forensic today — no programmatic readers (`doctor`
-     * prints platform-derived capabilities, query routing never consults
-     * meta). The status unions mirror `CapabilityStatus` /
+     * the HNSW index). `fts.status` gained its first programmatic reader in
+     * #2767: `LocalBackend.ensureInitialized()` compares it against the
+     * warm connection pool's last-observed value as the dedicated signal
+     * that `--repair-fts` changed FTS availability (`doctor` still prints
+     * platform-derived capabilities separately; `graph`/`vectorSearch` remain
+     * forensic-only). The status unions mirror `CapabilityStatus` /
      * `SemanticSearchMode` in core/platform/capabilities.ts; inlined to keep
      * storage/ free of a core/ type dependency.
      */

package/package.json

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