gitnexus 1.6.10-rc.2 → 1.6.10-rc.21

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

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

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

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

package/dist/core/tree-sitter/safe-parse.d.ts

@@ -42,7 +42,7 @@ export declare function getParseDiagnostics(tree: Parser.Tree): {
 /**
  * Parse `sourceText` safely on every platform.
  *
- * This is the single "parse safely" entry point and its contract covers three
+ * This is the single "parse safely" entry point and its contract covers four
  * concerns:
  *
  *  1. **Windows crash workaround.** Inputs longer than 32 767 chars are fed
@@ -62,7 +62,12 @@ export declare function getParseDiagnostics(tree: Parser.Tree): {
  *     the tree is **returned anyway** — error recovery is a downgrade, never a
  *     drop. Callers wanting the boolean use {@link parseHadErrors}.
  *
- * @param label optional context (e.g. file path) attached to timeout errors
- *   and degraded-parse logs. Non-breaking trailing param.
+ *  4. **Embedded NUL recovery.** U+0000 is replaced with one ASCII space in
+ *     the parser-only input. The one-for-one substitution keeps tree indices
+ *     aligned with the original source while preventing language lexers from
+ *     swallowing declarations during error recovery.
+ *
+ * @param label optional context (e.g. file path) attached to timeout errors,
+ *   recovery warnings, and degraded-parse logs. Non-breaking trailing param.
  */
 export declare function parseSourceSafe(parser: Parser, sourceText: string, oldTree?: Parser.Tree, options?: Parser.Options, label?: string): Parser.Tree;

package/dist/core/tree-sitter/safe-parse.js

@@ -155,7 +155,7 @@ export function getParseDiagnostics(tree) {
 /**
  * Parse `sourceText` safely on every platform.
  *
- * This is the single "parse safely" entry point and its contract covers three
+ * This is the single "parse safely" entry point and its contract covers four
  * concerns:
  *
  *  1. **Windows crash workaround.** Inputs longer than 32 767 chars are fed
@@ -175,22 +175,36 @@ export function getParseDiagnostics(tree) {
  *     the tree is **returned anyway** — error recovery is a downgrade, never a
  *     drop. Callers wanting the boolean use {@link parseHadErrors}.
  *
- * @param label optional context (e.g. file path) attached to timeout errors
- *   and degraded-parse logs. Non-breaking trailing param.
+ *  4. **Embedded NUL recovery.** U+0000 is replaced with one ASCII space in
+ *     the parser-only input. The one-for-one substitution keeps tree indices
+ *     aligned with the original source while preventing language lexers from
+ *     swallowing declarations during error recovery.
+ *
+ * @param label optional context (e.g. file path) attached to timeout errors,
+ *   recovery warnings, and degraded-parse logs. Non-breaking trailing param.
  */
 export function parseSourceSafe(parser, sourceText, oldTree, options, label) {
+    let parserInput = sourceText;
+    if (sourceText.includes('\0')) {
+        let nullByteCount = 0;
+        parserInput = sourceText.replaceAll('\0', () => {
+            nullByteCount += 1;
+            return ' ';
+        });
+        logger.warn({ ...(label ? { file: label } : {}), nullByteCount }, 'replaced embedded NUL bytes before tree-sitter parsing');
+    }
     const budgetMs = resolveParseTimeoutMs();
     const armed = armParseBudget(parser, budgetMs);
     let tree;
     try {
-        if (sourceText.length <= DIRECT_PARSE_LIMIT_CHARS) {
-            tree = parser.parse(sourceText, oldTree, options);
+        if (parserInput.length <= DIRECT_PARSE_LIMIT_CHARS) {
+            tree = parser.parse(parserInput, oldTree, options);
         }
         else {
             const input = (index) => {
-                if (index >= sourceText.length)
+                if (index >= parserInput.length)
                     return null;
-                return sourceText.slice(index, index + SAFE_PARSE_CHUNK_CHARS);
+                return parserInput.slice(index, index + SAFE_PARSE_CHUNK_CHARS);
             };
             tree = parser.parse(input, oldTree, options);
         }

package/dist/core/wiki/graph-queries.js

@@ -5,6 +5,7 @@
  * Uses the MCP-style pooled lbug-adapter for connection management.
  */
 import { initLbug, executeQuery, closeLbug, touchRepo, pinRepo } from '../lbug/pool-adapter.js';
+import { escapeCypherString } from '../lbug/cypher-escape.js';
 const REPO_ID = '__wiki__';
 /**
  * Touch the wiki DB connection to prevent idle timeout during long LLM calls.
@@ -98,7 +99,7 @@ export async function getInterFileCallEdges() {
 export async function getIntraModuleCallEdges(filePaths) {
     if (filePaths.length === 0)
         return [];
-    const fileList = filePaths.map((f) => `'${f.replace(/'/g, "''")}'`).join(', ');
+    const fileList = filePaths.map((f) => `'${escapeCypherString(f)}'`).join(', ');
     const rows = await executeQuery(REPO_ID, `
     MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b)
     WHERE a.filePath IN [${fileList}] AND b.filePath IN [${fileList}]
@@ -118,7 +119,7 @@ export async function getIntraModuleCallEdges(filePaths) {
 export async function getInterModuleCallEdges(filePaths) {
     if (filePaths.length === 0)
         return { outgoing: [], incoming: [] };
-    const fileList = filePaths.map((f) => `'${f.replace(/'/g, "''")}'`).join(', ');
+    const fileList = filePaths.map((f) => `'${escapeCypherString(f)}'`).join(', ');
     const outRows = await executeQuery(REPO_ID, `
     MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b)
     WHERE a.filePath IN [${fileList}] AND NOT b.filePath IN [${fileList}]
@@ -155,7 +156,7 @@ export async function getInterModuleCallEdges(filePaths) {
 export async function getProcessesForFiles(filePaths, limit = 5) {
     if (filePaths.length === 0)
         return [];
-    const fileList = filePaths.map((f) => `'${f.replace(/'/g, "''")}'`).join(', ');
+    const fileList = filePaths.map((f) => `'${escapeCypherString(f)}'`).join(', ');
     // Find processes that have steps in the given files
     const procRows = await executeQuery(REPO_ID, `
     MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
@@ -173,7 +174,7 @@ export async function getProcessesForFiles(filePaths, limit = 5) {
         const stepCount = row.stepCount || row[3] || 0;
         // Get the full step trace for this process
         const stepRows = await executeQuery(REPO_ID, `
-      MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process {id: '${procId.replace(/'/g, "''")}'})
+      MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process {id: '${escapeCypherString(procId)}'})
       RETURN s.name AS name, s.filePath AS filePath, labels(s)[0] AS type, r.step AS step
       ORDER BY r.step
     `);
@@ -210,7 +211,7 @@ export async function getAllProcesses(limit = 20) {
         const type = row.type || row[2] || 'unknown';
         const stepCount = row.stepCount || row[3] || 0;
         const stepRows = await executeQuery(REPO_ID, `
-      MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process {id: '${procId.replace(/'/g, "''")}'})
+      MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process {id: '${escapeCypherString(procId)}'})
       RETURN s.name AS name, s.filePath AS filePath, labels(s)[0] AS type, r.step AS step
       ORDER BY r.step
     `);

package/dist/mcp/core/embedder.js

@@ -7,8 +7,9 @@
 import { isHttpMode, getHttpDimensions, httpEmbedQuery, } from '../../core/embeddings/http-client.js';
 import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
 import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry, } from '../../core/embeddings/hf-env.js';
-import { getLocalEmbeddingRuntimeBlocker } from '../../core/embeddings/runtime-support.js';
+import { getLocalEmbeddingRuntimeBlocker, getMissingLocalEmbeddingStackMessage, } from '../../core/embeddings/runtime-support.js';
 import { ensureOnnxRuntimeCommonResolvable } from '../../core/embeddings/onnxruntime-common-resolver.js';
+import { ensureEmbeddingStackResolvable } from '../../core/embeddings/runtime-install.js';
 import { ensureOnnxRuntimeNodeMatchesSystem } from '../../core/embeddings/onnxruntime-node-resolver.js';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
 import { logger } from '../../core/logger.js';
@@ -45,6 +46,11 @@ export const initEmbedder = async () => {
         try {
             // Lazy-load transformers.js only after the runtime guard has passed, so
             // unsupported platforms never reach the native ONNX import (#1515).
+            // Registered FIRST so it sits last in the hook chain (registerHooks runs
+            // the most recent hook first): when the optional stack was pruned at
+            // install time (#2370), its bare specifiers fall back to the on-demand
+            // runtime prefix.
+            ensureEmbeddingStackResolvable();
             // Under pnpm-strict / `pnpm dlx`, transformers' phantom `onnxruntime-common`
             // import is unresolvable; register the fallback resolver first (#307).
             ensureOnnxRuntimeCommonResolvable();
@@ -55,7 +61,15 @@ export const initEmbedder = async () => {
             // Windows/DirectML, and macOS. Mirrors the core embedder's call site so
             // MCP query-time embedding gets the same CUDA-13 fix.
             ensureOnnxRuntimeNodeMatchesSystem();
-            const { pipeline, env } = await import('@huggingface/transformers');
+            // The stack is an optionalDependency: npm prunes it when onnxruntime-node's
+            // postinstall can't reach api.nuget.org (#2370). Rethrow with actionable
+            // reinstall guidance instead of a raw ERR_MODULE_NOT_FOUND.
+            const { pipeline, env } = await import('@huggingface/transformers').catch((err) => {
+                const missing = getMissingLocalEmbeddingStackMessage(err);
+                if (missing)
+                    throw new Error(missing);
+                throw err;
+            });
             env.allowLocalModels = false;
             // Bridge user-controlled env vars to transformers.js: HF_HOME →
             // env.cacheDir, HF_ENDPOINT → env.remoteHost (#1205). Centralised in

package/dist/mcp/local/line-display.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Convert a 0-based GraphNode `startLine`/`endLine` to the 1-based line number
+ * shown to humans and LLMs in MCP tool output.
+ *
+ * Storage is 0-based (tree-sitter `startPosition.row`; see
+ * `ingestion/utils/line-base.ts`), which matches editors/`sed`/`less -N` only
+ * after `+ 1`. The `context`, `query`, and `impact` tools present line numbers a
+ * user cross-references against source, so they convert here at the response
+ * boundary (#2377).
+ *
+ * Apply ONLY to a symbol node's 0-based `startLine`/`endLine`. Do NOT apply to:
+ *   - BasicBlock / CFG `functionStartLine` and PDG statement lines — already
+ *     1-based (they use `startPosition.row + 1`);
+ *   - the internal `sym.startLine + 1` join params that target the 1-based
+ *     BasicBlock id space;
+ *   - raw `cypher` results, which pass LadybugDB columns through verbatim and
+ *     stay 0-based (documented).
+ *
+ * `undefined`/`null` pass through so optional line fields stay absent.
+ */
+export declare function toDisplayLine(zeroBasedLine: number): number;
+export declare function toDisplayLine(zeroBasedLine: number | null | undefined): number | undefined;

package/dist/mcp/local/line-display.js

@@ -0,0 +1,3 @@
+export function toDisplayLine(zeroBasedLine) {
+    return typeof zeroBasedLine === 'number' ? zeroBasedLine + 1 : undefined;
+}

package/dist/mcp/local/local-backend.d.ts

@@ -162,10 +162,24 @@ export declare class LocalBackend {
      * stderr noisy per DoD §2.8.
      */
     private warnedVectorUnsupported;
+    /**
+     * One-shot warning when a pruned or Node-unloadable optional embedding stack
+     * (#2370/#2372) forces semantic search to fall back to BM25 — so the
+     * degradation is visible once instead of silent.
+     */
+    private warnedMissingEmbeddingStack;
     /**
      * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
      */
     getGroupService(): GroupService;
+    /**
+     * Adapt local `trace` to the group port. The assembled group/cross-repo trace
+     * presents 1-based endpoints (via resolveSymbolForGroup), so convert the hop
+     * lines here too — otherwise one response mixes 1-based endpoints with 0-based
+     * hops (#2380). Single-repo `trace` dispatches directly (not through this
+     * port) and stays 0-based (documented full-parity follow-up).
+     */
+    private traceForGroup;
     /**
      * Adapt the shared symbol resolver to the GroupToolPort contract. Used by the
      * cross-repo trace path to locate which member repo an endpoint lives in and

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

@@ -10,6 +10,7 @@ import path from 'path';
 import { createHash } from 'crypto';
 import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, } from '../../core/lbug/pool-adapter.js';
 import { isValidQueryParams } from '../../core/lbug/query-params.js';
+import { toDisplayLine } from './line-display.js';
 import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
@@ -26,9 +27,11 @@ import { rankExactEmbeddingRows, } from '../../core/embeddings/exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
 import { getExactScanLimit, isVectorExtensionSupportedByPlatform, } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
+import { ftsDegradedWarning } from '../../core/search/fts-indexes.js';
 import { cjkSegmentationModeMismatch, containsSegmentableCjkRun, getSearchFTSCjkSegmentation, isSupportedCjkSegmentationMode, MAX_CJK_SEGMENTATION_QUERY_LENGTH, } from '../../core/search/cjk-segmentation.js';
 import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
 import { logger } from '../../core/logger.js';
+import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, } from '../../core/embeddings/runtime-support.js';
 import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT, } from '../tools.js';
 import { findImportCycles } from '../../core/graph/import-cycles.js';
 import { decodeTaintPath } from '../../core/ingestion/taint/path-codec.js';
@@ -434,6 +437,12 @@ export class LocalBackend {
      * stderr noisy per DoD §2.8.
      */
     warnedVectorUnsupported = false;
+    /**
+     * One-shot warning when a pruned or Node-unloadable optional embedding stack
+     * (#2370/#2372) forces semantic search to fall back to BM25 — so the
+     * degradation is visible once instead of silent.
+     */
+    warnedMissingEmbeddingStack = false;
     /**
      * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
      */
@@ -445,7 +454,7 @@ export class LocalBackend {
                 query: (r, p) => this.query(r, p),
                 impactByUid: (id, uid, d, o) => this.impactByUid(id, uid, d, o),
                 context: (r, p) => this.context(r, p),
-                trace: (r, p) => this.trace(r, p),
+                trace: (r, p) => this.traceForGroup(r, p),
                 resolveSymbol: (r, q) => this.resolveSymbolForGroup(r, q),
                 pdgFlows: (r, anchor, opts) => this.pdgFlowsForGroup(r, anchor, opts),
             };
@@ -453,6 +462,23 @@ export class LocalBackend {
         }
         return this.groupToolSvc;
     }
+    /**
+     * Adapt local `trace` to the group port. The assembled group/cross-repo trace
+     * presents 1-based endpoints (via resolveSymbolForGroup), so convert the hop
+     * lines here too — otherwise one response mixes 1-based endpoints with 0-based
+     * hops (#2380). Single-repo `trace` dispatches directly (not through this
+     * port) and stays 0-based (documented full-parity follow-up).
+     */
+    async traceForGroup(repo, params) {
+        const result = await this.trace(repo, params);
+        const hops = result.hops;
+        if (Array.isArray(hops)) {
+            for (const hop of hops) {
+                hop.startLine = toDisplayLine(hop.startLine);
+            }
+        }
+        return result;
+    }
     /**
      * Adapt the shared symbol resolver to the GroupToolPort contract. Used by the
      * cross-repo trace path to locate which member repo an endpoint lives in and
@@ -470,8 +496,8 @@ export class LocalBackend {
                     name: s.name,
                     type: s.type,
                     filePath: s.filePath,
-                    startLine: s.startLine,
-                    endLine: s.endLine,
+                    startLine: toDisplayLine(s.startLine),
+                    endLine: toDisplayLine(s.endLine),
                 },
             };
         }
@@ -483,7 +509,7 @@ export class LocalBackend {
                     name: c.name,
                     type: c.type,
                     filePath: c.filePath,
-                    startLine: c.startLine,
+                    startLine: toDisplayLine(c.startLine),
                 })),
             };
         }
@@ -1564,8 +1590,8 @@ export class LocalBackend {
                 name: sym.name,
                 type: sym.type,
                 filePath: sym.filePath,
-                startLine: sym.startLine,
-                endLine: sym.endLine,
+                startLine: toDisplayLine(sym.startLine),
+                endLine: toDisplayLine(sym.endLine),
                 ...(module ? { module } : {}),
                 ...(includeContent && content ? { content } : {}),
             };
@@ -1652,7 +1678,7 @@ export class LocalBackend {
         // path, leaving the success-path response shape byte-identical.
         const warnings = [];
         if (!ftsUsed) {
-            warnings.push('FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.');
+            warnings.push(ftsDegradedWarning());
         }
         // #2331: a CJK query against a server process resolving
         // GITNEXUS_FTS_CJK_SEGMENTATION to 'none' silently misses sub-phrase
@@ -1791,8 +1817,11 @@ export class LocalBackend {
                             name: sym.name || sym[1],
                             type: sym.type || sym[2],
                             filePath: sym.filePath || sym[3],
-                            startLine: sym.startLine || sym[4],
-                            endLine: sym.endLine || sym[5],
+                            // Raw 0-based here — `bm25Search` is only called from `query()`,
+                            // whose aggregation loop applies `toDisplayLine` once (see below).
+                            // Converting here too would double-shift BM25-matched lines (#2380).
+                            startLine: sym.startLine ?? sym[4],
+                            endLine: sym.endLine ?? sym[5],
                             bm25Score: bm25Result.score,
                         });
                     }
@@ -1927,8 +1956,20 @@ export class LocalBackend {
             }
             return results;
         }
-        catch {
-            // Expected when embeddings are disabled — silently fall back to BM25-only
+        catch (err) {
+            // Embeddings disabled is the common, silent case. But a pruned or
+            // Node-unloadable optional stack (#2370/#2372) also lands here — surface it
+            // once so semantic search doesn't silently degrade to BM25 with no hint
+            // (the exact silent-degradation mode #2370 exists to fix). Emitted once per
+            // LocalBackend instance to keep stderr quiet on hot paths (like the VECTOR
+            // fallback above). All other errors stay silent, as before.
+            const message = err instanceof Error ? err.message : '';
+            if (!this.warnedMissingEmbeddingStack &&
+                (isMissingLocalEmbeddingStackMessage(message) ||
+                    isLocalEmbeddingRuntimeBlockerMessage(message))) {
+                this.warnedMissingEmbeddingStack = true;
+                logger.warn(`GitNexus [query:vector]: ${message}`);
+            }
             return [];
         }
     }
@@ -2376,7 +2417,7 @@ export class LocalBackend {
                     name: c.name,
                     kind: c.type,
                     filePath: c.filePath,
-                    line: c.startLine,
+                    line: toDisplayLine(c.startLine),
                     score: Number(c.score.toFixed(2)),
                 })),
             };
@@ -2583,8 +2624,8 @@ export class LocalBackend {
                 name: sym.name || sym[1],
                 kind: symKind,
                 filePath: sym.filePath || sym[3],
-                startLine: sym.startLine || sym[4],
-                endLine: sym.endLine || sym[5],
+                startLine: toDisplayLine(sym.startLine ?? sym[4]),
+                endLine: toDisplayLine(sym.endLine ?? sym[5]),
                 ...(include_content && (sym.content || sym[6]) ? { content: sym.content || sym[6] } : {}),
                 ...(methodMetadata ? { methodMetadata } : {}),
             },
@@ -2660,7 +2701,7 @@ export class LocalBackend {
                         name: c.name,
                         kind: c.type,
                         filePath: c.filePath,
-                        line: c.startLine,
+                        line: toDisplayLine(c.startLine),
                         score: Number(c.score.toFixed(2)),
                     })),
                 },
@@ -2678,11 +2719,14 @@ export class LocalBackend {
             return {
                 anchorClause: 'a.id STARTS WITH $idPrefix AND a.startLine >= $symStart AND a.startLine <= $symEnd',
                 queryParams: { idPrefix, symStart: sym.startLine + 1, symEnd: sym.endLine + 1 },
+                // Display anchor is 1-based, matching the ambiguous-candidate branch and
+                // the context/query/impact tools (#2380). This is display-only — the
+                // BasicBlock join above uses the raw `sym.startLine + 1` in `symStart`.
                 anchor: {
                     file: sym.filePath,
                     symbol: sym.name,
-                    startLine: sym.startLine,
-                    endLine: sym.endLine,
+                    startLine: toDisplayLine(sym.startLine),
+                    endLine: toDisplayLine(sym.endLine),
                 },
             };
         }
@@ -4016,7 +4060,7 @@ export class LocalBackend {
                         name: c.name,
                         kind: c.type,
                         filePath: c.filePath,
-                        line: c.startLine,
+                        line: toDisplayLine(c.startLine),
                         score: Number(c.score.toFixed(2)),
                     })),
                 };
@@ -4069,7 +4113,7 @@ export class LocalBackend {
                     name: c.name,
                     kind: c.type,
                     filePath: c.filePath,
-                    line: c.startLine,
+                    line: toDisplayLine(c.startLine),
                     score: Number(c.score.toFixed(2)),
                     impactedCount: summary?.impactedCount ?? 0,
                     risk: summary?.risk ?? 'UNKNOWN',

package/dist/mcp/local/pdg-impact.d.ts

@@ -34,8 +34,10 @@ export declare function splitCalleeIds(raw: unknown): string[];
  * Contract version of the mode:'pdg' impact result shape. A stable discriminator
  * for external MCP/agent consumers — distinct from the DB INCREMENTAL_SCHEMA_VERSION.
  * Bump on any breaking change to the PDG result fields.
+ * v2: `startLine` in the result is now 1-based display (#2380), matching the
+ * context/query/impact tools (was 0-based).
  */
-export declare const PDG_RESULT_VERSION: 1;
+export declare const PDG_RESULT_VERSION: 2;
 /** A reachable dependence block resolved to its source statement. */
 export interface PdgStatement {
     /** 1-based source line where the statement's block starts. */
@@ -105,7 +107,7 @@ export interface PdgInterproceduralImpact {
 export interface PdgImpactBaseResult extends PdgImpactParityFields {
     mode: 'pdg';
     /** Contract version of the mode:'pdg' impact result shape; bump on any breaking change to the PDG result fields. */
-    pdgResultVersion: 1;
+    pdgResultVersion: 2;
     target: PdgImpactTarget;
     direction: 'upstream' | 'downstream';
     impactedCount: number;
@@ -172,7 +174,7 @@ export interface PdgImpactDegradedResult extends PdgImpactBaseResult {
 export interface PdgImpactErrorResult {
     mode?: 'pdg';
     /** Contract version of the mode:'pdg' impact result shape; bump on any breaking change to the PDG result fields. */
-    pdgResultVersion: 1;
+    pdgResultVersion: 2;
     error: string;
     target: PdgImpactTarget;
     direction: 'upstream' | 'downstream';

package/dist/mcp/local/pdg-impact.js

@@ -9,6 +9,7 @@ import path from 'path';
 import { loadMeta } from '../../storage/repo-manager.js';
 import { IMPACT_MAX_DEPTH, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT } from '../tools.js';
 import { CALLEES_TRUNCATED_SENTINEL, CALLEE_ID_SEP } from '../../core/ingestion/cfg/emit.js';
+import { toDisplayLine } from './line-display.js';
 import { decodeCallSummary } from '../../core/ingestion/taint/call-summary-codec.js';
 import { decodeReachingDefReason } from '../../core/ingestion/cfg/reaching-def-reason-codec.js';
 import { getProviderForFile } from '../../core/ingestion/languages/index.js';
@@ -84,8 +85,10 @@ export function splitCalleeIds(raw) {
  * Contract version of the mode:'pdg' impact result shape. A stable discriminator
  * for external MCP/agent consumers — distinct from the DB INCREMENTAL_SCHEMA_VERSION.
  * Bump on any breaking change to the PDG result fields.
+ * v2: `startLine` in the result is now 1-based display (#2380), matching the
+ * context/query/impact tools (was 0-based).
  */
-export const PDG_RESULT_VERSION = 1;
+export const PDG_RESULT_VERSION = 2;
 /**
  * FU-B-2 intra-block def→use line walk. Given a block's self REACHING_DEF
  * def→use line PAIRS (every `defLine → useLine` step decoded from the edge
@@ -519,7 +522,7 @@ function assemblePdgImpactResult(input) {
         name: s.name,
         type: s.type,
         filePath: s.filePath,
-        ...(s.startLine !== undefined ? { startLine: s.startLine } : {}),
+        ...(s.startLine !== undefined ? { startLine: toDisplayLine(s.startLine) } : {}),
         ...(s.ambiguous ? { ambiguous: true } : {}),
         ...(s.id === null ? { unresolved: true } : {}),
         pdgEvidence: (s.id === null ? 'degraded' : 'owner-projection'),

package/dist/mcp/resources.js

@@ -365,6 +365,7 @@ additional_node_types: "Multi-language: Struct, Enum, Macro, Typedef, Union, Nam
 
 node_properties:
   common: "name (STRING), filePath (STRING), startLine (INT32), endLine (INT32)"
+  line_numbers: "startLine/endLine on symbol nodes are 0-BASED (tree-sitter rows) in storage AND in raw Cypher results. The context, query, impact, group/cross-repo trace, and explain/pdg_query (symbol anchor) tools present them 1-BASED (editor / sed / less -N aligned), so a symbol spans editor lines (startLine+1)..(endLine+1) — e.g. sed '<startLine+1>,<endLine+1>!d' <file>. Single-repo trace symbol lines stay 0-BASED for now (full-parity follow-up). content holds the exact symbol span. (BasicBlock / PDG statement lines are separately 1-based.) (#2377, #2380)"
   Method: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL), visibility (STRING), isStatic (BOOL), isAbstract (BOOL), isFinal (BOOL), isVirtual (BOOL), isOverride (BOOL), isAsync (BOOL), isPartial (BOOL), requiredParameterCount (INT32), parameterTypes (STRING[]), annotations (STRING[])"
   Function: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL), visibility (STRING), isStatic (BOOL), isAbstract (BOOL), isFinal (BOOL), isAsync (BOOL), parameterTypes (STRING[]), annotations (STRING[])"
   Property: "declaredType (STRING) — the field's type annotation (e.g., 'Address', 'City'). Used for field-access chain resolution."

package/dist/mcp/tools.js

@@ -379,7 +379,7 @@ MODE (opt-in): "callgraph" (default) walks symbol→symbol edges (CALLS/IMPORTS/
 
 STATEMENT-ANCHORED PDG SLICE: with mode:'pdg', pass "line" (1-based source line within the target symbol) to seed the dependence slice on the statement at that line and return what depends on it in affectedStatements (line + text). Inter-procedural symbols are still reported through interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket. Without "line", pdg returns whole-symbol inter-procedural reach plus local whole-symbol PDG diagnostics.
 
-PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:1 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:1, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar.
+PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:2 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:2, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar.
 
 WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
 AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.

package/dist/server/analyze-launch.d.ts

@@ -17,6 +17,12 @@ export interface LaunchDeps {
     };
     acquireRepoLock: (key: string) => string | null;
     releaseRepoLock: (key: string) => void;
+    /**
+     * Drops the server's cached LadybugDB handle (closeLbug). The worker
+     * process rewrites the repo's DB files on disk, so a connection opened
+     * before the rewrite keeps reading the pre-rewrite state until evicted.
+     */
+    closeDbHandle: () => Promise<void>;
 }
 export interface LaunchOptions {
     force?: boolean;