gitnexus 1.6.9 → 1.6.10-aptos.0

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;
@@ -17,5 +24,29 @@ export declare function initialiseSearchFTSStemmer(): string;
  * tests) so validation always applies.
  */
 export declare function getSearchFTSStemmer(): string;
+/**
+ * Drop every configured FTS index (no-op per index when absent or unloadable
+ * — `dropFTSIndex` tolerates both). Callable ahead of any DML that mutates an
+ * FTS-indexed table's rows: LadybugDB's FTS extension is not proven to
+ * survive a DETACH DELETE against a table that still carries a live index
+ * from a prior run (#2589) — dropping first removes that hazard entirely,
+ * regardless of whether it also fixed a specific native inconsistency.
+ */
+export declare function dropSearchFTSIndexes(): Promise<void>;
 export declare function createSearchFTSIndexes(options?: CreateSearchFTSIndexesOptions): Promise<void>;
 export declare function verifySearchFTSIndexes(executeQuery: (cypher: string) => Promise<unknown[]>): Promise<string[]>;
+export interface BuildSearchIndexesResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Build + verify FTS indexes, catching any failure instead of letting it
+ * propagate. `createSearchFTSIndexes` re-tokenizes every stored row on every
+ * analyze run (see the `ponytail:` comment above) — a native LadybugDB
+ * tokenizer error on a single pre-existing row (e.g. a "Failed calling
+ * LOWER: Invalid UTF-8", #2544/#2546) must not discard an otherwise-
+ * successful analyze's graph/embeddings work. The caller degrades keyword
+ * search for this run instead, mirroring the existing FTS-extension-
+ * unavailable degrade path in `run-analyze.ts`.
+ */
+export declare function buildSearchIndexesOrDegrade(executeQuery: (cypher: string) => Promise<unknown[]>, options?: CreateSearchFTSIndexesOptions): Promise<BuildSearchIndexesResult>;

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
@@ -66,6 +103,19 @@ export function initialiseSearchFTSStemmer() {
 export function getSearchFTSStemmer() {
     return resolvedStemmer ?? resolveFTSStemmer();
 }
+/**
+ * Drop every configured FTS index (no-op per index when absent or unloadable
+ * — `dropFTSIndex` tolerates both). Callable ahead of any DML that mutates an
+ * FTS-indexed table's rows: LadybugDB's FTS extension is not proven to
+ * survive a DETACH DELETE against a table that still carries a live index
+ * from a prior run (#2589) — dropping first removes that hazard entirely,
+ * regardless of whether it also fixed a specific native inconsistency.
+ */
+export async function dropSearchFTSIndexes() {
+    for (const { table, indexName } of FTS_INDEXES) {
+        await dropFTSIndex(table, indexName);
+    }
+}
 export async function createSearchFTSIndexes(options) {
     const stemmer = getSearchFTSStemmer();
     for (const { table, indexName, properties } of FTS_INDEXES) {
@@ -115,3 +165,26 @@ export async function verifySearchFTSIndexes(executeQuery) {
     }
     return missing;
 }
+/**
+ * Build + verify FTS indexes, catching any failure instead of letting it
+ * propagate. `createSearchFTSIndexes` re-tokenizes every stored row on every
+ * analyze run (see the `ponytail:` comment above) — a native LadybugDB
+ * tokenizer error on a single pre-existing row (e.g. a "Failed calling
+ * LOWER: Invalid UTF-8", #2544/#2546) must not discard an otherwise-
+ * successful analyze's graph/embeddings work. The caller degrades keyword
+ * search for this run instead, mirroring the existing FTS-extension-
+ * unavailable degrade path in `run-analyze.ts`.
+ */
+export async function buildSearchIndexesOrDegrade(executeQuery, options) {
+    try {
+        await createSearchFTSIndexes(options);
+        const missing = await verifySearchFTSIndexes(executeQuery);
+        if (missing.length > 0) {
+            return { ok: false, error: `missing indexes after build: ${missing.join(', ')}` };
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}

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

@@ -37,4 +37,6 @@ export const FTS_INDEXES = [
     { table: 'Union', indexName: 'union_fts', properties: FTS_PROPERTIES },
     { table: 'Static', indexName: 'static_fts', properties: FTS_PROPERTIES },
     { table: 'Variable', indexName: 'variable_fts', properties: FTS_PROPERTIES },
+    // Move/Aptos module nodes also carry description/content columns.
+    { table: 'Module', indexName: 'module_fts', properties: FTS_PROPERTIES },
 ];

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/core/wiki/llm-client.d.ts

@@ -23,6 +23,8 @@ export interface LLMConfig {
     requestTimeoutMs?: number;
     /** Max fetch attempts before giving up (default: 3). */
     maxAttempts?: number;
+    /** Exact hostnames allowed for explicit http:// LLM endpoints. */
+    allowedInsecureHttpHosts?: readonly string[];
 }
 export interface LLMResponse {
     content: string;
@@ -40,6 +42,8 @@ export declare function resolveLLMConfig(overrides?: Partial<LLMConfig>): Promis
  * Estimate token count from text (rough heuristic: ~4 chars per token).
  */
 export declare function estimateTokens(text: string): number;
+export declare const LLM_ALLOW_INSECURE_CONNECTION_ENV = "GITNEXUS_ALLOW_INSECURE_CONNECTION";
+export declare function parseLLMAllowedInsecureHttpHosts(value: string | undefined): string[];
 /**
  * Validate that a base URL supplied for LLM API calls is a safe HTTP/HTTPS
  * endpoint (CWE-918 / CodeQL js/http-to-file-access).
@@ -47,15 +51,17 @@ export declare function estimateTokens(text: string): number;
  * Allowed:
  *  - https:// with any hostname (public LLM APIs, Azure, OpenRouter, …)
  *  - http:// restricted to localhost / 127.0.0.1 (local servers: Ollama, LiteLLM, …)
+ *  - http:// to exact hosts explicitly allowlisted for LAN/self-hosted LLMs
  *
  * Rejected:
  *  - file://, data:, javascript:, and any other non-HTTP scheme
- *  - http:// aimed at non-loopback hosts (avoids SSRF against internal networks)
+ *  - http:// aimed at non-loopback hosts unless explicitly allowlisted
+ *    (avoids SSRF against internal networks by default)
  *
  * Throws with a descriptive message on validation failure so callers surface a
  * clear error rather than an opaque network error.
  */
-export declare function validateLLMBaseUrl(baseUrl: string): void;
+export declare function validateLLMBaseUrl(baseUrl: string, allowedInsecureHttpHosts?: readonly string[]): void;
 /**
  * Returns true if the given base URL is an Azure OpenAI endpoint.
  * Uses proper hostname matching to avoid spoofed URLs like

package/dist/core/wiki/llm-client.js

@@ -43,6 +43,8 @@ export async function resolveLLMConfig(overrides) {
         provider: savedProvider ?? 'openai',
         apiVersion: overrides?.apiVersion || process.env.GITNEXUS_AZURE_API_VERSION || savedConfig.apiVersion,
         isReasoningModel: overrides?.isReasoningModel ?? savedConfig.isReasoningModel,
+        allowedInsecureHttpHosts: overrides?.allowedInsecureHttpHosts ??
+            parseLLMAllowedInsecureHttpHosts(process.env[LLM_ALLOW_INSECURE_CONNECTION_ENV]),
     };
 }
 /**
@@ -64,6 +66,36 @@ function isTimeoutLikeError(err) {
         return true;
     return /time(d)?\s*out|timeout/i.test(err.message);
 }
+export const LLM_ALLOW_INSECURE_CONNECTION_ENV = 'GITNEXUS_ALLOW_INSECURE_CONNECTION';
+function normalizeAllowedInsecureHttpHost(host) {
+    const trimmed = host.trim().toLowerCase();
+    const fail = () => {
+        throw new Error(`--allow-insecure-connection / ${LLM_ALLOW_INSECURE_CONNECTION_ENV} entries must be exact hostnames or IP addresses`);
+    };
+    if (!trimmed || /[/@?#]/.test(trimmed))
+        fail();
+    if (trimmed.startsWith('[')) {
+        if (!trimmed.endsWith(']'))
+            fail();
+        const normalized = trimmed.slice(1, -1);
+        if (!normalized || /[\[\]]/.test(normalized))
+            fail();
+        return normalized;
+    }
+    if (/[\[\]]/.test(trimmed))
+        fail();
+    if ((trimmed.match(/:/g)?.length ?? 0) === 1) {
+        // URL.hostname never includes the port, so accepting "host:port" would
+        // create a confusing no-op allowlist entry.
+        fail();
+    }
+    return trimmed;
+}
+export function parseLLMAllowedInsecureHttpHosts(value) {
+    if (value === undefined || value.trim() === '')
+        return [];
+    return [...new Set(value.split(',').map(normalizeAllowedInsecureHttpHost))];
+}
 /**
  * Validate that a base URL supplied for LLM API calls is a safe HTTP/HTTPS
  * endpoint (CWE-918 / CodeQL js/http-to-file-access).
@@ -71,15 +103,17 @@ function isTimeoutLikeError(err) {
  * Allowed:
  *  - https:// with any hostname (public LLM APIs, Azure, OpenRouter, …)
  *  - http:// restricted to localhost / 127.0.0.1 (local servers: Ollama, LiteLLM, …)
+ *  - http:// to exact hosts explicitly allowlisted for LAN/self-hosted LLMs
  *
  * Rejected:
  *  - file://, data:, javascript:, and any other non-HTTP scheme
- *  - http:// aimed at non-loopback hosts (avoids SSRF against internal networks)
+ *  - http:// aimed at non-loopback hosts unless explicitly allowlisted
+ *    (avoids SSRF against internal networks by default)
  *
  * Throws with a descriptive message on validation failure so callers surface a
  * clear error rather than an opaque network error.
  */
-export function validateLLMBaseUrl(baseUrl) {
+export function validateLLMBaseUrl(baseUrl, allowedInsecureHttpHosts = parseLLMAllowedInsecureHttpHosts(process.env[LLM_ALLOW_INSECURE_CONNECTION_ENV])) {
     let parsed;
     try {
         parsed = new URL(baseUrl);
@@ -96,9 +130,11 @@ export function validateLLMBaseUrl(baseUrl) {
         // Node's URL parser preserves IPv6 brackets in hostname (e.g. "[::1]"),
         // so strip them before comparing to bare address literals.
         const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
-        if (host !== 'localhost' && host !== '127.0.0.1' && host !== '::1') {
+        const allowedHosts = new Set(allowedInsecureHttpHosts.map(normalizeAllowedInsecureHttpHost));
+        if (host !== 'localhost' && host !== '127.0.0.1' && host !== '::1' && !allowedHosts.has(host)) {
             // Use parsed.origin (scheme+host+port, no credentials) instead of the full URL.
-            throw new Error(`Insecure http:// LLM base URLs are only allowed for localhost/127.0.0.1. ` +
+            throw new Error(`Insecure http:// LLM base URLs are only allowed for localhost/127.0.0.1 ` +
+                `or hosts listed by --allow-insecure-connection / ${LLM_ALLOW_INSECURE_CONNECTION_ENV}. ` +
                 `Use https:// for remote endpoints (got ${parsed.origin})`);
         }
     }
@@ -145,7 +181,7 @@ export function buildRequestUrl(baseUrl, apiVersion) {
  */
 export async function callLLM(prompt, config, systemPrompt, options) {
     // Validate base URL before any fetch (CodeQL js/http-to-file-access)
-    validateLLMBaseUrl(config.baseUrl);
+    validateLLMBaseUrl(config.baseUrl, config.allowedInsecureHttpHosts);
     const messages = [];
     if (systemPrompt) {
         messages.push({ role: 'system', content: systemPrompt });

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/http-transport.d.ts

@@ -23,6 +23,7 @@ import type { Server as HttpServer } from 'http';
 import { type Request, type Response, type NextFunction } from 'express';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { LocalBackend } from './local/local-backend.js';
+import { type McpRepositoryPolicy } from './repository-policy.js';
 /** HTTP server configuration options. */
 export interface McpHttpOptions {
     /** Listening port. */
@@ -31,6 +32,8 @@ export interface McpHttpOptions {
     host: string;
     /** Bearer auth token (optional; no auth when omitted). */
     authToken?: string;
+    /** Prevalidated repository policy shared by startup logging and transports. */
+    repositoryPolicy?: McpRepositoryPolicy;
 }
 /**
  * Creates a Bearer Token authentication middleware.
@@ -93,6 +96,7 @@ export declare function createStreamableHttpHandler(backend: LocalBackend, opts?
     createServer?: () => Server;
     host?: string;
     port?: number;
+    repositoryPolicy?: McpRepositoryPolicy;
 }): {
     handler: (req: Request, res: Response) => Promise<void>;
     cleanup: () => Promise<void>;
@@ -113,6 +117,7 @@ export declare function createSseHandlers(backend: LocalBackend, messagesPath?:
     maxSessions?: number;
     host?: string;
     port?: number;
+    repositoryPolicy?: McpRepositoryPolicy;
 }): {
     sseHandler: (req: Request, res: Response) => Promise<void>;
     messageHandler: (req: Request, res: Response) => Promise<void>;

package/dist/mcp/http-transport.js

@@ -27,6 +27,7 @@ import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { createMCPServer, installSignalShutdown } from './server.js';
 import { logger } from '../core/logger.js';
+import { createMcpRepositoryPolicy, mcpRepositoryPolicyConfigured, } from './repository-policy.js';
 /** Sessions idle longer than this are evicted. */
 const SESSION_TTL_MS = 30 * 60 * 1000;
 /** Cleanup sweep runs every 5 minutes. */
@@ -170,8 +171,14 @@ export function startIdleSweep(sessions, ttlMs, intervalMs) {
  * route mount in server/mcp-http.ts (/api/mcp).
  */
 export function createStreamableHttpHandler(backend, opts = {}) {
+    if (opts.createServer && !opts.repositoryPolicy && mcpRepositoryPolicyConfigured()) {
+        throw new Error('A custom MCP server factory cannot bypass configured repository policy.');
+    }
     // Seam: tests inject createServer to observe the per-session Server lifecycle.
-    const createServer = opts.createServer ?? (() => createMCPServer(backend));
+    let repositoryPolicy = opts.repositoryPolicy
+        ? Promise.resolve(opts.repositoryPolicy)
+        : undefined;
+    const getRepositoryPolicy = () => (repositoryPolicy ??= createMcpRepositoryPolicy(backend));
     // DNS-rebinding protection (Host-header allowlist) when the bind host is known.
     const dnsRebinding = dnsRebindingOptions(opts.host, opts.port);
     const sessions = new Map();
@@ -226,7 +233,9 @@ export function createStreamableHttpHandler(backend, opts = {}) {
                 sessionIdGenerator: () => randomUUID(),
                 ...dnsRebinding,
             });
-            const server = createServer();
+            const server = opts.createServer
+                ? opts.createServer()
+                : createMCPServer(backend, { repositoryPolicy: await getRepositoryPolicy() });
             await server.connect(transport);
             await transport.handleRequest(req, res, req.body);
             if (transport.sessionId) {
@@ -282,6 +291,10 @@ export function createStreamableHttpHandler(backend, opts = {}) {
  */
 export function createSseHandlers(backend, messagesPath = '/messages', opts = {}) {
     const maxSessions = opts.maxSessions ?? MAX_SESSIONS;
+    let repositoryPolicy = opts.repositoryPolicy
+        ? Promise.resolve(opts.repositoryPolicy)
+        : undefined;
+    const getRepositoryPolicy = () => (repositoryPolicy ??= createMcpRepositoryPolicy(backend));
     // DNS-rebinding protection (Host-header allowlist) when the bind host is known.
     const dnsRebinding = dnsRebindingOptions(opts.host, opts.port);
     const sseSessions = new Map();
@@ -300,7 +313,7 @@ export function createSseHandlers(backend, messagesPath = '/messages', opts = {}
         }
         // SSEServerTransport(endpoint, res, options): endpoint is the path clients POST to.
         const transport = new SSEServerTransport(messagesPath, res, dnsRebinding);
-        const server = createMCPServer(backend);
+        const server = createMCPServer(backend, { repositoryPolicy: await getRepositoryPolicy() });
         sseSessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() });
         transport.onclose = () => {
             sseSessions.delete(transport.sessionId);
@@ -370,6 +383,7 @@ export async function startMcpHttpServer(backend, options) {
             'Pass --auth-token (or set GITNEXUS_MCP_AUTH_TOKEN), or bind --host 127.0.0.1. ' +
             'This applies to --host 0.0.0.0 and --host :: as well.');
     }
+    const repositoryPolicy = options.repositoryPolicy ?? (await createMcpRepositoryPolicy(backend));
     const app = express();
     // Suppress X-Powered-By to reduce information leakage.
     app.disable('x-powered-by');
@@ -410,7 +424,7 @@ export async function startMcpHttpServer(backend, options) {
         res.json({ status: 'ok' });
     });
     // Streamable HTTP (modern MCP clients) at POST /mcp.
-    const streamable = createStreamableHttpHandler(backend, { host, port });
+    const streamable = createStreamableHttpHandler(backend, { host, port, repositoryPolicy });
     app.all('/mcp', auth, jsonBody, (req, res) => {
         void streamable.handler(req, res).catch((err) => {
             logger.error({ err }, 'MCP /mcp request failed');
@@ -424,7 +438,7 @@ export async function startMcpHttpServer(backend, options) {
         });
     });
     // Legacy SSE: GET /sse opens the stream; POST /messages receives JSON-RPC messages.
-    const sse = createSseHandlers(backend, '/messages', { host, port });
+    const sse = createSseHandlers(backend, '/messages', { host, port, repositoryPolicy });
     app.get('/sse', auth, (req, res) => {
         void sse.sseHandler(req, res).catch((err) => {
             logger.error({ err }, 'MCP /sse failed');

package/dist/mcp/local/bean-metadata.d.ts

@@ -0,0 +1,2 @@
+import { type SpringBeanMetadata } from '../../core/ingestion/frameworks/spring/bean-catalog.js';
+export declare function queryClassBeanMetadata(lbugPath: string, symbolId: string, symbolType: string): Promise<SpringBeanMetadata | undefined>;

package/dist/mcp/local/bean-metadata.js

@@ -0,0 +1,25 @@
+import { executeParameterized } from '../../core/lbug/pool-adapter.js';
+import { deriveSpringBeanMetadata, } from '../../core/ingestion/frameworks/spring/bean-catalog.js';
+export async function queryClassBeanMetadata(lbugPath, symbolId, symbolType) {
+    if (symbolType !== 'Class')
+        return undefined;
+    try {
+        const rows = await executeParameterized(lbugPath, `
+      MATCH (c:Class {id: $symbolId})
+      RETURN c.frameworkAnnotations AS frameworkAnnotations
+      LIMIT 1
+    `, { symbolId });
+        const row = rows[0];
+        if (!row)
+            return undefined;
+        const value = row.frameworkAnnotations ?? row[0];
+        if (!Array.isArray(value))
+            return undefined;
+        return deriveSpringBeanMetadata(value.filter((annotation) => typeof annotation === 'string'));
+    }
+    catch {
+        // Older or partially upgraded indexes may not have the column. This
+        // enrichment is additive, so context and impact must still succeed.
+        return undefined;
+    }
+}

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;
+}