gitnexus 1.6.10-rc.3 → 1.6.10-rc.5

package/README.md

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

package/dist/cli/doctor.js

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

package/dist/core/group/extractors/manifest-extractor.js

@@ -7,6 +7,10 @@ import { logger } from '../../logger.js';
 // reserved-keyword labels `Macro` and `Union`, and LadybugDB's parser rejects
 // a disjunction that names a reserved keyword (#2325) — which the resolver's
 // try/catch then swallowed. `labels(n) IN` has no such collision.
+// This list overlaps `ingestion/utils/symbol-labels.ts` (SYMBOL_NODE_LABELS) but
+// is a deliberate SUBSET — it omits `Namespace`/`Variable`/`Module`. Unifying the
+// two would widen which nodes resolve as contract symbols and must update the
+// #2325 test, so they are intentionally kept separate for now.
 export const CUSTOM_CONTRACT_RESOLVE_QUERY = `MATCH (n)
    WHERE labels(n) IN ['Function','Method','Class','Interface','Struct','Enum','Trait','Constructor','TypeAlias','Impl','Macro','Union','Typedef','Property','Record','Delegate','Annotation','Template','Const','Static','CodeElement']
      AND n.name = $symbolName

package/dist/core/ingestion/cobol/jcl-processor.js

@@ -17,6 +17,7 @@
  */
 import { parseJcl } from './jcl-parser.js';
 import { generateId } from '../../../lib/utils.js';
+import { toZeroBasedLine } from '../utils/line-base.js';
 /**
  * Process JCL files and integrate into the knowledge graph.
  *
@@ -71,8 +72,8 @@ function integrateJclResults(graph, parsed, filePath, moduleNames) {
             properties: {
                 name: job.name,
                 filePath,
-                startLine: job.line,
-                endLine: job.line,
+                startLine: toZeroBasedLine(job.line),
+                endLine: toZeroBasedLine(job.line),
                 description: `jcl-job${classPart}${msgPart}`,
             },
         });
@@ -105,8 +106,8 @@ function integrateJclResults(graph, parsed, filePath, moduleNames) {
             properties: {
                 name: step.name,
                 filePath,
-                startLine: step.line,
-                endLine: step.line,
+                startLine: toZeroBasedLine(step.line),
+                endLine: toZeroBasedLine(step.line),
                 description: `jcl-step${pgmPart}${procPart}`,
             },
         });
@@ -170,8 +171,8 @@ function integrateJclResults(graph, parsed, filePath, moduleNames) {
                 properties: {
                     name: dd.dataset,
                     filePath,
-                    startLine: dd.line,
-                    endLine: dd.line,
+                    startLine: toZeroBasedLine(dd.line),
+                    endLine: toZeroBasedLine(dd.line),
                     description: `jcl-dataset${dispPart}`,
                 },
             });
@@ -202,8 +203,8 @@ function integrateJclResults(graph, parsed, filePath, moduleNames) {
             properties: {
                 name: proc.name,
                 filePath,
-                startLine: proc.line,
-                endLine: proc.line,
+                startLine: toZeroBasedLine(proc.line),
+                endLine: toZeroBasedLine(proc.line),
                 description: 'jcl-proc-instream',
             },
         });

package/dist/core/ingestion/cobol-processor.js

@@ -14,6 +14,7 @@
  */
 import path from 'node:path';
 import { generateId } from '../../lib/utils.js';
+import { toZeroBasedLine } from './utils/line-base.js';
 import { SupportedLanguages } from '../../_shared/index.js';
 import { preprocessCobolSource, extractCobolSymbolsWithRegex, } from './cobol/cobol-preprocessor.js';
 import { expandCopies } from './cobol/cobol-copy-expander.js';
@@ -275,8 +276,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: extracted.programName,
                 filePath,
-                startLine: 1,
-                endLine: lines.length,
+                startLine: toZeroBasedLine(1),
+                endLine: toZeroBasedLine(lines.length),
                 language: SupportedLanguages.Cobol,
                 isExported: true,
                 description: metaDesc || undefined,
@@ -310,8 +311,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: prog.name,
                 filePath,
-                startLine: prog.startLine,
-                endLine: prog.endLine,
+                startLine: toZeroBasedLine(prog.startLine),
+                endLine: toZeroBasedLine(prog.endLine),
                 language: SupportedLanguages.Cobol,
                 isExported: true,
                 description: `nested-program${prog.isCommon ? ' common' : ''}`,
@@ -349,8 +350,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: sec.name,
                 filePath,
-                startLine: sec.line,
-                endLine: nextLine,
+                startLine: toZeroBasedLine(sec.line),
+                endLine: toZeroBasedLine(nextLine),
                 language: SupportedLanguages.Cobol,
                 isExported: true,
             },
@@ -379,8 +380,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: para.name,
                 filePath,
-                startLine: para.line,
-                endLine: nextLine,
+                startLine: toZeroBasedLine(para.line),
+                endLine: toZeroBasedLine(nextLine),
                 language: SupportedLanguages.Cobol,
                 isExported: true,
             },
@@ -412,8 +413,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: item.name,
                 filePath,
-                startLine: item.line,
-                endLine: item.line,
+                startLine: toZeroBasedLine(item.line),
+                endLine: toZeroBasedLine(item.line),
                 language: SupportedLanguages.Cobol,
                 description: `level:${item.level} section:${item.section}${item.pic ? ` pic:${item.pic}` : ''}`,
             },
@@ -506,8 +507,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
                 properties: {
                     name: `CALL ${call.target}`,
                     filePath,
-                    startLine: call.line,
-                    endLine: call.line,
+                    startLine: toZeroBasedLine(call.line),
+                    endLine: toZeroBasedLine(call.line),
                     language: SupportedLanguages.Cobol,
                     description: 'dynamic-call (target is a data item, not resolvable statically)',
                 },
@@ -619,8 +620,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: `EXEC SQL ${sql.operation}`,
                 filePath,
-                startLine: sql.line,
-                endLine: sql.line,
+                startLine: toZeroBasedLine(sql.line),
+                endLine: toZeroBasedLine(sql.line),
                 language: SupportedLanguages.Cobol,
                 description: `tables:[${sql.tables.join(',')}] cursors:[${sql.cursors.join(',')}]`,
             },
@@ -691,8 +692,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: `EXEC CICS ${cics.command}`,
                 filePath,
-                startLine: cics.line,
-                endLine: cics.line,
+                startLine: toZeroBasedLine(cics.line),
+                endLine: toZeroBasedLine(cics.line),
                 language: SupportedLanguages.Cobol,
                 description: [
                     cics.mapName && `map:${cics.mapName}`,
@@ -726,8 +727,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
                     properties: {
                         name: `CICS ${cics.command} ${cics.programName}`,
                         filePath,
-                        startLine: cics.line,
-                        endLine: cics.line,
+                        startLine: toZeroBasedLine(cics.line),
+                        endLine: toZeroBasedLine(cics.line),
                         language: SupportedLanguages.Cobol,
                         description: `cics-dynamic-program (target is data item ${cics.programName})`,
                     },
@@ -879,8 +880,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: entry.name,
                 filePath,
-                startLine: entry.line,
-                endLine: entry.line,
+                startLine: toZeroBasedLine(entry.line),
+                endLine: toZeroBasedLine(entry.line),
                 language: SupportedLanguages.Cobol,
                 isExported: true,
                 description: entry.parameters.length > 0 ? `using:${entry.parameters.join(',')}` : undefined,
@@ -1014,8 +1015,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: `EXEC DLI ${dli.verb}`,
                 filePath,
-                startLine: dli.line,
-                endLine: dli.line,
+                startLine: toZeroBasedLine(dli.line),
+                endLine: toZeroBasedLine(dli.line),
                 language: SupportedLanguages.Cobol,
                 description: [
                     dli.segmentName && `segment:${dli.segmentName}`,
@@ -1148,8 +1149,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
             properties: {
                 name: fd.selectName,
                 filePath,
-                startLine: fd.line,
-                endLine: fd.line,
+                startLine: toZeroBasedLine(fd.line),
+                endLine: toZeroBasedLine(fd.line),
                 language: SupportedLanguages.Cobol,
                 description: `assign:${fd.assignTo}${fd.isOptional ? ' optional' : ''}${fd.organization ? ` org:${fd.organization}` : ''}${fd.access ? ` access:${fd.access}` : ''}`,
             },
@@ -1231,8 +1232,8 @@ function mapToGraph(graph, extracted, file, copyResolutions, moduleNodeIds) {
                 properties: {
                     name: `CANCEL ${cancel.target}`,
                     filePath,
-                    startLine: cancel.line,
-                    endLine: cancel.line,
+                    startLine: toZeroBasedLine(cancel.line),
+                    endLine: toZeroBasedLine(cancel.line),
                     language: SupportedLanguages.Cobol,
                     description: 'dynamic-cancel (target is a data item, not resolvable statically)',
                 },

package/dist/core/ingestion/emit-references.js

@@ -44,6 +44,7 @@
  * ancestor scope, and if THAT produces nothing either the edge is
  * skipped (with a count returned in `EmitStats.skippedNoCaller`).
  */
+import { toZeroBasedLine } from './utils/line-base.js';
 /**
  * Drain `referenceIndex.bySourceScope` into graph edges.
  *
@@ -95,8 +96,8 @@ export function emitScopeGraph(input) {
             properties: {
                 name: scope.kind,
                 filePath: scope.filePath,
-                startLine: scope.range.startLine,
-                endLine: scope.range.endLine,
+                startLine: toZeroBasedLine(scope.range.startLine),
+                endLine: toZeroBasedLine(scope.range.endLine),
                 description: `Scope: ${scope.kind}`,
             },
         });

package/dist/core/ingestion/markdown-processor.js

@@ -7,6 +7,7 @@
  */
 import path from 'node:path';
 import { generateId } from '../../lib/utils.js';
+import { toZeroBasedLine } from './utils/line-base.js';
 const HEADING_RE = /^(#{1,6})\s+(.+)$/;
 const LINK_RE = /\[([^\]]*)\]\(([^)]+)\)/g;
 const MD_EXTENSIONS = new Set(['.md', '.mdx']);
@@ -59,8 +60,8 @@ export const processMarkdown = (graph, files, allPathSet) => {
                 properties: {
                     name: heading,
                     filePath: file.path,
-                    startLine: lineNum,
-                    endLine,
+                    startLine: toZeroBasedLine(lineNum),
+                    endLine: toZeroBasedLine(endLine),
                     level,
                     description: `h${level}`,
                 },

package/dist/core/ingestion/utils/line-base.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Convert a 1-based source line number to the 0-based convention used by
+ * GraphNode `startLine`/`endLine`.
+ *
+ * The graph layer stores line numbers 0-based (tree-sitter `startPosition.row`),
+ * and this is load-bearing: the taint/PDG/CFG join and the MCP consumers all add
+ * `+ 1` to recover 1-based (see `summary-harvest-driver.ts` — "Function/Method
+ * node startLine is 0-based"). Most emitters get 0-based for free from
+ * tree-sitter. The exceptions are the regex-based COBOL/JCL processors (their
+ * parsers use `lineNum = i + 1`) and the scope-capture path (`Capture` ranges
+ * are 1-based per RFC §2.1). Those must convert to 0-based when they build a
+ * graph node, or the exact-content slice in `csv-generator.ts` drops the
+ * symbol's declaration line (#2379) and reported line numbers are off (#2377).
+ *
+ * Apply this ONLY at the graph-node `startLine:`/`endLine:` assignment. The
+ * parser-internal 1-based values (`.line`, `prog.startLine`) stay 1-based —
+ * they feed `L${line}` node/edge IDs and line-range containment checks that
+ * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
+ */
+export declare const toZeroBasedLine: (oneBasedLine: number) => number;

package/dist/core/ingestion/utils/line-base.js

@@ -0,0 +1,20 @@
+/**
+ * Convert a 1-based source line number to the 0-based convention used by
+ * GraphNode `startLine`/`endLine`.
+ *
+ * The graph layer stores line numbers 0-based (tree-sitter `startPosition.row`),
+ * and this is load-bearing: the taint/PDG/CFG join and the MCP consumers all add
+ * `+ 1` to recover 1-based (see `summary-harvest-driver.ts` — "Function/Method
+ * node startLine is 0-based"). Most emitters get 0-based for free from
+ * tree-sitter. The exceptions are the regex-based COBOL/JCL processors (their
+ * parsers use `lineNum = i + 1`) and the scope-capture path (`Capture` ranges
+ * are 1-based per RFC §2.1). Those must convert to 0-based when they build a
+ * graph node, or the exact-content slice in `csv-generator.ts` drops the
+ * symbol's declaration line (#2379) and reported line numbers are off (#2377).
+ *
+ * Apply this ONLY at the graph-node `startLine:`/`endLine:` assignment. The
+ * parser-internal 1-based values (`.line`, `prog.startLine`) stay 1-based —
+ * they feed `L${line}` node/edge IDs and line-range containment checks that
+ * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
+ */
+export const toZeroBasedLine = (oneBasedLine) => Math.max(0, oneBasedLine - 1);

package/dist/core/ingestion/utils/symbol-labels.d.ts

@@ -0,0 +1,21 @@
+import type { NodeLabel } from '../../../_shared/index.js';
+/**
+ * Graph-node labels that represent a resolvable code symbol — a definition with
+ * its own source span (function, type, member, module-like container).
+ *
+ * These get EXACT source-span content in the FTS index: `csv-generator.ts`
+ * slices exactly `[startLine, endLine]` for them (no ±2 padding), while every
+ * other label keeps the context window. That exactness depends on the 0-based
+ * `startLine`/`endLine` invariant enforced by `line-base.ts` — the slice is only
+ * correct because all emitters store 0-based lines. Keep the two together.
+ *
+ * Single source of truth so the set can't silently drift the way the inline copy
+ * did in #2379.
+ *
+ * NOTE: `group/extractors/manifest-extractor.ts`'s `CUSTOM_CONTRACT_RESOLVE_QUERY`
+ * carries a near-identical hand-list that is intentionally a SUBSET — it excludes
+ * `Namespace`, `Variable`, `Module`. Unifying the two needs a contract-resolution
+ * behavior check (would widen which nodes resolve as contract symbols), so it is
+ * deliberately left separate for now.
+ */
+export declare const SYMBOL_NODE_LABELS: ReadonlySet<NodeLabel>;

package/dist/core/ingestion/utils/symbol-labels.js

@@ -0,0 +1,45 @@
+/**
+ * Graph-node labels that represent a resolvable code symbol — a definition with
+ * its own source span (function, type, member, module-like container).
+ *
+ * These get EXACT source-span content in the FTS index: `csv-generator.ts`
+ * slices exactly `[startLine, endLine]` for them (no ±2 padding), while every
+ * other label keeps the context window. That exactness depends on the 0-based
+ * `startLine`/`endLine` invariant enforced by `line-base.ts` — the slice is only
+ * correct because all emitters store 0-based lines. Keep the two together.
+ *
+ * Single source of truth so the set can't silently drift the way the inline copy
+ * did in #2379.
+ *
+ * NOTE: `group/extractors/manifest-extractor.ts`'s `CUSTOM_CONTRACT_RESOLVE_QUERY`
+ * carries a near-identical hand-list that is intentionally a SUBSET — it excludes
+ * `Namespace`, `Variable`, `Module`. Unifying the two needs a contract-resolution
+ * behavior check (would widen which nodes resolve as contract symbols), so it is
+ * deliberately left separate for now.
+ */
+export const SYMBOL_NODE_LABELS = new Set([
+    'Function',
+    'Method',
+    'Class',
+    'Interface',
+    'CodeElement',
+    'Struct',
+    'Enum',
+    'Macro',
+    'Typedef',
+    'Union',
+    'Namespace',
+    'Trait',
+    'Impl',
+    'TypeAlias',
+    'Const',
+    'Static',
+    'Variable',
+    'Property',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Constructor',
+    'Template',
+    'Module',
+]);

package/dist/core/lbug/csv-generator.js

@@ -17,6 +17,7 @@ import path from 'path';
 import { NODE_TABLES } from './schema.js';
 import { RelPairRouter } from './rel-pair-routing.js';
 import { parseTruthyEnv } from '../ingestion/utils/env.js';
+import { SYMBOL_NODE_LABELS } from '../ingestion/utils/symbol-labels.js';
 import { applyCjkSegmentationIfEnabled } from '../search/cjk-segmentation.js';
 /**
  * Deterministic output ordering — optional (out-of-core / windowed-resolve
@@ -187,6 +188,10 @@ class FileContentCache {
 export const normalizeFtsText = (text) => text.replace(/[\r\n\t]+/g, ' ');
 /** Composes both FTS-text transforms for the `description` column — one place for the six emission sites below to call, instead of repeating the composition. */
 const formatFtsDescription = (description) => normalizeFtsText(applyCjkSegmentationIfEnabled(description));
+// Labels that get exact source-span content (no ±2 window). Single source of
+// truth in `symbol-labels.ts` — see there for why the exactness depends on the
+// 0-based line invariant. Kept as a named alias to read intent at the use site.
+const EXACT_SYMBOL_CONTENT_LABELS = SYMBOL_NODE_LABELS;
 const extractContent = async (node, contentCache) => {
     const filePath = node.properties.filePath;
     const content = await contentCache.get(filePath);
@@ -209,8 +214,9 @@ const extractContent = async (node, contentCache) => {
     if (startLine === undefined || endLine === undefined)
         return '';
     const lines = content.split('\n');
-    const start = Math.max(0, startLine - 2);
-    const end = Math.min(lines.length - 1, endLine + 2);
+    const exactSymbolContent = EXACT_SYMBOL_CONTENT_LABELS.has(node.label);
+    const start = Math.max(0, exactSymbolContent ? startLine : startLine - 2);
+    const end = Math.min(lines.length - 1, exactSymbolContent ? endLine : endLine + 2);
     const snippet = lines.slice(start, end + 1).join('\n');
     const MAX_SNIPPET = 5000;
     const capped = snippet.length > MAX_SNIPPET ? snippet.slice(0, MAX_SNIPPET) + '\n... [truncated]' : snippet;

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

@@ -29,7 +29,7 @@ export interface ExtensionEnsureOptions {
 export interface ExtensionManagerOptions {
     policy?: ExtensionInstallPolicy;
     installTimeoutMs?: number;
-    installExtension?: (extensionName: string, timeoutMs: number) => Promise<ExtensionInstallResult>;
+    installExtension?: (extensionName: string, timeoutMs: number, loadError?: string) => Promise<ExtensionInstallResult>;
     warn?: (message: string) => void;
 }
 export declare const getExtensionInstallPolicy: () => ExtensionInstallPolicy;
@@ -58,7 +58,7 @@ export declare const getExtensionInstallChildProcessArgs: (extensionName: string
  * If the child exceeds `timeoutMs` the parent kills it with SIGKILL and
  * resolves with `timedOut: true`.
  */
-export declare const installDuckDbExtensionOutOfProcess: (extensionName: string, timeoutMs?: number) => Promise<ExtensionInstallResult>;
+export declare const installDuckDbExtensionOutOfProcess: (extensionName: string, timeoutMs?: number, loadError?: string) => Promise<ExtensionInstallResult>;
 /**
  * Centralized lifecycle manager for optional LadybugDB extensions.
  *
@@ -90,6 +90,14 @@ export declare class ExtensionManager {
      * paths are expected to degrade gracefully.
      */
     ensure(query: (sql: string) => Promise<unknown>, name: string, label: string, opts?: ExtensionEnsureOptions): Promise<boolean>;
+    /**
+     * Attempt `LOAD EXTENSION <name>`; returns `null` on success and the
+     * collapsed error message on failure. The message is the load-side ground
+     * truth — LadybugDB distinguishes a missing extension file from a present
+     * but unloadable one (wrong platform, truncated download, version mismatch),
+     * and discarding it left users staring at "not pre-installed" when the file
+     * existed all along (#2374).
+     */
     private tryLoad;
     private markLoaded;
     private markUnavailable;

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

@@ -7,6 +7,8 @@ const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
 const alreadyAvailable = (message) => message.includes('already loaded') ||
     message.includes('already installed') ||
     message.includes('already exists');
+/** LadybugDB errors are multi-line; collapse for single-line warn/reason strings. */
+const oneLine = (value) => value.replace(/\s+/g, ' ').trim();
 const resolvePolicyFromEnv = () => {
     const raw = process.env.GITNEXUS_LBUG_EXTENSION_INSTALL;
     if (raw === 'load-only' || raw === 'never' || raw === 'auto')
@@ -51,7 +53,7 @@ export const getExtensionInstallChildProcessArgs = (extensionName, maxDbSize = L
  * If the child exceeds `timeoutMs` the parent kills it with SIGKILL and
  * resolves with `timedOut: true`.
  */
-export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutMs = getExtensionInstallTimeoutMs()) => {
+export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutMs = getExtensionInstallTimeoutMs(), loadError) => {
     if (!EXTENSION_NAME_PATTERN.test(extensionName)) {
         throw new Error(`Invalid DuckDB extension name: ${extensionName}`);
     }
@@ -60,6 +62,9 @@ export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutM
             env: {
                 ...process.env,
                 GITNEXUS_LBUG_EXTENSION_NAME: extensionName,
+                // The child picks INSTALL vs FORCE INSTALL from this LOAD error so it
+                // only re-downloads when the on-disk extension file is actually broken.
+                ...(loadError ? { GITNEXUS_LBUG_EXTENSION_LOAD_ERROR: loadError } : {}),
             },
             stdio: ['ignore', 'ignore', 'pipe'],
             windowsHide: true,
@@ -78,7 +83,7 @@ export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutM
             resolve({
                 success: false,
                 timedOut: true,
-                message: `INSTALL ${extensionName} timed out after ${timeoutMs}ms`,
+                message: `extension install for ${extensionName} timed out after ${timeoutMs}ms`,
             });
         }, timeoutMs);
         child.on('error', (err) => {
@@ -97,8 +102,8 @@ export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutM
                 success: code === 0,
                 timedOut: false,
                 message: code === 0
-                    ? `INSTALL ${extensionName} completed`
-                    : `INSTALL ${extensionName} failed with ${signal ?? `exit code ${code}`}${stderr ? `: ${stderr.trim()}` : ''}`,
+                    ? `extension install for ${extensionName} completed`
+                    : `extension install for ${extensionName} failed with ${signal ?? `exit code ${code}`}${stderr ? `: ${stderr.trim()}` : ''}`,
             });
         });
     });
@@ -152,39 +157,51 @@ export class ExtensionManager {
             this.markUnavailable(name, label, 'extension install policy is "never"', warn);
             return false;
         }
-        if (await this.tryLoad(query, name)) {
+        const loadError = await this.tryLoad(query, name);
+        if (loadError === null) {
             this.markLoaded(name);
             return true;
         }
         if (policy === 'load-only') {
-            this.markUnavailable(name, label, 'load-only policy: extension not pre-installed', warn);
+            this.markUnavailable(name, label, `load-only policy (no install attempted); LOAD ${name} failed: ${loadError}`, warn);
             return false;
         }
         let install = this.installAttempted.get(name);
         if (!install) {
             const installFn = this.options.installExtension ?? installDuckDbExtensionOutOfProcess;
-            install = await installFn(name, timeoutMs);
+            // Hand the child the LOAD error so it re-downloads (FORCE) only when the
+            // present extension file is provably broken, not on every LOAD failure.
+            install = await installFn(name, timeoutMs, loadError);
             this.installAttempted.set(name, install);
         }
         if (!install.success) {
-            this.markUnavailable(name, label, install.message, warn);
+            this.markUnavailable(name, label, `${install.message}; LOAD ${name} had failed: ${loadError}`, warn);
             return false;
         }
-        if (await this.tryLoad(query, name)) {
+        const retryError = await this.tryLoad(query, name);
+        if (retryError === null) {
             this.markLoaded(name);
             return true;
         }
-        this.markUnavailable(name, label, `LOAD ${name} failed after successful INSTALL`, warn);
+        this.markUnavailable(name, label, `LOAD ${name} failed after successful INSTALL: ${retryError}`, warn);
         return false;
     }
+    /**
+     * Attempt `LOAD EXTENSION <name>`; returns `null` on success and the
+     * collapsed error message on failure. The message is the load-side ground
+     * truth — LadybugDB distinguishes a missing extension file from a present
+     * but unloadable one (wrong platform, truncated download, version mismatch),
+     * and discarding it left users staring at "not pre-installed" when the file
+     * existed all along (#2374).
+     */
     async tryLoad(query, name) {
         try {
             await query(`LOAD EXTENSION ${name}`);
-            return true;
+            return null;
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            return alreadyAvailable(msg);
+            return alreadyAvailable(msg) ? null : oneLine(msg);
         }
     }
     markLoaded(name) {

package/dist/core/lbug/native-check.d.ts

@@ -4,3 +4,25 @@ export interface NativeCheckResult {
     message?: string;
 }
 export declare function checkLbugNative(overridePkgDir?: string): NativeCheckResult;
+export interface FtsProbeResult {
+    loaded: boolean;
+    /** Collapsed LadybugDB error when `loaded` is false. */
+    reason?: string;
+}
+/**
+ * Live-probe `LOAD EXTENSION fts` on a throwaway in-memory database.
+ *
+ * `doctor` used to print the static platform capability, which contradicted
+ * analyze whenever the extension file was missing or unloadable (#2374).
+ * LOAD never touches the network, so the probe is safe offline, and it
+ * surfaces LadybugDB's real error — which distinguishes a missing extension
+ * file from a present-but-broken one (wrong platform, truncated download).
+ * Dynamic import so doctor still runs when the native module itself is broken.
+ *
+ * Bounded by `timeoutMs`: an unresponsive extension file (e.g. on a hung
+ * network home dir) must never freeze `doctor` — the tool the degradation
+ * warnings send users to. `Promise.race` lets doctor report and move on; it
+ * cannot cancel an in-flight native call, so a future thread-blocking case
+ * would need an out-of-process probe.
+ */
+export declare function probeFtsExtensionLoad(timeoutMs?: number): Promise<FtsProbeResult>;