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

package/dist/server/analyze-launch.js

@@ -10,16 +10,83 @@
  * path is resolved relative to `import.meta.url`.
  */
 import path from 'path';
+import { existsSync, statSync } from 'node:fs';
 import { fork } from 'child_process';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
-import { getStoragePath } from '../storage/repo-manager.js';
+import { canonicalizePath, getStoragePath, INDEX_METADATA_FILE, listRegisteredRepos, registryPathEquals, } from '../storage/repo-manager.js';
 import { logger } from '../core/logger.js';
 const _require = createRequire(import.meta.url);
 const MAX_WORKER_RETRIES = 2;
+/**
+ * The worker reports `complete` over IPC before its on-disk finalization
+ * (LadybugDB checkpoint + native handle release + metadata write) is visible
+ * at `getStoragePath(targetPath)` — observed up to ~6.5s behind the IPC
+ * message. Opening the database inside that window is what the pre-IPC
+ * ordering was meant to prevent and is actively dangerous: reads fail with
+ * binder errors or return an empty graph, the open can quarantine the
+ * in-flight WAL, and the native layer racing the rewrite has crashed the
+ * whole server (SIGSEGV-class exit, no output) on slow CI runners.
+ */
+const FINALIZE_SETTLE_TIMEOUT_MS = 60_000;
+const FINALIZE_SETTLE_POLL_MS = 200;
+/**
+ * Resolve once the analyzed repo's index is settled at `storagePath`: the
+ * LadybugDB file and metadata both exist AND were (re)written by THIS job
+ * (mtime >= jobStartMs — bare existence is not enough, a re-analysis leaves
+ * the previous index in place while it works), and no transient WAL/shadow/
+ * checkpoint sidecars remain (the worker's native close has finished).
+ *
+ * Never rejects. Timing out logs and proceeds (pre-gate behavior) rather
+ * than failing a job whose analysis genuinely succeeded — e.g. a no-op
+ * non-force analyze legitimately rewrites nothing.
+ */
+/**
+ * Look up the analyzed repo's registered storage path. The request's
+ * user-provided path is used only as a comparison key; the filesystem probes
+ * below run against the registry's own `storagePath` — the server-owned
+ * record readers resolve through, and not a user-controlled value
+ * (CodeQL js/path-injection).
+ */
+const registeredStoragePath = async (targetPath) => {
+    const target = canonicalizePath(path.resolve(targetPath));
+    const entries = await listRegisteredRepos();
+    const entry = entries.find((e) => registryPathEquals(canonicalizePath(e.path), target));
+    return entry?.storagePath ?? null;
+};
+const waitForSettledIndex = async (targetPath, jobStartMs) => {
+    const settled = (storagePath) => {
+        try {
+            const lbugStat = statSync(path.join(storagePath, 'lbug'));
+            const metaStat = statSync(path.join(storagePath, INDEX_METADATA_FILE));
+            return (lbugStat.mtimeMs >= jobStartMs &&
+                metaStat.mtimeMs >= jobStartMs &&
+                ['lbug.wal', 'lbug.shadow', 'lbug.wal.checkpoint'].every((f) => !existsSync(path.join(storagePath, f))));
+        }
+        catch {
+            return false; // not written yet
+        }
+    };
+    const deadline = Date.now() + FINALIZE_SETTLE_TIMEOUT_MS;
+    for (;;) {
+        // Re-resolved each round: the worker registers the repo as part of the
+        // finalization this gate is waiting out.
+        const storagePath = await registeredStoragePath(targetPath);
+        if (storagePath && settled(storagePath))
+            return;
+        if (Date.now() > deadline) {
+            logger.warn({ targetPath }, 'analyze finalization not visible after timeout; completing job anyway');
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, FINALIZE_SETTLE_POLL_MS));
+    }
+};
 export function createLaunchAnalysisWorker(deps) {
-    const { jobManager, backend, acquireRepoLock, releaseRepoLock } = deps;
+    const { jobManager, backend, acquireRepoLock, releaseRepoLock, closeDbHandle } = deps;
     return function launchAnalysisWorker(job, targetPath, opts) {
+        // For waitForSettledIndex: files (re)written by this job have mtimes at or
+        // after this instant. Taken before the fork so no worker write predates it.
+        const jobStartMs = Date.now();
         // Acquire shared repo lock (keyed on storagePath to match embed handler)
         const analyzeLockKey = getStoragePath(targetPath);
         const lockErr = acquireRepoLock(analyzeLockKey);
@@ -67,10 +134,17 @@ export function createLaunchAnalysisWorker(deps) {
                 }
                 else if (msg.type === 'complete') {
                     releaseRepoLock(analyzeLockKey);
-                    // Reinitialize backend BEFORE marking complete — ensures the new repo
-                    // is queryable when the client receives the SSE complete event.
-                    backend
-                        .init()
+                    // Before marking complete: (1) wait for the worker's on-disk
+                    // finalization to settle (see waitForSettledIndex), (2) evict the
+                    // cached DB handle — same invalidation DELETE /api/repo performs, a
+                    // handle opened before the rewrite reads pre-rewrite state — and
+                    // only then (3) reinitialize the backend. This makes the ordering
+                    // comment below true in practice: the repo is actually queryable
+                    // when the client receives the SSE complete event.
+                    waitForSettledIndex(targetPath, jobStartMs)
+                        .then(() => closeDbHandle())
+                        .catch(() => { }) // best-effort: eviction failure must not fail the job
+                        .then(() => backend.init())
                         .then(() => {
                         jobManager.updateJob(job.id, { status: 'complete', repoName: msg.result.repoName });
                     })
@@ -84,6 +158,8 @@ export function createLaunchAnalysisWorker(deps) {
                 }
                 else if (msg.type === 'error') {
                     releaseRepoLock(analyzeLockKey);
+                    // A failed (force) analyze may still have rewritten DB files first.
+                    void closeDbHandle().catch(() => { });
                     jobManager.updateJob(job.id, { status: 'failed', error: msg.message });
                 }
             });

package/dist/server/api.d.ts

@@ -8,7 +8,9 @@
  * CORS is restricted to localhost, private/LAN networks, and the deployed site.
  */
 import express from 'express';
+import { type RegistryEntry } from '../storage/repo-manager.js';
 import { type GraphNode, type GraphRelationship } from '../_shared/index.js';
+import { JobManager } from './analyze-job.js';
 /**
  * Determine whether an HTTP Origin header value is allowed by CORS policy.
  *
@@ -49,6 +51,34 @@ export declare const registerWebUI: (app: express.Express, staticDir: string | n
 export declare const writeNdjsonRecord: (res: express.Response, record: GraphStreamRecord, signal?: AbortSignal) => Promise<void>;
 export declare const getNodeQuery: (table: string, includeContent: boolean) => string;
 export declare const streamGraphNdjson: (res: express.Response, includeContent?: boolean, signal?: AbortSignal) => Promise<void>;
+/**
+ * Mount an SSE progress endpoint for a JobManager.
+ * Handles: initial state, terminal events, heartbeat, event IDs, client disconnect.
+ *
+ * Terminal payloads carry `repoPath` (the analyzed path) alongside the display
+ * `repoName` so clients can reconnect by path identity — with duplicate
+ * basenames, a name-only reconnect resolves to the first same-named sibling.
+ * Exported for unit tests that lock the wire payload shape.
+ */
+export declare const mountSSEProgress: (app: express.Express, routePath: string, jm: JobManager) => void;
+/**
+ * Resolve a `?repo=` request param against the registry in two tiers:
+ *
+ *   1. Path claim — any input containing a separator ('/' or '\\', which
+ *      cover path.sep on every platform) is treated as a path claim and
+ *      resolved by canonical registry path ONLY. A miss fails closed
+ *      (null, never a basename fallback) so a stale or wrong path can
+ *      never silently retarget a same-named sibling repo (#2419).
+ *      Within this tier, only absolute or Windows-shaped ('\\') claims
+ *      are worth canonicalizing; relative claims like 'org/name' or
+ *      './repo' are rejected immediately WITHOUT touching the filesystem
+ *      — canonicalizing them would run an attacker-influenced
+ *      CWD-relative realpathSync probe on un-rate-limited GET routes,
+ *      and no legitimate caller sends relative paths.
+ *   2. Name fallback — bare names (no separators) keep the legacy
+ *      basename/name match for older callers.
+ */
+export declare const resolveRegisteredRepoEntry: (repos: RegistryEntry[], repoName?: string) => RegistryEntry | null;
 /**
  * Handle a GET /api/file request body. Extracted from createServer's route
  * registration so it can be unit-tested without spinning up an HTTP server

package/dist/server/api.js

@@ -12,12 +12,13 @@ import cors from 'cors';
 import path from 'path';
 import fs from 'fs/promises';
 import { createRequire } from 'node:module';
-import { loadMeta, listRegisteredRepos, getStoragePath } from '../storage/repo-manager.js';
+import { canonicalizePath, cloneDirBelongsToEntry, loadMeta, listRegisteredRepos, getStoragePath, registryPathEquals, } from '../storage/repo-manager.js';
 import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, flushWAL, closeLbug, withLbugDb, isReadOnlyDbError, } from '../core/lbug/lbug-adapter.js';
 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';
@@ -380,8 +381,13 @@ export const streamGraphNdjson = async (res, includeContent = false, signal) =>
 /**
  * Mount an SSE progress endpoint for a JobManager.
  * Handles: initial state, terminal events, heartbeat, event IDs, client disconnect.
+ *
+ * Terminal payloads carry `repoPath` (the analyzed path) alongside the display
+ * `repoName` so clients can reconnect by path identity — with duplicate
+ * basenames, a name-only reconnect resolves to the first same-named sibling.
+ * Exported for unit tests that lock the wire payload shape.
  */
-const mountSSEProgress = (app, routePath, jm) => {
+export const mountSSEProgress = (app, routePath, jm) => {
     app.get(routePath, (req, res) => {
         let jobId;
         try {
@@ -411,6 +417,7 @@ const mountSSEProgress = (app, routePath, jm) => {
             eventId++;
             res.write(`id: ${eventId}\nevent: ${job.status}\ndata: ${JSON.stringify({
                 repoName: job.repoName,
+                repoPath: job.repoPath,
                 error: job.error,
             })}\n\n`);
             res.end();
@@ -434,6 +441,7 @@ const mountSSEProgress = (app, routePath, jm) => {
                     const eventJob = jm.getJob(jobId);
                     res.write(`id: ${eventId}\nevent: ${progress.phase}\ndata: ${JSON.stringify({
                         repoName: eventJob?.repoName,
+                        repoPath: eventJob?.repoPath,
                         error: eventJob?.error,
                     })}\n\n`);
                     clearInterval(heartbeat);
@@ -476,6 +484,43 @@ const requestedRepo = (req) => {
     }
     return undefined;
 };
+const repoParamBasename = (repoName) => repoName.replace(/\\/g, '/').split('/').filter(Boolean).pop() ?? repoName;
+/**
+ * Resolve a `?repo=` request param against the registry in two tiers:
+ *
+ *   1. Path claim — any input containing a separator ('/' or '\\', which
+ *      cover path.sep on every platform) is treated as a path claim and
+ *      resolved by canonical registry path ONLY. A miss fails closed
+ *      (null, never a basename fallback) so a stale or wrong path can
+ *      never silently retarget a same-named sibling repo (#2419).
+ *      Within this tier, only absolute or Windows-shaped ('\\') claims
+ *      are worth canonicalizing; relative claims like 'org/name' or
+ *      './repo' are rejected immediately WITHOUT touching the filesystem
+ *      — canonicalizing them would run an attacker-influenced
+ *      CWD-relative realpathSync probe on un-rate-limited GET routes,
+ *      and no legitimate caller sends relative paths.
+ *   2. Name fallback — bare names (no separators) keep the legacy
+ *      basename/name match for older callers.
+ */
+export const resolveRegisteredRepoEntry = (repos, repoName) => {
+    if (!repoName)
+        return repos[0] ?? null;
+    const looksLikePath = path.isAbsolute(repoName) || repoName.includes('/') || repoName.includes('\\');
+    if (looksLikePath) {
+        // Relative path claims fail closed with zero filesystem probes.
+        if (!path.isAbsolute(repoName) && !repoName.includes('\\'))
+            return null;
+        const requestedPath = canonicalizePath(repoName);
+        const pathMatch = repos.find((r) => registryPathEquals(canonicalizePath(r.path), requestedPath));
+        if (pathMatch)
+            return pathMatch;
+        return null;
+    }
+    const normalizedName = repoParamBasename(repoName);
+    return (repos.find((r) => r.name === normalizedName) ||
+        repos.find((r) => r.name.toLowerCase() === normalizedName.toLowerCase()) ||
+        null);
+};
 /**
  * Handle a GET /api/file request body. Extracted from createServer's route
  * registration so it can be unit-tested without spinning up an HTTP server
@@ -702,6 +747,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
         backend,
         acquireRepoLock,
         releaseRepoLock,
+        closeDbHandle: closeLbug,
     });
     /**
      * Maximum time the hold-queue will wait for an active analysis job to complete.
@@ -712,19 +758,8 @@ export const createServer = async (port, host = '127.0.0.1') => {
     // Pass `req` to enable early exit if the client disconnects during the hold-queue wait.
     const resolveRepo = async (repoName, isRetry = false, req) => {
         const repos = await listRegisteredRepos();
-        let found = null;
-        // Normalize: if a full path is passed, extract just the basename.
-        // e.g. "C:\Users\LENOVO\.gitnexus\repos\todo.txt-cli" -> "todo.txt-cli"
-        const normalizedName = repoName ? path.basename(repoName) : undefined;
-        if (normalizedName) {
-            found =
-                repos.find((r) => r.name === normalizedName) ||
-                    repos.find((r) => r.name.toLowerCase() === normalizedName.toLowerCase()) ||
-                    null;
-        }
-        else if (repos.length > 0) {
-            found = repos[0]; // default to first repo
-        }
+        const found = resolveRegisteredRepoEntry(repos, repoName);
+        const normalizedName = repoName ? repoParamBasename(repoName) : undefined;
         // If not yet in the registry, check whether a background job is actively cloning or
         // analyzing this repo. Hold the connection open (up to 5 minutes) until it completes.
         // We only wait for in-progress jobs ('queued'|'cloning'|'analyzing') — a 'complete' job
@@ -757,7 +792,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         if (currentJob.status === 'complete') {
                             await backend.init();
                             const freshRepos = await listRegisteredRepos();
-                            return freshRepos.find((r) => r.name === normalizedName) || null;
+                            return resolveRegisteredRepoEntry(freshRepos, repoName);
                         }
                         await new Promise((r) => setTimeout(r, 1000));
                     }
@@ -774,7 +809,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 logger.debug({ repoName: String(normalizedName).replace(/[\r\n]/g, ' ') }, '[debug] resolveRepo 404, triggering deep init');
             }
             await backend.init();
-            return await resolveRepo(normalizedName, true, req);
+            return await resolveRepo(repoName, true, req);
         }
         return found;
     };
@@ -826,6 +861,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
             res.json(repos.map((r) => ({
                 name: r.name,
                 path: r.path,
+                repoPath: r.path,
                 indexedAt: r.indexedAt,
                 lastCommit: r.lastCommit,
                 stats: r.stats,
@@ -836,7 +872,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
         }
     });
     // Get repo info
-    app.get('/api/repo', async (req, res) => {
+    // Rate-limited (CodeQL js/missing-rate-limiting): resolveRepo canonicalizes
+    // the attacker-supplied ?repo= param (realpathSync probe for absolute /
+    // Windows-shaped claims). Default 60 rpm/IP — web callers hit this route
+    // only on connect/switch, never in a polling loop.
+    app.get('/api/repo', createRouteLimiter(), async (req, res) => {
         try {
             const entry = await resolveRepo(requestedRepo(req), false, req);
             if (!entry) {
@@ -906,7 +946,10 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 catch {
                     /* repo name not eligible for a clone dir (local repo) */
                 }
-                if (cloneDir) {
+                // Only remove the clone dir when it is *this* entry's path — a local
+                // repo registered under the same name would otherwise take a cloned
+                // sibling's checkout down with it (see cloneDirBelongsToEntry).
+                if (cloneDir && cloneDirBelongsToEntry(cloneDir, entry.path)) {
                     try {
                         const stat = await fs.stat(cloneDir);
                         if (stat.isDirectory()) {
@@ -1140,8 +1183,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

@@ -54,6 +54,18 @@ export declare const canonicalizePath: (p: string) => string;
  * lookups/dedup/finalize checks all share so they answer identically.
  */
 export declare const registryPathEquals: (a: string, b: string) => boolean;
+/**
+ * Does the clone dir derived from an entry's *name* actually belong to that
+ * entry? Registry names are not unique across storage locations: a cloned
+ * repo under `~/.gitnexus/repos/<name>` and a local repo registered under the
+ * same name share a `getCloneDir(entry.name)` result. The server's delete
+ * handler must therefore never remove the clone dir based on the name alone —
+ * only when the entry's own `path` resolves to that dir (mirroring its step-2b
+ * rule that cleanup is driven off `entry.path`, so a same-named sibling's
+ * clone is never removed). Both sides are canonicalised so symlinked or
+ * differently-spelled forms of the same dir still match.
+ */
+export declare const cloneDirBelongsToEntry: (cloneDir: string, entryPath: string) => boolean;
 export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
@@ -74,6 +86,33 @@ export interface RepoMeta {
         processes?: number;
         embeddings?: number;
     };
+    /**
+     * Capability stamps for what THIS analyze run actually produced (mirrors
+     * the meta literal in run-analyze.ts — typed here so the stamp site is
+     * compile-checked; tri-review 4669518496 P1/U3: `vectorSearch.status`
+     * must never claim 'vector-index' unless the run verified or recreated
+     * the HNSW index). Forensic today — no programmatic readers (`doctor`
+     * prints platform-derived capabilities, query routing never consults
+     * meta). The status unions mirror `CapabilityStatus` /
+     * `SemanticSearchMode` in core/platform/capabilities.ts; inlined to keep
+     * storage/ free of a core/ type dependency.
+     */
+    capabilities?: {
+        graph: {
+            provider: string;
+            status: 'available' | 'degraded' | 'unavailable';
+        };
+        fts: {
+            provider: string;
+            status: 'available' | 'degraded' | 'unavailable';
+        };
+        vectorSearch: {
+            provider: string;
+            status: 'vector-index' | 'exact-scan' | 'unavailable';
+            exactScanLimit: number;
+            reason?: string;
+        };
+    };
     /**
      * Bumped whenever incremental-indexing invariants change in an
      * incompatible way (delete-and-rewrite logic, subgraph extraction,
@@ -110,9 +149,29 @@ export interface RepoMeta {
     incrementalInProgress?: {
         /** When the run started (epoch ms). */
         startedAt: number;
+        /** Last dirty-flag refresh (epoch ms). */
+        updatedAt?: number;
         /** Number of files in the writable set, for diagnostic logs.
          *  `0` on the full-rebuild path (no incremental write set exists). */
         toWriteCount: number;
+        /** Last completed writeback phase before the process stopped. */
+        phase?: string;
+        /** Directly changed/added files before importer expansion. */
+        directWriteCount?: number;
+        /** Extra files pulled into the writable set by importer BFS. */
+        importerExpansion?: number;
+        /** Files in the effective write set after graph-boundary expansion. */
+        effectiveWriteCount?: number;
+        /** Files whose persisted rows were scheduled for deletion. */
+        deleteCount?: number;
+        /** Added-file shadow seeds included in importer BFS. */
+        shadowSeedCount?: number;
+        /** Importer-BFS chunks dropped by failed IMPORTS queries (#2410 +
+         *  tri-review 4669518496 P2-5). Stamped only when > 0: a dropped chunk
+         *  means the importer expansion silently shrank, so a crash's
+         *  diagnostics must show whether the write set was already
+         *  under-expanded when the run died. */
+        droppedImporterChunks?: number;
     };
     /**
      * Name of the git branch this index represents (#2106). Absent for the
@@ -242,8 +301,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

@@ -71,6 +71,18 @@ export const canonicalizePath = (p) => {
  * lookups/dedup/finalize checks all share so they answer identically.
  */
 export const registryPathEquals = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+/**
+ * Does the clone dir derived from an entry's *name* actually belong to that
+ * entry? Registry names are not unique across storage locations: a cloned
+ * repo under `~/.gitnexus/repos/<name>` and a local repo registered under the
+ * same name share a `getCloneDir(entry.name)` result. The server's delete
+ * handler must therefore never remove the clone dir based on the name alone —
+ * only when the entry's own `path` resolves to that dir (mirroring its step-2b
+ * rule that cleanup is driven off `entry.path`, so a same-named sibling's
+ * clone is never removed). Both sides are canonicalised so symlinked or
+ * differently-spelled forms of the same dir still match.
+ */
+export const cloneDirBelongsToEntry = (cloneDir, entryPath) => registryPathEquals(canonicalizePath(cloneDir), canonicalizePath(entryPath));
 /**
  * Bumped whenever incremental-indexing invariants change incompatibly.
  * v2: `BasicBlock.callees` column added (statement-precise inter-procedural
@@ -90,8 +102,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);

package/hooks/claude/gitnexus-hook.cjs

@@ -349,6 +349,49 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
   });
 }
 
+/**
+ * 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 (sendHookResponse) 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;
+}
+
 /**
  * PreToolUse handler — augment searches with graph context.
  */
@@ -385,18 +428,25 @@ function handlePreToolUse(input) {
   let result = '';
   try {
     if (hasGitNexusServerOwner(gitNexusDir)) {
-      // Normal skip path: the MCP server owns the DB, so the CLI augment would
-      // contend on the lock. Stay silent for strict hook runners (issue #1913);
-      // surface the reason only when diagnostics are explicitly requested.
+      // #2396: the MCP server holds the DB write lock, so a competing CLI
+      // `augment` would only contend on it (LadybugDB is single-writer). But the
+      // session that triggered this hook has the GitNexus MCP tools live — route
+      // the augmentation to the agent via additionalContext instead of silently
+      // doing nothing. Mirror the skip reason to stderr only under GITNEXUS_DEBUG
+      // (strict-runner contract, #1913); the hint itself rides the sanctioned
+      // additionalContext stdout channel the successful augment already uses.
       if (isDebugEnabled()) {
         process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
       }
-      return;
-    }
-    const cliPath = resolveCliPath();
-    const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
-    if (!child.error && child.status === 0) {
-      result = extractAugmentContext(child.stderr || '');
+      if (shouldEmitMcpHint(gitNexusDir)) {
+        result = buildMcpQueryHint(pattern);
+      }
+    } else {
+      const cliPath = resolveCliPath();
+      const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
+      if (!child.error && child.status === 0) {
+        result = extractAugmentContext(child.stderr || '');
+      }
     }
   } catch {
     /* graceful failure */