gitnexus 1.6.10-rc.80 → 1.6.10-rc.82

package/dist/cli/analyze.js

@@ -14,7 +14,7 @@ import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { isLbugReady, LbugWipeError } from '../core/lbug/lbug-adapter.js';
 import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
-import { getOsPageSize, isLbugCheckpointIoError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
+import { getOsPageSize, isLbugCheckpointIoError, isLbugCheckpointBusyError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir, getDefaultBranch } from '../storage/git.js';
 import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
@@ -1236,7 +1236,15 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             return;
         }
         if (isLbugCheckpointIoError(err)) {
+            // #2599: when the checkpoint IO error also looks busy/locked, another
+            // handle holds the store open — name that actionable cause alongside the
+            // threshold hint (the original error is preserved so the hint still fires).
+            const heldOpen = isLbugCheckpointBusyError(err)
+                ? `  Another process may hold the store open (a running \`gitnexus mcp\` server, or a\n` +
+                    `  stale reader) — close other GitNexus processes on this repo, then retry.\n`
+                : '';
             cliError(`  LadybugDB failed while rotating/removing WAL checkpoint files.\n` +
+                heldOpen +
                 `  This can happen when auto-checkpoint runs at the default threshold (~16MB).\n` +
                 `  Retry with a larger checkpoint threshold to reduce checkpoint frequency:\n` +
                 `    gitnexus analyze --wal-checkpoint-threshold ${RECOMMENDED_WAL_CHECKPOINT_THRESHOLD}\n` +

package/dist/core/group/bridge-db.js

@@ -829,6 +829,8 @@ const LBUG_OPEN_RETRY_PATTERNS = [
     'could not set lock',
     'lock held by another process',
 ];
+// Cross-repo bridge RO open retry. Catalogued as entry 5 of the lbug-config
+// retry-budget registry; caps back-off so total wait ~3s.
 const LBUG_OPEN_RETRY_ATTEMPTS = 10;
 const LBUG_OPEN_RETRY_BASE_MS = 100;
 /** Cap individual back-off delays so the total wait is bounded (~3s). */

package/dist/core/lbug/lbug-config.d.ts

@@ -128,6 +128,15 @@ export interface LbugConnectionHandle {
  * import directly from this module — no re-export to keep in sync.
  */
 export declare const isDbBusyError: (err: unknown) => boolean;
+/**
+ * True when a WAL-checkpoint IO error ALSO carries a busy/lock signal — the
+ * rotation failed because another handle (a `gitnexus mcp` server, or this
+ * process's own reader) holds the store's WAL open, rather than a permanent
+ * disk error. Reuses `isDbBusyError`'s already-tested keyword set instead of a
+ * fresh regex, so an unmatched message degrades to "IO error" rather than
+ * silently claiming a held-open cause. (#2599)
+ */
+export declare const isLbugCheckpointBusyError: (err: unknown) => boolean;
 /** See {@link classifyDeleteAllError}. */
 export type DeleteAllErrorClass = 'benign-missing-table' | 'rethrow';
 /**

package/dist/core/lbug/lbug-config.js

@@ -582,6 +582,27 @@ export const isDbBusyError = (err) => {
         msg.includes('already in use') ||
         msg.includes('only one write transaction at a time'));
 };
+/**
+ * True when a WAL-checkpoint IO error ALSO carries a busy/lock signal — the
+ * rotation failed because another handle (a `gitnexus mcp` server, or this
+ * process's own reader) holds the store's WAL open, rather than a permanent
+ * disk error. Reuses `isDbBusyError`'s already-tested keyword set instead of a
+ * fresh regex, so an unmatched message degrades to "IO error" rather than
+ * silently claiming a held-open cause. (#2599)
+ */
+export const isLbugCheckpointBusyError = (err) => {
+    if (!isLbugCheckpointIoError(err))
+        return false;
+    // Anchor to real held-open wording rather than isDbBusyError's broad
+    // `.includes('lock')`, which matches the DB PATH embedded in the checkpoint
+    // error message (e.g. a repo under `blockchain-app`) and would misclassify a
+    // pure disk fault as held-open (#2614 LOW).
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (msg.includes('could not set lock') ||
+        msg.includes('lock is held') ||
+        msg.includes('being used by another process') ||
+        msg.includes('is busy'));
+};
 /**
  * Classify an error thrown while clearing all relationships of one type
  * before an incremental re-write (`deleteAllRelationshipsOfType` in
@@ -652,6 +673,18 @@ const OPEN_LOCK_RETRY_DELAY_MS = 100;
 export const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
 export const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
 const HANDLE_RELEASE_LOCK_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+// Retry-budget registry, part 2 (retry-budget consolidation): the remaining
+// open-time lock retries live next to their call sites but are catalogued here
+// so all lbug retry budgets surface in one grep. They retry the same lock class
+// as 1–3 ("Could not set lock" while a writer rebuilds the index):
+//   4. LOCK_RETRY_ATTEMPTS / LOCK_RETRY_DELAY_MS  (pool-adapter.ts)
+//      → read pool's read-only open while `gitnexus analyze` is writing
+//        (3 attempts, linear 2s·n back-off ≈ 6s total)
+//   5. LBUG_OPEN_RETRY_ATTEMPTS / _BASE_MS / _MAX_MS  (group/bridge-db.ts)
+//      → cross-repo bridge RO open race (10 attempts, linear 100ms·n capped
+//        at 500ms ≈ 3.5s total)
+// Kept in-file (not moved here) so explicit `lbug-config` test mocks don't have
+// to enumerate them; change a budget in its call site and update this catalogue.
 /**
  * Test-fixture directory prefixes recognized by `isTestFixturePath`.
  *

package/dist/core/lbug/pool-adapter.d.ts

@@ -15,6 +15,21 @@
  * from the same Database is the officially supported concurrency pattern.
  */
 import lbug from '@ladybugdb/core';
+/** Filesystem identity used to detect an index rebuilt/mutated under a live
+ *  read pool. `ino` catches a full-rebuild unlink+recreate or an atomic-rename
+ *  swap; `mtimeMs`+`size` catch an in-place incremental writeback. */
+interface DbIdentity {
+    ino: number;
+    mtimeMs: number;
+    size: number;
+}
+export declare function statDbIdentity(dbPath: string): Promise<DbIdentity | null>;
+/** True only when both identities are known AND differ. A stat failure
+ *  (ENOENT during the brief unlink window of a full rebuild) yields false, so
+ *  the reader keeps serving its still-valid open inode until the NEW file
+ *  appears with a different identity — avoiding a churn into a failed reopen
+ *  mid-rebuild. */
+export declare function dbIdentityChanged(prev: DbIdentity | null, next: DbIdentity | null): boolean;
 /**
  * Listeners notified when a pool entry is torn down (LRU eviction, idle
  * timeout, explicit close). Used by upper layers (e.g. the BM25 search
@@ -87,7 +102,14 @@ export declare function restoreStdout(): void;
  * Concurrent calls for the same repoId are deduplicated — the second caller
  * awaits the first's in-progress init rather than starting a redundant one.
  */
-export declare const initLbug: (repoId: string, dbPath: string) => Promise<void>;
+/**
+ * Returns `true` when this call (re)opened a fresh handle onto the current
+ * on-disk file, `false` when it reused/served the existing handle (unchanged,
+ * or changed-but-a-query-is-in-flight). Callers that gate their own freshness
+ * bookkeeping on "did the pool actually roll over" (LocalBackend) use the
+ * return value; callers that only need the pool ready can ignore it.
+ */
+export declare const initLbug: (repoId: string, dbPath: string) => Promise<boolean>;
 /**
  * Initialize a pool entry from a pre-existing Database object.
  *

package/dist/core/lbug/pool-adapter.js

@@ -20,6 +20,25 @@ import { isReadOnlyDbError, loadFTSExtension } from './lbug-adapter.js';
 import { closeQueryResults } from './query-result-utils.js';
 import { createLbugDatabase, isWalCorruptionError, toNativeSafePath, WAL_RECOVERY_SUGGESTION, } from './lbug-config.js';
 import { guardWalQuarantine, isMissingFsError, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, statIfExists, } from './sidecar-recovery.js';
+export async function statDbIdentity(dbPath) {
+    try {
+        const s = await fs.stat(dbPath);
+        return { ino: s.ino, mtimeMs: s.mtimeMs, size: s.size };
+    }
+    catch {
+        return null;
+    }
+}
+/** True only when both identities are known AND differ. A stat failure
+ *  (ENOENT during the brief unlink window of a full rebuild) yields false, so
+ *  the reader keeps serving its still-valid open inode until the NEW file
+ *  appears with a different identity — avoiding a churn into a failed reopen
+ *  mid-rebuild. */
+export function dbIdentityChanged(prev, next) {
+    if (!prev || !next)
+        return false;
+    return prev.ino !== next.ino || prev.mtimeMs !== next.mtimeMs || prev.size !== next.size;
+}
 const pool = new Map();
 const poolCloseListeners = new Set();
 /**
@@ -306,7 +325,16 @@ setInterval(() => {
 function createConnection(db) {
     silenceStdout();
     try {
-        return new lbug.Connection(db);
+        const conn = new lbug.Connection(db);
+        // Bound a single query at the engine level so a pathological query cannot
+        // hang a pooled connection past the JS-side Promise.race guard (which frees
+        // the waiter but not the native call). Matches QUERY_TIMEOUT_MS. Guarded so
+        // test doubles that don't model the engine method don't break connection
+        // creation.
+        if (typeof conn.setQueryTimeout === 'function') {
+            conn.setQueryTimeout(QUERY_TIMEOUT_MS);
+        }
+        return conn;
     }
     finally {
         restoreStdout();
@@ -316,6 +344,8 @@ function createConnection(db) {
 const QUERY_TIMEOUT_MS = 30_000;
 /** Waiter queue timeout in milliseconds */
 const WAITER_TIMEOUT_MS = 15_000;
+// Read-only open retry while `gitnexus analyze` writes. Catalogued as entry 4
+// of the lbug-config retry-budget registry.
 const LOCK_RETRY_ATTEMPTS = 3;
 const LOCK_RETRY_DELAY_MS = 2000;
 const SHADOW_REPLAY_PROBE_QUERY = 'MATCH (n) RETURN n LIMIT 1';
@@ -502,18 +532,46 @@ const initPromises = new Map();
  * Concurrent calls for the same repoId are deduplicated — the second caller
  * awaits the first's in-progress init rather than starting a redundant one.
  */
+/**
+ * Returns `true` when this call (re)opened a fresh handle onto the current
+ * on-disk file, `false` when it reused/served the existing handle (unchanged,
+ * or changed-but-a-query-is-in-flight). Callers that gate their own freshness
+ * bookkeeping on "did the pool actually roll over" (LocalBackend) use the
+ * return value; callers that only need the pool ready can ignore it.
+ */
 export const initLbug = async (repoId, dbPath) => {
     const existing = pool.get(repoId);
     if (existing) {
         existing.lastUsed = Date.now();
-        return;
+        // Detect an index that `analyze` rebuilt or mutated under this live read
+        // pool. Without this, the pool keeps serving the old (POSIX:
+        // unlinked-but-open) inode until LRU/idle eviction — a stale-read window
+        // of up to IDLE_TIMEOUT_MS after analyze finishes.
+        const current = await statDbIdentity(dbPath);
+        if (!dbIdentityChanged(existing.dbIdentity, current))
+            return false; // unchanged → reuse
+        // A query is in flight on this entry; closing its connection (and the
+        // shared Database at refCount 0) mid-use is a native use-after-free. Serve
+        // the current handle for this dispatch — the next initLbug that finds the
+        // entry idle (checkedOut === 0) reopens, since the identity stays divergent
+        // until then. Under sustained overlapping queries `checkedOut` may never
+        // reach 0 and `lastUsed` keeps the idle timer from evicting, so this window
+        // is bounded by the load, not IDLE_TIMEOUT_MS — the data stays consistent
+        // (a complete older snapshot), just not the newest. Callers that route
+        // freshness THROUGH initLbug (rather than calling closeLbug directly) get
+        // this guard for free; that is why LocalBackend delegates here (#2614).
+        if (existing.checkedOut > 0)
+            return false;
+        closeOne(repoId); // idle & changed → evict, then fall through to reopen the new file
     }
     // Deduplicate concurrent init calls for the same repoId —
     // prevents double-init race when multiple parallel tool calls
     // trigger initialization for the same repo simultaneously.
     const pending = initPromises.get(repoId);
-    if (pending)
-        return pending;
+    if (pending) {
+        await pending;
+        return true;
+    }
     const promise = doInitLbug(repoId, dbPath);
     initPromises.set(repoId, promise);
     try {
@@ -522,6 +580,7 @@ export const initLbug = async (repoId, dbPath) => {
     finally {
         initPromises.delete(repoId);
     }
+    return true;
 };
 /**
  * Internal init — creates DB, pre-warms connections, loads FTS, then registers pool.
@@ -540,6 +599,21 @@ async function doInitLbug(repoId, dbPath) {
     // Reuse an existing native Database if another repoId already opened this path.
     // This prevents buffer manager exhaustion from multiple mmap regions on the same file.
     let shared = dbCache.get(dbPath);
+    if (shared && !shared.external && shared.dbIdentity) {
+        // #2614 F2: a cached read-only Database is keyed by dbPath and shared across
+        // pool consumers. If the on-disk index was rebuilt/swapped (new inode) while
+        // ANOTHER consumer still holds this handle (refCount kept it alive), reusing
+        // it serves a superseded index. Unreachable via the MCP backend (one
+        // consumer per lbugPath ⇒ refCount hits 0 ⇒ closeOne reopens fresh); a
+        // complete fix needs per-inode handles rather than a dbPath-keyed cache.
+        // Surface it so the corner is observable instead of silently stale.
+        const current = await statDbIdentity(dbPath);
+        if (dbIdentityChanged(shared.dbIdentity, current)) {
+            realStderrWrite(`GitNexus: reusing a shared read-only handle for ${dbPath} whose on-disk ` +
+                `index was rebuilt while another consumer holds it — results may be stale ` +
+                `until that consumer releases it.\n`);
+        }
+    }
     if (!shared) {
         // Open in read-only mode — MCP server never writes to the database.
         // This allows multiple MCP server instances to read concurrently, and
@@ -548,7 +622,7 @@ async function doInitLbug(repoId, dbPath) {
         for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
             try {
                 const db = await openReadOnlyDatabase(dbPath);
-                shared = { db, refCount: 0, ftsLoaded: false };
+                shared = { db, refCount: 0, ftsLoaded: false, dbIdentity: await statDbIdentity(dbPath) };
                 dbCache.set(dbPath, shared);
                 break;
             }
@@ -557,7 +631,12 @@ async function doInitLbug(repoId, dbPath) {
                 if (isWalCorruptionError(lastError)) {
                     try {
                         const db = await tryQuarantineAndReopen(dbPath, repoId);
-                        shared = { db, refCount: 0, ftsLoaded: false };
+                        shared = {
+                            db,
+                            refCount: 0,
+                            ftsLoaded: false,
+                            dbIdentity: await statDbIdentity(dbPath),
+                        };
                         dbCache.set(dbPath, shared);
                         break;
                     }
@@ -611,6 +690,9 @@ async function doInitLbug(repoId, dbPath) {
     // Register pool entry only after all connections are pre-warmed and FTS is
     // loaded.  Concurrent executeQuery calls see either "not initialized"
     // (and throw cleanly) or a fully ready pool — never a half-built one.
+    // Record the on-disk identity so a later initLbug can detect an analyze
+    // rebuild/mutation and re-open onto the new file (pool staleness invalidation).
+    const dbIdentity = await statDbIdentity(dbPath);
     pool.set(repoId, {
         db,
         available,
@@ -618,6 +700,7 @@ async function doInitLbug(repoId, dbPath) {
         waiters: [],
         lastUsed: Date.now(),
         dbPath,
+        dbIdentity,
         closed: false,
     });
     ensureIdleTimer();
@@ -673,6 +756,8 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
         waiters: [],
         lastUsed: Date.now(),
         dbPath,
+        // Injected/external DB (tests) — not tracked for rebuild invalidation.
+        dbIdentity: null,
         closed: false,
     });
     ensureIdleTimer();

package/dist/core/lbug/wal-checkpoint-driver.js

@@ -97,6 +97,9 @@ export const runCheckpointWithRetry = async (options = {}) => {
         }
     }
     logger.warn({ attempts: CHECKPOINT_RETRY_ATTEMPTS }, 'GitNexus: manual WAL checkpoint exhausted retry budget — surfacing IO error to caller');
+    // The held-open cause (#2599) is named at the CLI layer (analyze.ts) where the
+    // --wal-checkpoint-threshold recovery hint already renders, so the original IO
+    // error is preserved intact for that classifier rather than re-wrapped here.
     throw lastError;
 };
 /**

package/dist/core/run-analyze.js

@@ -10,6 +10,7 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
+import { retryRename } from '../storage/fs-atomic.js';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFiles, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, deleteAllInjects, queryImportersBatch, loadFTSExtension, wipeLbugDbFiles, LbugWipeError, DELETE_FILES_CHUNK_SIZE, } from './lbug/lbug-adapter.js';
@@ -20,7 +21,7 @@ import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSea
 import { getExtensionCapabilities, resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { diagnoseExtensionLoad } from './lbug/extension-load-error.js';
 import { startWalCheckpointDriver, checkpointOnce, } from './lbug/wal-checkpoint-driver.js';
-import { quarantineSidecarsForDirtyRecovery } from './lbug/sidecar-recovery.js';
+import { quarantineSidecarsForDirtyRecovery, inspectLbugSidecars, } from './lbug/sidecar-recovery.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, adoptFlatBranchLabel, isReadOnlyFilesystemError, isRepoRegistered, cleanupOldKuzuFiles, reconcileMetadataFiles, isMissingFilesystemError, INDEX_METADATA_FILE, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { DEFAULT_PDG_MAX_FUNCTION_LINES } from './ingestion/cfg/collect.js';
 import { DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_CDG_EDGES_PER_FUNCTION, } from './ingestion/cfg/emit.js';
@@ -901,6 +902,50 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
     const hashDiff = isIncremental
         ? diffFileHashes(newFileHashes, existingMeta.fileHashes)
         : undefined;
+    // #2 atomic index publish: on a full rebuild, build the fresh DB at a temp
+    // path and swap it over the live index in one rename at the very end, so a
+    // concurrent MCP reader opening mid-build only ever sees the previous
+    // complete index (never a wiped/half-built file) and a crash leaves the old
+    // index intact. The whole build flows through the singleton connection, so
+    // only initLbug/wipeLbugDbFiles below take the temp target.
+    //
+    // POSIX only: the common CLI/serve-worker analyze paths skip the native close
+    // (closeLbugBeforeExit, #2264) and leave the build handle open at swap time.
+    // POSIX renames an open file cleanly; a same-process open handle blocks the
+    // rename on Windows. Windows keeps the current in-place behavior
+    // (buildPath === lbugPath, no swap) until that is resolved (see §12/follow-up).
+    const isFullRebuild = !(isIncremental && hashDiff);
+    // Where the swap is allowed:
+    //  - POSIX renames an open file, so the usual skip-native-close (#2264) is
+    //    fine and the swap always applies.
+    //  - Windows can swap only when a real close is safe to release the build
+    //    handle before the rename — i.e. NOT a --pdg run (the #2264 destructor
+    //    crash). Unverified on Windows CI; falls back to in-place otherwise.
+    const posixSwap = process.platform !== 'win32';
+    // #2614 Windows: the forced real-close before the rename re-bets that #2264 is
+    // --pdg-only, which is unproven (the CLI/worker skip the native close
+    // UNCONDITIONALLY) and unverifiable without a Windows runner. Keep it opt-in
+    // (GITNEXUS_ATOMIC_WINDOWS_SWAP=1) so the default Windows analyze stays on the
+    // proven in-place path; enable it only to test the Windows swap.
+    const windowsSwapOk = process.platform === 'win32' &&
+        options.pdg !== true &&
+        process.env.GITNEXUS_ATOMIC_WINDOWS_SWAP === '1';
+    // Incremental atomicity copies the whole index into the temp before mutating
+    // it, which negates incremental's speed premise — so it is opt-in
+    // (GITNEXUS_ATOMIC_INCREMENTAL=1) pending a benchmark. Full rebuilds always
+    // swap where the platform allows.
+    const wantAtomicIncremental = isIncremental && !!hashDiff && process.env.GITNEXUS_ATOMIC_INCREMENTAL === '1';
+    // #2614 F3: the copy-then-swap stages ONLY the main lbug file, so a live index
+    // carrying an orphan .wal/.shadow (a silently-failed prior checkpoint) would
+    // be copied incompletely and lose that delta. Only take the atomic path when
+    // the live index is a consolidated single file; otherwise fall back to the
+    // in-place writeback, which the next open replays correctly.
+    const atomicIncremental = wantAtomicIncremental && (await inspectLbugSidecars(lbugPath)).kind === 'clean';
+    if (wantAtomicIncremental && !atomicIncremental) {
+        log('atomic-incremental: live index carries orphan sidecars — using in-place writeback');
+    }
+    const useAtomicSwap = (isFullRebuild || atomicIncremental) && (posixSwap || windowsSwapOk);
+    const buildPath = useAtomicSwap ? `${lbugPath}.new` : lbugPath;
     if (isIncremental && hashDiff) {
         log(`Incremental: changed=${hashDiff.changed.length}, ` +
             `added=${hashDiff.added.length}, ` +
@@ -919,6 +964,14 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
                 directWriteCount: hashDiff.toWrite.length,
             },
         });
+        if (atomicIncremental) {
+            // Stage the live index into the temp so the in-place delete/writeback
+            // below mutates the COPY, and the end-of-run swap publishes it atomically.
+            // Clear any stale temp first (a crashed run), then copy the (consolidated,
+            // single-file) live index. Whole-file copy — hence opt-in.
+            await wipeLbugDbFiles(buildPath);
+            await fs.copyFile(lbugPath, buildPath);
+        }
     }
     else {
         // Full rebuild path: wipe DB files first.
@@ -949,7 +1002,12 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
         // valve below can never drift. Failures now throw a typed LbugWipeError
         // (ENOENT-verified removal) instead of silently letting initLbug reopen
         // a still-populated DB this run believes it wiped.
-        await wipeLbugDbFiles(lbugPath);
+        //
+        // With the atomic swap (POSIX), this wipes the TEMP build target
+        // (`buildPath` = `<lbugPath>.new`, clearing any stragglers from a crashed
+        // run) and leaves the live index untouched until the end-of-run swap. On
+        // Windows buildPath === lbugPath, so this is the original in-place wipe.
+        await wipeLbugDbFiles(buildPath);
     }
     // Size the buffer pool to the graph just built by the pipeline (a page cache
     // over the on-disk index, which scales with node/edge count) instead of the
@@ -958,7 +1016,9 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
     // the pool; env override / no-hint paths are unchanged. See
     // resolveBufferManagerSize / estimateBufferPool.
     setBufferPoolSizeHint(estimateBufferPool(pipelineResult.graph.nodeCount + pipelineResult.graph.relationshipCount));
-    await initLbug(lbugPath);
+    // Full rebuild (POSIX) builds into the temp `buildPath`; incremental and
+    // Windows use `buildPath === lbugPath` in place.
+    await initLbug(buildPath);
     // Manual WAL checkpoint driver (#1741): periodically drain the WAL
     // from JS so the un-retriable native auto-checkpoint almost never
     // has work left to do. Failures of the manual CHECKPOINT are absorbed
@@ -1191,8 +1251,8 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
                 // to replace wholesale.
                 await walCheckpointDriver.stop();
                 await closeLbug();
-                await wipeLbugDbFiles(lbugPath);
-                await initLbug(lbugPath);
+                await wipeLbugDbFiles(buildPath);
+                await initLbug(buildPath);
                 walCheckpointDriver = startWalCheckpointDriver();
                 await loadGraphToLbug(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
                     lbugMsgCount++;
@@ -1726,7 +1786,11 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
         // inside the resolver, and a mismatch leaves the dirty flag intact so the
         // next run takes the established full-recovery path.
         meta.runnerIdentity = finalizeAnalyzerRunnerIdentity(import.meta.url, runnerIdentity);
-        await saveMeta(metaDir, meta);
+        // #2614 F1: the freshness stamp (saveMeta) is written AFTER the atomic swap
+        // below — never here — so a concurrent MCP reader can't observe
+        // meta.indexedAt = T_new while lbugPath still resolves to the pre-swap
+        // inode (which latched the reader on the stale index permanently). The meta
+        // object is fully computed at this point; only its write is deferred.
         // Persist the incremental parse cache for the next run. Wraps in
         // try/catch so a cache-write failure never breaks an otherwise
         // successful indexing run. Prune stale chunk-hash entries first so
@@ -1850,7 +1914,54 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
         // LadybugDB destructor double-free after --pdg writes — closeLbugBeforeExit
         // CHECKPOINTs for durability then leaves the handles for process exit to
         // reclaim (#2264). Long-lived callers close for real.
-        await (options.skipNativeCloseOnExit ? closeLbugBeforeExit() : closeLbug());
+        //
+        // On Windows a swap must release the build handle before the rename (a
+        // same-process open file can't be renamed), so it forces a real close —
+        // safe because windowsSwapOk excludes --pdg (the #2264 case). POSIX renames
+        // an open file, so it keeps the skip-native-close there.
+        const forceRealCloseForSwap = useAtomicSwap && process.platform === 'win32';
+        await (options.skipNativeCloseOnExit && !forceRealCloseForSwap
+            ? closeLbugBeforeExit()
+            : closeLbug());
+        // #2 atomic publish: the fresh index was built at buildPath (a full rebuild,
+        // or an opt-in atomic incremental that copied the live index in first). Swap
+        // it over the live lbugPath in one rename so an MCP reader that opened
+        // mid-build only ever saw the previous complete index — never a wiped/
+        // half-built file. The close above checkpoint-consolidated buildPath to a
+        // single file (no .wal), so the rename publishes a complete index; a reader
+        // holding the old inode keeps a consistent stale snapshot until the pool
+        // re-opens onto the new one (the pool staleness invalidation). Runs only on
+        // success — a thrown error skips this, leaving the live index intact and the
+        // temp build to be cleared by the next run's wipe.
+        // Only publish if the build actually produced a DB at buildPath. A
+        // degenerate run (empty repo, or a mocked pipeline that never opened the
+        // store) leaves nothing to swap — skip rather than throw ENOENT.
+        const builtDbExists = useAtomicSwap
+            ? await fs.stat(buildPath).then(() => true, () => false)
+            : false;
+        if (useAtomicSwap && builtDbExists) {
+            await retryRename(buildPath, lbugPath);
+            // Clear any sidecars orphaned beside the replaced file. A cleanly-closed
+            // prior index has none; a crashed one could, and it would be replay
+            // poison next to the freshly published index. Best-effort.
+            for (const suffix of ['.wal', '.shadow', '.wal.checkpoint']) {
+                await fs.rm(`${lbugPath}${suffix}`, { force: true }).catch(() => { });
+            }
+            // #2614 F4: if the final checkpoint silently failed, the build may still
+            // carry a residual .wal/.shadow under the temp name. MOVE it beside the
+            // published index (not orphan/delete it) so the next open replays the
+            // delta, rather than leaving it under a name LadybugDB never reconciles.
+            for (const suffix of ['.wal', '.shadow']) {
+                await fs.rename(`${buildPath}${suffix}`, `${lbugPath}${suffix}`).catch(() => { });
+            }
+        }
+        // #2614 F1: stamp the freshness metadata now that the index is published.
+        // When meta.indexedAt becomes visible, lbugPath already resolves to the new
+        // inode, so a reader reiniting on the stamp opens the fresh graph rather
+        // than latching on the old one. Leaving the dirty flag set across the swap
+        // is a crash-safety improvement: a failed swap leaves the previous index
+        // live and the next run recovers via the full-rebuild path.
+        await saveMeta(metaDir, meta);
         progress('done', 100, 'Done');
         return {
             repoName: projectName,

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

@@ -147,6 +147,7 @@ export declare class LocalBackend {
     private reinitPromises;
     private lastStalenessCheck;
     private lastObservedIndexedAt;
+    private lastObservedDbIdentity;
     private groupToolSvc;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by

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

@@ -8,7 +8,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { createHash } from 'crypto';
-import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, } from '../../core/lbug/pool-adapter.js';
+import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, statDbIdentity, dbIdentityChanged, } from '../../core/lbug/pool-adapter.js';
 import { queryClassBeanMetadata } from './bean-metadata.js';
 import { isValidQueryParams } from '../../core/lbug/query-params.js';
 import { toDisplayLine } from './line-display.js';
@@ -470,6 +470,11 @@ export class LocalBackend {
     // not persist across calls and the staleness check would reinit forever
     // (#2106).
     lastObservedIndexedAt = new Map();
+    // #2614 F1: file identity of the lbug the pool last opened. An atomic swap or
+    // an in-place incremental changes the inode; reiniting on that reinit-covers
+    // the window where meta.indexedAt hasn't caught up (and the incremental case),
+    // so a rebuilt index is never served stale even when the stamp looks current.
+    lastObservedDbIdentity = new Map();
     groupToolSvc = null;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by
@@ -755,6 +760,7 @@ export class LocalBackend {
             this.initializedRepos.delete(key);
             this.lastStalenessCheck.delete(key);
             this.lastObservedIndexedAt.delete(key);
+            this.lastObservedDbIdentity.delete(key);
             this.reinitPromises.delete(key);
             closeLbug(key).catch(() => { });
         }
@@ -1114,23 +1120,38 @@ export class LocalBackend {
                 // Reading the flat meta for a branch handle would compare the branch
                 // index's indexedAt against the primary's and thrash the pool (#2106).
                 const meta = await loadMeta(path.dirname(repo.lbugPath));
-                if (!meta)
-                    return;
                 // Compare against the last indexedAt OBSERVED for this pool (keyed by
                 // lbugPath), not the handle's — branch handles are fresh spreads so a
                 // handle mutation would not persist and would reinit on every check.
                 const observed = this.lastObservedIndexedAt.get(poolKey) ?? repo.indexedAt;
-                if (meta.indexedAt && meta.indexedAt !== observed) {
-                    // Index was rebuilt — close stale connection and re-init.
-                    // Wrap in reinitPromises to prevent TOCTOU race where concurrent
-                    // callers both detect staleness and double-close the pool.
+                const stampChanged = !!meta?.indexedAt && meta.indexedAt !== observed;
+                // #2614 F1: also reinit on a file-identity change. An atomic swap (or an
+                // in-place incremental) changes the lbug inode; keying only on
+                // meta.indexedAt let a reader that reinited inside the pre-swap window
+                // latch on the old inode forever (its stamp already == meta.indexedAt).
+                const currentIdentity = await statDbIdentity(repo.lbugPath);
+                const identityChanged = dbIdentityChanged(this.lastObservedDbIdentity.get(poolKey) ?? null, currentIdentity);
+                if (stampChanged || identityChanged) {
+                    // Index was rebuilt/swapped — DELEGATE the close/reopen to the pool's
+                    // initLbug, which refuses to evict (and close the shared Database)
+                    // while a query is in flight (its checkedOut>0 guard). Calling
+                    // closeLbug directly here bypassed that guard and could close a
+                    // Database mid-query — a native use-after-free (#2614). Wrap in
+                    // reinitPromises to serialize concurrent detectors.
                     const reinit = (async () => {
                         try {
-                            await closeLbug(poolKey);
-                            this.initializedRepos.delete(poolKey);
-                            this.lastObservedIndexedAt.set(poolKey, meta.indexedAt);
-                            await initLbug(poolKey, repo.lbugPath);
-                            this.initializedRepos.add(poolKey);
+                            // Advance the observed stamp regardless: a stamp change with an
+                            // unchanged file must not re-trigger on every check.
+                            if (meta?.indexedAt)
+                                this.lastObservedIndexedAt.set(poolKey, meta.indexedAt);
+                            const reopened = await initLbug(poolKey, repo.lbugPath);
+                            // Advance the observed IDENTITY only when the pool actually rolled
+                            // over. If a query was in flight, initLbug served the current
+                            // handle and returned false; leaving the identity divergent
+                            // re-triggers the reopen on a later idle check instead of latching.
+                            if (reopened) {
+                                this.lastObservedDbIdentity.set(poolKey, await statDbIdentity(repo.lbugPath));
+                            }
                         }
                         finally {
                             this.reinitPromises.delete(poolKey);
@@ -1151,6 +1172,7 @@ export class LocalBackend {
             await initLbug(poolKey, repo.lbugPath);
             this.initializedRepos.add(poolKey);
             this.lastObservedIndexedAt.set(poolKey, repo.indexedAt);
+            this.lastObservedDbIdentity.set(poolKey, await statDbIdentity(repo.lbugPath));
         }
         catch (err) {
             // If lock error, mark as not initialized so next call retries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.80",
+  "version": "1.6.10-rc.82",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",