gitnexus 1.6.9 → 1.6.10-rc.10

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/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/api.js

@@ -18,6 +18,7 @@ import { isValidQueryParams } from '../core/lbug/query-params.js';
 import { NODE_TABLES } from '../_shared/index.js';
 import { searchFTSFromLbug } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
+import { ftsDegradedWarning } from '../core/search/fts-indexes.js';
 import { LocalBackend } from '../mcp/local/local-backend.js';
 import { mountMCPEndpoints } from './mcp-http.js';
 import { fileURLToPath } from 'url';
@@ -1140,8 +1141,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
             }, { readOnly: true });
             const response = { results: results.searchResults ?? results };
             if (results.ftsAvailable === false) {
-                response.warning =
-                    'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.';
+                response.warning = ftsDegradedWarning();
             }
             res.json(response);
         }

package/dist/storage/parse-cache.js

@@ -52,7 +52,7 @@ import { fileURLToPath } from 'url';
 // the main thread (the #1983 OOM). Because the two stores share this version,
 // any future change to the `ParsedFile` serialization shape MUST bump
 // SCHEMA_BUMP so both invalidate in lockstep.
-const SCHEMA_BUMP = 10; // PR #2200: Property nodes gained `rawDeclaredType` + `annotations` (Spring DI); warm caches must invalidate or the DI phase silently no-ops on replayed pre-upgrade nodes
+const SCHEMA_BUMP = 12; // #2391 follow-up: extractPythonModuleConstants changed what it EMITS for the same source (binding mutual-exclusivity clears stale imports; RHS refs are snapshotted; `$imp$N` aliases). `moduleConstants` is cached verbatim, so a warm shard built pre-fix would replay stale/WRONG folds and the correctness fixes would silently no-op on upgrade — bump to force re-extraction. (11 = #2391: ExtractedDecoratorRoute gained `routePathExpr`/`routePathOperands` + ParseWorkerResult gained per-file `moduleConstants`. 10 = PR #2200: Property nodes gained `rawDeclaredType` + `annotations` for Spring DI)
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from

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

@@ -242,8 +242,13 @@ export interface RepoMeta {
  * URL-only id). The incremental writeback preserves unchanged-file rows, so a
  * top-up against a pre-v5 index would strand old url-keyed Route nodes alongside
  * new composite-keyed ones — force a full re-analyze instead.
+ * v6: line-number storage flipped to uniform 0-based for the last 1-based
+ * GraphNode emitters — COBOL/JCL/markdown/scope (#2377/#2379/#2380). Incremental
+ * writeback preserves unchanged-file rows, so a top-up against a pre-v6 index
+ * would MIX old 1-based rows with new 0-based ones — and the 1-based MCP display
+ * would render the stale rows one line too high — so force a full re-analyze.
  */
-export declare const INCREMENTAL_SCHEMA_VERSION = 5;
+export declare const INCREMENTAL_SCHEMA_VERSION = 6;
 export interface IndexedRepo {
     repoPath: string;
     storagePath: string;

package/dist/storage/repo-manager.js

@@ -90,8 +90,13 @@ export const registryPathEquals = (a, b) => process.platform === 'win32' ? a.toL
  * URL-only id). The incremental writeback preserves unchanged-file rows, so a
  * top-up against a pre-v5 index would strand old url-keyed Route nodes alongside
  * new composite-keyed ones — force a full re-analyze instead.
+ * v6: line-number storage flipped to uniform 0-based for the last 1-based
+ * GraphNode emitters — COBOL/JCL/markdown/scope (#2377/#2379/#2380). Incremental
+ * writeback preserves unchanged-file rows, so a top-up against a pre-v6 index
+ * would MIX old 1-based rows with new 0-based ones — and the 1-based MCP display
+ * would render the stale rows one line too high — so force a full re-analyze.
  */
-export const INCREMENTAL_SCHEMA_VERSION = 5;
+export const INCREMENTAL_SCHEMA_VERSION = 6;
 const GITNEXUS_DIR = '.gitnexus';
 const GITNEXUS_EXCLUDE_ENTRY = `${GITNEXUS_DIR}/`;
 export const INDEX_METADATA_FILE = 'gitnexus.json';

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -391,6 +391,49 @@ function buildAfterToolContext(input) {
   return parts.length > 0 ? parts.join('\n\n') : null;
 }
 
+/**
+ * Fallback augmentation for the #2396 path: when a GitNexus process holds the
+ * lbug DB write lock the CLI `augment` can't run, so point the agent at the MCP
+ * `query` tool instead. Phrased conditionally ("if the MCP tools are live") so it
+ * stays truthful on every owner path — a confirmed MCP owner, a `serve` owner, or
+ * a fail-closed probe where no server is actually confirmed. `pattern` is embedded
+ * verbatim; the caller (writeAdditionalContext) JSON-escapes it structurally.
+ */
+function buildMcpQueryHint(pattern) {
+  return (
+    `[GitNexus] Local augment is unavailable (the graph DB is held by another ` +
+    `GitNexus process). If the GitNexus MCP tools are live in this session, call ` +
+    `the GitNexus \`query\` MCP tool (e.g. mcp__gitnexus__query) with ` +
+    `search_query "${pattern}".`
+  );
+}
+
+/**
+ * #2396 throttle: emit the MCP-query hint at most once per repo per window, so an
+ * owner-locked session isn't nudged on every search. Window (ms) via
+ * GITNEXUS_MCP_HINT_THROTTLE_MS (default 10min; 0/invalid disables). Best-effort —
+ * any fs error falls back to emitting.
+ * ponytail: per-repo mtime marker, shared across concurrent sessions on the same
+ * repo; add per-session dedup only if that sharing becomes a problem.
+ */
+function shouldEmitMcpHint(gitNexusDir) {
+  const raw = process.env.GITNEXUS_MCP_HINT_THROTTLE_MS;
+  const windowMs = raw === undefined || raw === '' ? 600000 : Number(raw);
+  if (!Number.isFinite(windowMs) || windowMs <= 0) return true;
+  const marker = path.join(gitNexusDir, '.mcp-hint-shown');
+  try {
+    if (Date.now() - fs.statSync(marker).mtimeMs < windowMs) return false;
+  } catch {
+    /* marker missing/unreadable → emit */
+  }
+  try {
+    fs.writeFileSync(marker, '');
+  } catch {
+    /* best-effort; still emit */
+  }
+  return true;
+}
+
 function runAugment(gitNexusDir, cwd, pattern) {
   // Acquire the per-repo slot BEFORE the DB-owner probe (#2163): the probe
   // itself spawns lsof/ps, so it must be bounded by the same ≤3-per-repo cap
@@ -410,12 +453,16 @@ function runAugment(gitNexusDir, cwd, pattern) {
   }
   try {
     if (hasGitNexusServerOwner(gitNexusDir)) {
-      // Normal skip path: the MCP server owns the DB. Stay silent for strict
-      // hook runners (issue #1913); surface the reason only under GITNEXUS_DEBUG.
+      // #2396: the MCP server holds the DB write lock, so a competing CLI
+      // `augment` would only contend on it (LadybugDB is single-writer). The
+      // session has the GitNexus MCP tools live — route the augmentation to the
+      // agent via additionalContext instead of dropping it. Mirror the skip
+      // reason to stderr only under GITNEXUS_DEBUG (strict-runner contract,
+      // #1913); the hint itself rides the sanctioned additionalContext channel.
       if (isDebugEnabled()) {
         process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
       }
-      return '';
+      return shouldEmitMcpHint(gitNexusDir) ? buildMcpQueryHint(pattern) : '';
     }
     const cliPath = resolveCliPath();
     const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);