gitnexus 1.6.3-rc.8 → 1.6.3

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

@@ -110,6 +110,17 @@ let conn = null;
 let currentDbPath = null;
 let ftsLoaded = false;
 let vectorExtensionLoaded = false;
+/**
+ * In-process cache of FTS indexes that have been ensured against the current
+ * connection. Prevents repeated `CALL CREATE_FTS_INDEX` round-trips inside a
+ * single CLI/MCP session — the first call to `ensureFTSIndex` for a given
+ * `(tableName, indexName)` pays the LadybugDB cost (~440 ms even when the
+ * index already exists on disk), subsequent calls are a Set lookup. Cleared
+ * by `closeLbug` so a re-init starts fresh.
+ *
+ * Key format: `${tableName}:${indexName}`.
+ */
+const ensuredFTSIndexes = new Set();
 /**
  * Check if an error indicates a missing column or table (schema-level problem)
  * rather than a transient/connection error. Used for legacy DB fallback logic.
@@ -935,6 +946,7 @@ export const closeLbug = async () => {
     currentDbPath = null;
     ftsLoaded = false;
     vectorExtensionLoaded = false;
+    ensuredFTSIndexes.clear();
 };
 export const isLbugReady = () => conn !== null && db !== null;
 /**
@@ -1014,36 +1026,50 @@ export const getEmbeddingTableName = () => EMBEDDING_TABLE_NAME;
 // ============================================================================
 /**
  * Load the FTS extension (required before using FTS functions).
- * Safe to call multiple times — tracks loaded state via module-level ftsLoaded.
+ *
+ * Safe to call multiple times — when invoked without arguments, tracks loaded
+ * state via module-level `ftsLoaded`. When invoked with an explicit
+ * connection, loads on that connection and returns whether the load
+ * succeeded — letting callers (e.g. the pool adapter) track their own state.
+ *
+ * Tries `LOAD EXTENSION fts` first so previously-cached installs skip the
+ * network entirely; falls back to `INSTALL` + `LOAD` only when the extension
+ * hasn't been cached yet.
  */
-export const loadFTSExtension = async () => {
-    if (ftsLoaded)
-        return;
-    if (!conn) {
+export const loadFTSExtension = async (targetConn) => {
+    const useModuleState = targetConn === undefined;
+    if (useModuleState && ftsLoaded)
+        return true;
+    const c = targetConn ?? conn;
+    if (!c) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
+    const markLoaded = () => {
+        if (useModuleState)
+            ftsLoaded = true;
+        return true;
+    };
     try {
         // Try loading locally first (no network required)
-        await conn.query('LOAD EXTENSION fts');
-        ftsLoaded = true;
+        await c.query('LOAD EXTENSION fts');
+        return markLoaded();
     }
     catch {
         // Fall back to install + load (requires network)
         try {
-            await conn.query('INSTALL fts');
-            await conn.query('LOAD EXTENSION fts');
-            ftsLoaded = true;
+            await c.query('INSTALL fts');
+            await c.query('LOAD EXTENSION fts');
+            return markLoaded();
         }
         catch (err) {
             const msg = err?.message || '';
             if (msg.includes('already loaded') ||
                 msg.includes('already installed') ||
                 msg.includes('already exists')) {
-                ftsLoaded = true;
-            }
-            else {
-                console.error('GitNexus: FTS extension load failed:', msg);
+                return markLoaded();
             }
+            console.error('GitNexus: FTS extension load failed:', msg);
+            return false;
         }
     }
 };
@@ -1097,6 +1123,24 @@ export const createFTSIndex = async (tableName, indexName, properties, stemmer =
         }
     }
 };
+/**
+ * Lazy-create an FTS index, caching the fact in-process.
+ *
+ * Used by `queryFTS` so that `analyze` doesn't pay the ~440 ms × 5 fixed
+ * LadybugDB cost up-front (it dominates analyze on small repos). Instead,
+ * the cost is moved to the first `query`/`context` call in a session,
+ * where it's amortised across many lookups.
+ *
+ * Safe to call repeatedly — the in-process Set guarantees only the first
+ * call hits LadybugDB. `closeLbug` clears the cache so re-init starts fresh.
+ */
+export const ensureFTSIndex = async (tableName, indexName, properties, stemmer = 'porter') => {
+    const key = `${tableName}:${indexName}`;
+    if (ensuredFTSIndexes.has(key))
+        return;
+    await createFTSIndex(tableName, indexName, properties, stemmer);
+    ensuredFTSIndexes.add(key);
+};
 /**
  * Query a full-text search index
  * @param tableName - The node table name

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

@@ -15,6 +15,22 @@
  * from the same Database is the officially supported concurrency pattern.
  */
 import lbug from '@ladybugdb/core';
+/**
+ * Listeners notified when a pool entry is torn down (LRU eviction, idle
+ * timeout, explicit close). Used by upper layers (e.g. the BM25 search
+ * module) to invalidate per-repo caches that must not outlive the pool
+ * entry that produced them.
+ *
+ * Listeners run synchronously inside `closeOne` after the pool entry has
+ * been removed; throwing listeners are isolated so one bad listener does
+ * not prevent others from firing or break teardown.
+ */
+type PoolCloseListener = (repoId: string) => void;
+/**
+ * Subscribe to pool-close events. Returns a disposer that removes the
+ * listener (handy for tests).
+ */
+export declare function addPoolCloseListener(listener: PoolCloseListener): () => void;
 /** Saved real stdout/stderr write — used to silence native module output without race conditions */
 export declare const realStdoutWrite: any;
 export declare const realStderrWrite: any;
@@ -74,3 +90,4 @@ export declare const isLbugReady: (repoId: string) => boolean;
 export declare const CYPHER_WRITE_RE: RegExp;
 /** Check if a Cypher query contains write operations */
 export declare function isWriteQuery(query: string): boolean;
+export {};

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

@@ -16,7 +16,19 @@
  */
 import fs from 'fs/promises';
 import lbug from '@ladybugdb/core';
+import { loadFTSExtension } from './lbug-adapter.js';
 const pool = new Map();
+const poolCloseListeners = new Set();
+/**
+ * Subscribe to pool-close events. Returns a disposer that removes the
+ * listener (handy for tests).
+ */
+export function addPoolCloseListener(listener) {
+    poolCloseListeners.add(listener);
+    return () => {
+        poolCloseListeners.delete(listener);
+    };
+}
 const dbCache = new Map();
 /** Max repos in the pool (LRU eviction) */
 const MAX_POOL_SIZE = 5;
@@ -119,6 +131,16 @@ function closeOne(repoId) {
         }
     }
     pool.delete(repoId);
+    // Notify listeners AFTER the pool entry is gone so any cache-invalidation
+    // they perform is consistent with `isLbugReady(repoId) === false`.
+    for (const listener of poolCloseListeners) {
+        try {
+            listener(repoId);
+        }
+        catch {
+            // Isolate listener failures — teardown must complete.
+        }
+    }
 }
 /**
  * Create a new Connection from a repo's Database.
@@ -263,13 +285,7 @@ async function doInitLbug(repoId, dbPath) {
     // Done BEFORE pool registration so no concurrent checkout can grab
     // the connection while the async FTS load is in progress.
     if (!shared.ftsLoaded) {
-        try {
-            await available[0].query('LOAD EXTENSION fts');
-            shared.ftsLoaded = true;
-        }
-        catch {
-            // Extension may not be installed — FTS queries will fail gracefully
-        }
+        shared.ftsLoaded = await loadFTSExtension(available[0]);
     }
     // Load VECTOR extension once per shared Database for semantic search support.
     if (!shared.vectorLoaded) {
@@ -335,13 +351,7 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     }
     // Load FTS extension if not already loaded on this Database
     if (!shared.ftsLoaded) {
-        try {
-            await available[0].query('LOAD EXTENSION fts');
-            shared.ftsLoaded = true;
-        }
-        catch {
-            // Extension may already be loaded or not installed
-        }
+        shared.ftsLoaded = await loadFTSExtension(available[0]);
     }
     // Load VECTOR extension for semantic search support
     if (!shared.vectorLoaded) {

package/dist/core/run-analyze.d.ts

@@ -13,13 +13,43 @@ export interface AnalyzeCallbacks {
     onLog?: (message: string) => void;
 }
 export interface AnalyzeOptions {
+    /**
+     * Force a full re-index of the pipeline. Callers may OR this with
+     * other flags that imply re-analysis (e.g. `--skills`), so the value
+     * here is the PIPELINE-force signal, NOT the registry-collision
+     * bypass. See `allowDuplicateName` below.
+     */
     force?: boolean;
     embeddings?: boolean;
+    /**
+     * Explicitly drop any embeddings present in the existing index instead of
+     * preserving them. Only meaningful when `embeddings` is false/undefined:
+     * the default behavior in that case is to load the previously generated
+     * embeddings and re-insert them after the rebuild so a routine
+     * re-analyze does not silently wipe a long embedding pass (#issue: analyze
+     * silently wipes existing embeddings when run without --embeddings).
+     */
+    dropEmbeddings?: boolean;
     skipGit?: boolean;
     /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
     skipAgentsMd?: boolean;
     /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
     noStats?: boolean;
+    /**
+     * User-provided alias for the registry `name` (#829). When set,
+     * forwarded to `registerRepo` so the indexed repo is stored under
+     * this alias instead of the path-derived basename.
+     */
+    registryName?: string;
+    /**
+     * Bypass the `RegistryNameCollisionError` guard and allow two paths
+     * to register under the same `name` (#829). Controlled by the
+     * dedicated `--allow-duplicate-name` CLI flag, intentionally
+     * independent from `--force` — users who hit the collision guard
+     * should be able to accept the duplicate without paying the cost
+     * of a pipeline re-index.
+     */
+    allowDuplicateName?: boolean;
 }
 export interface AnalyzeResult {
     repoName: string;
@@ -36,6 +66,8 @@ export interface AnalyzeResult {
     /** The raw pipeline result — only populated when needed by callers (e.g. skill generation). */
     pipelineResult?: any;
 }
+export { deriveEmbeddingMode } from './embedding-mode.js';
+export type { EmbeddingMode } from './embedding-mode.js';
 export declare const PHASE_LABELS: Record<string, string>;
 /**
  * Run the full GitNexus analysis pipeline.

package/dist/core/run-analyze.js

@@ -11,14 +11,18 @@
 import path from 'path';
 import fs from 'fs/promises';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
-import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, createFTSIndex, loadCachedEmbeddings, } from './lbug/lbug-adapter.js';
+import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, } from './lbug/lbug-adapter.js';
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
-import { getCurrentCommit, hasGitDir } from '../storage/git.js';
+import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
 /** Threshold: auto-skip embeddings for repos with more nodes than this */
 const EMBEDDING_NODE_LIMIT = 50_000;
+// Re-export the pure flag-derivation helper so external callers (and tests)
+// keep importing from this module's stable surface.
+export { deriveEmbeddingMode } from './embedding-mode.js';
+import { deriveEmbeddingMode as _deriveEmbeddingMode } from './embedding-mode.js';
 export const PHASE_LABELS = {
     extracting: 'Scanning files',
     structure: 'Building structure',
@@ -65,7 +69,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
             return {
-                repoName: path.basename(repoPath),
+                repoName: options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath),
                 repoPath,
                 stats: existingMeta.stats ?? {},
                 alreadyUpToDate: true,
@@ -73,9 +77,39 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
     }
     // ── Cache embeddings from existing index before rebuild ────────────
+    // Four modes:
+    //   --embeddings              -> load cache, restore, then generate any new ones
+    //   --force (with existing
+    //    embeddings)              -> auto-imply --embeddings: load cache, restore,
+    //                                regenerate embeddings for new/changed nodes
+    //                                (a forced re-index of an embedded repo
+    //                                shouldn't quietly downgrade to "preserve only")
+    //   (default)                 -> if existing index has embeddings, preserve them
+    //                                (load + restore, but do not generate); otherwise no-op
+    //   --drop-embeddings         -> skip cache load entirely; rebuild wipes embeddings
+    //
+    // The default-preserve branch is what makes a routine `analyze` (e.g. a
+    // post-commit hook) safe: a multi-minute embedding pass is no longer
+    // silently dropped just because the caller omitted `--embeddings`.
     let cachedEmbeddingNodeIds = new Set();
     let cachedEmbeddings = [];
-    if (options.embeddings && existingMeta && !options.force) {
+    const existingEmbeddingCount = existingMeta?.stats?.embeddings ?? 0;
+    const { forceRegenerateEmbeddings, preserveExistingEmbeddings, shouldGenerateEmbeddings, shouldLoadCache, } = _deriveEmbeddingMode(options, existingEmbeddingCount);
+    if (options.dropEmbeddings && existingEmbeddingCount > 0) {
+        log(`Dropping ${existingEmbeddingCount} existing embeddings (--drop-embeddings). ` +
+            `Re-run with --embeddings to regenerate.`);
+    }
+    else if (forceRegenerateEmbeddings) {
+        log(`--force on a repo with ${existingEmbeddingCount} existing embeddings: ` +
+            `regenerating embeddings for new/changed nodes. ` +
+            `Pass --drop-embeddings to wipe them instead.`);
+    }
+    else if (preserveExistingEmbeddings) {
+        log(`Preserving ${existingEmbeddingCount} existing embeddings. ` +
+            `Pass --embeddings to also generate embeddings for new/changed nodes, ` +
+            `or --drop-embeddings to wipe them.`);
+    }
+    if (shouldLoadCache && existingMeta) {
         try {
             progress('embeddings', 0, 'Caching embeddings...');
             await initLbug(lbugPath);
@@ -84,7 +118,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             cachedEmbeddings = cached.embeddings;
             await closeLbug();
         }
-        catch {
+        catch (err) {
+            // Surface cache-load failures explicitly: silently swallowing here would
+            // re-introduce the original silent-data-loss symptom (embeddings end up
+            // at 0 in meta.json with no diagnostic) through a different door.
+            log(`Warning: could not load cached embeddings ` +
+                `(${err?.message ?? String(err)}). ` +
+                `Embeddings will not be preserved on this run.`);
+            cachedEmbeddingNodeIds = new Set();
+            cachedEmbeddings = [];
             try {
                 await closeLbug();
             }
@@ -123,17 +165,12 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             progress('lbug', pct, msg);
         });
         // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
-        progress('fts', 85, 'Creating search indexes...');
-        try {
-            await createFTSIndex('File', 'file_fts', ['name', 'content']);
-            await createFTSIndex('Function', 'function_fts', ['name', 'content']);
-            await createFTSIndex('Class', 'class_fts', ['name', 'content']);
-            await createFTSIndex('Method', 'method_fts', ['name', 'content']);
-            await createFTSIndex('Interface', 'interface_fts', ['name', 'content']);
-        }
-        catch {
-            // Non-fatal — FTS is best-effort
-        }
+        // FTS indexes are created lazily on first `query`/`context` call instead
+        // of eagerly here. On small repos / CI runners the LadybugDB
+        // CREATE_FTS_INDEX cost is ~440 ms × 5 (≈2 s) regardless of table size,
+        // which dominated `analyze` runtime and pushed Windows CI past its
+        // 30 s test budget. Lazy creation is implemented in
+        // `core/search/bm25-index.ts` via `ensureFTSIndex`.
         // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
         if (cachedEmbeddings.length > 0) {
             const cachedDims = cachedEmbeddings[0].embedding.length;
@@ -162,7 +199,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
         const stats = await getLbugStats();
         let embeddingSkipped = true;
-        if (options.embeddings) {
+        if (shouldGenerateEmbeddings) {
             if (stats.nodes <= EMBEDDING_NODE_LIMIT) {
                 embeddingSkipped = false;
             }
@@ -208,6 +245,13 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             repoPath,
             lastCommit: currentCommit,
             indexedAt: new Date().toISOString(),
+            // Captured here (not at registration) so it travels with the
+            // on-disk meta.json — sibling-clone fingerprinting works for
+            // out-of-tree consumers (group-status, future tooling) without
+            // a second git shellout. `undefined` when the repo has no
+            // origin remote, which is fine: paths-only repos behave as
+            // before.
+            remoteUrl: hasGitDir(repoPath) ? getRemoteUrl(repoPath) : undefined,
             stats: {
                 files: pipelineResult.totalFileCount,
                 nodes: stats.nodes,
@@ -218,12 +262,23 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             },
         };
         await saveMeta(storagePath, meta);
-        await registerRepo(repoPath, meta);
+        // Forward the --name alias and the registry-collision bypass bit.
+        // `allowDuplicateName` is its own concern — independent from the
+        // pipeline `force` above. The CLI maps it from
+        // `--allow-duplicate-name` only; `--force` and `--skills` both
+        // trigger pipeline re-run but never bypass the registry guard.
+        // The returned name is the one actually written to the registry
+        // (after applying the precedence chain in registerRepo) — reuse it
+        // so AGENTS.md / skill files reference the same name MCP clients
+        // will look up (#979).
+        const projectName = await registerRepo(repoPath, meta, {
+            name: options.registryName,
+            allowDuplicateName: options.allowDuplicateName,
+        });
         // Only attempt to update .gitignore when a .git directory is present.
         if (hasGitDir(repoPath)) {
             await addToGitignore(repoPath);
         }
-        const projectName = path.basename(repoPath);
         // ── Generate AI context files (best-effort) ───────────────────────
         let aggregatedClusterCount = 0;
         if (pipelineResult.communityResult?.communities) {

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

@@ -3,12 +3,30 @@
  *
  * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
  * Always reads from the database (no cached state to drift).
+ *
+ * FTS indexes are created lazily on first query (via `ensureFTSIndex`) — see
+ * `lbug-adapter.ts` for the rationale. This keeps `analyze` fast (the
+ * ~440 ms × 5 LadybugDB CREATE_FTS_INDEX cost dominates pipeline time on
+ * small repos / CI runners) at the cost of paying that overhead on the
+ * first `query`/`context` call in a session.
  */
 export interface BM25SearchResult {
     filePath: string;
     score: number;
     rank: number;
+    nodeIds?: string[];
 }
+/**
+ * Drop all ensured-FTS cache entries for a given repoId.
+ *
+ * Called from the pool-close listener so that a pool teardown / recreation
+ * forces the next `searchFTSFromLbug` call to re-issue `CREATE_FTS_INDEX`
+ * against the fresh connection rather than trust stale ensure-state from a
+ * previous pool lifetime.
+ *
+ * Exported for tests; the listener wiring is internal.
+ */
+export declare function invalidateEnsuredFTSForRepo(repoId: string): void;
 /**
  * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
  *

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

@@ -3,8 +3,96 @@
  *
  * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
  * Always reads from the database (no cached state to drift).
+ *
+ * FTS indexes are created lazily on first query (via `ensureFTSIndex`) — see
+ * `lbug-adapter.ts` for the rationale. This keeps `analyze` fast (the
+ * ~440 ms × 5 LadybugDB CREATE_FTS_INDEX cost dominates pipeline time on
+ * small repos / CI runners) at the cost of paying that overhead on the
+ * first `query`/`context` call in a session.
+ */
+import { queryFTS, ensureFTSIndex } from '../lbug/lbug-adapter.js';
+/**
+ * FTS schema served by `searchFTSFromLbug`. Centralised so that both the
+ * CLI/pipeline path and the MCP pool path use identical (table, index,
+ * properties) tuples and the lazy-create logic stays in one place.
+ */
+const FTS_INDEXES = [
+    { table: 'File', indexName: 'file_fts', properties: ['name', 'content'] },
+    { table: 'Function', indexName: 'function_fts', properties: ['name', 'content'] },
+    { table: 'Class', indexName: 'class_fts', properties: ['name', 'content'] },
+    { table: 'Method', indexName: 'method_fts', properties: ['name', 'content'] },
+    { table: 'Interface', indexName: 'interface_fts', properties: ['name', 'content'] },
+];
+/**
+ * Per-process cache for the MCP pool path: tracks which `(repoId, table)`
+ * pairs have been ensured. The CLI/pipeline path gets its own cache inside
+ * `lbug-adapter.ts` keyed by table/index, scoped to the singleton connection.
+ *
+ * IMPORTANT: an entry is added ONLY when the index was confirmed to exist
+ * (CREATE_FTS_INDEX succeeded, or failed with `'already exists'`). Other
+ * failures (transient lock errors, missing extension, etc.) leave the key
+ * unset so the next query retries instead of silently caching the failure.
+ *
+ * Entries for a given repoId are invalidated when its pool is closed —
+ * see the `addPoolCloseListener` registration in `searchFTSFromLbug`.
+ */
+const ensuredPoolFTS = new Set();
+/**
+ * Drop all ensured-FTS cache entries for a given repoId.
+ *
+ * Called from the pool-close listener so that a pool teardown / recreation
+ * forces the next `searchFTSFromLbug` call to re-issue `CREATE_FTS_INDEX`
+ * against the fresh connection rather than trust stale ensure-state from a
+ * previous pool lifetime.
+ *
+ * Exported for tests; the listener wiring is internal.
+ */
+export function invalidateEnsuredFTSForRepo(repoId) {
+    const prefix = `${repoId}:`;
+    for (const key of ensuredPoolFTS) {
+        if (key.startsWith(prefix))
+            ensuredPoolFTS.delete(key);
+    }
+}
+/**
+ * Tracks whether we've already wired the pool-close listener for this
+ * process. The pool adapter is dynamically imported, so registration
+ * happens lazily on the first MCP-pool-backed FTS query.
  */
-import { queryFTS } from '../lbug/lbug-adapter.js';
+let poolCloseListenerRegistered = false;
+function registerPoolCloseListenerOnce(addPoolCloseListener) {
+    if (poolCloseListenerRegistered)
+        return;
+    poolCloseListenerRegistered = true;
+    addPoolCloseListener((repoId) => invalidateEnsuredFTSForRepo(repoId));
+}
+async function ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties) {
+    const key = `${repoId}:${table}:${indexName}`;
+    if (ensuredPoolFTS.has(key))
+        return;
+    const propList = properties.map((p) => `'${p}'`).join(', ');
+    try {
+        await executor(`CALL CREATE_FTS_INDEX('${table}', '${indexName}', [${propList}], stemmer := 'porter')`);
+        // Index was created successfully — safe to cache.
+        ensuredPoolFTS.add(key);
+    }
+    catch (e) {
+        // 'already exists' is the happy path (index persists on disk between
+        // process invocations) — cache it. Anything else is treated as a
+        // transient failure: surface a one-time warning and leave the key
+        // unset so the NEXT query retries rather than silently using a
+        // cached failure (which previously disabled BM25 for the whole
+        // process for that repo).
+        const msg = String(e?.message ?? '');
+        if (msg.includes('already exists')) {
+            ensuredPoolFTS.add(key);
+        }
+        else {
+            console.warn(`[gitnexus] FTS index ensure failed for repo "${repoId}" table "${table}" ` +
+                `(index "${indexName}"): ${msg || e}. Will retry on next query.`);
+        }
+    }
+}
 /**
  * Execute a single FTS query via a custom executor (for MCP connection pool).
  * Returns the same shape as core queryFTS (from LadybugDB adapter).
@@ -26,6 +114,7 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
             return {
                 filePath: node.filePath || '',
                 score: typeof score === 'number' ? score : parseFloat(score) || 0,
+                nodeId: node.nodeId || node.id || '',
             };
         });
     }
@@ -50,8 +139,19 @@ export const searchFTSFromLbug = async (query, limit = 20, 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.
-        const { executeQuery } = await import('../lbug/pool-adapter.js');
+        const poolMod = await import('../lbug/pool-adapter.js');
+        const { executeQuery, addPoolCloseListener } = poolMod;
+        // Register the pool-close listener lazily on first use so a teardown of
+        // the pool entry (LRU eviction, idle timeout, explicit close) drops the
+        // matching `ensuredPoolFTS` entries. Without this, stale ensure-state
+        // can outlive the pool that produced it.
+        registerPoolCloseListenerOnce(addPoolCloseListener);
         const executor = (cypher) => executeQuery(repoId, cypher);
+        // Lazy-create FTS indexes on first query for this repo (analyze no longer
+        // creates them up-front, so we ensure them here). Cached per-process.
+        for (const { table, indexName, properties } of FTS_INDEXES) {
+            await ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties);
+        }
         fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
         functionResults = await queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit);
         classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);
@@ -59,24 +159,24 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         interfaceResults = await queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit);
     }
     else {
-        // Use core lbug adapter (CLI / pipeline context) — also sequential for safety
+        // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
+        // Lazy-create FTS indexes on first query (analyze no longer does it).
+        for (const { table, indexName, properties } of FTS_INDEXES) {
+            await ensureFTSIndex(table, indexName, [...properties]).catch(() => { });
+        }
         fileResults = await queryFTS('File', 'file_fts', query, limit, false).catch(() => []);
         functionResults = await queryFTS('Function', 'function_fts', query, limit, false).catch(() => []);
         classResults = await queryFTS('Class', 'class_fts', query, limit, false).catch(() => []);
         methodResults = await queryFTS('Method', 'method_fts', query, limit, false).catch(() => []);
         interfaceResults = await queryFTS('Interface', 'interface_fts', query, limit, false).catch(() => []);
     }
-    // Merge results by filePath, summing scores for same file
-    const merged = new Map();
+    // Collect all node scores per filePath to track which nodes actually matched
+    const fileNodeScores = new Map();
     const addResults = (results) => {
         for (const r of results) {
-            const existing = merged.get(r.filePath);
-            if (existing) {
-                existing.score += r.score;
-            }
-            else {
-                merged.set(r.filePath, { filePath: r.filePath, score: r.score });
-            }
+            if (!fileNodeScores.has(r.filePath))
+                fileNodeScores.set(r.filePath, []);
+            fileNodeScores.get(r.filePath).push({ score: r.score, nodeId: r.nodeId });
         }
     };
     addResults(fileResults);
@@ -84,6 +184,18 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
     addResults(classResults);
     addResults(methodResults);
     addResults(interfaceResults);
+    // Sum the top-3 highest-scoring nodes per file and collect their nodeIds.
+    // Summing all nodes naively inflates scores for files with many mediocre
+    // matches (e.g. test files) over files with a single highly-relevant symbol.
+    const merged = new Map();
+    for (const [filePath, entries] of fileNodeScores) {
+        const top3 = [...entries].sort((a, b) => b.score - a.score).slice(0, 3);
+        merged.set(filePath, {
+            filePath,
+            score: top3.reduce((acc, e) => acc + e.score, 0),
+            nodeIds: top3.map((e) => e.nodeId).filter((id) => id),
+        });
+    }
     // Sort by score descending and add rank
     const sorted = Array.from(merged.values())
         .sort((a, b) => b.score - a.score)
@@ -92,5 +204,6 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         filePath: r.filePath,
         score: r.score,
         rank: index + 1,
+        nodeIds: r.nodeIds,
     }));
 };

package/dist/core/tree-sitter/parser-loader.js

@@ -5,7 +5,12 @@ import Python from 'tree-sitter-python';
 import Java from 'tree-sitter-java';
 import C from 'tree-sitter-c';
 import CPP from 'tree-sitter-cpp';
-import CSharp from 'tree-sitter-c-sharp';
+// Explicit subpath import: tree-sitter-c-sharp declares `type: "module"` with
+// `main: "bindings/node"` (no extension) and no `exports` field, which triggers
+// Node 22's DEP0151 deprecation warning on the bare-package import. Importing
+// the built entrypoint directly bypasses the deprecated ESM main-field
+// resolution. (#1013)
+import CSharp from 'tree-sitter-c-sharp/bindings/node/index.js';
 import Go from 'tree-sitter-go';
 import Rust from 'tree-sitter-rust';
 import PHP from 'tree-sitter-php';