gitnexus 1.6.4-rc.91 → 1.6.4-rc.93

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

@@ -32,12 +32,6 @@ export interface RelCsvSplitResult {
 export declare const splitRelCsvByLabelPair: (csvPath: string, csvDir: string, validTables: Set<string>, getNodeLabel: (id: string) => string, wsFactory?: WriteStreamFactory) => Promise<RelCsvSplitResult>;
 /** Expose the current Database for pool adapter reuse in tests. */
 export declare const getDatabase: () => lbug.Database | null;
-/**
- * Return true when the error message indicates that another process holds
- * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
- * `gitnexus serve` running at the same time).
- */
-export declare const isDbBusyError: (err: unknown) => boolean;
 /**
  * Return true when the error message indicates a write was attempted against
  * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,

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

@@ -8,7 +8,7 @@ import lbug from '@ladybugdb/core';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { extensionManager } from './extension-loader.js';
-import { closeLbugConnection, openLbugConnection, } from './lbug-config.js';
+import { closeLbugConnection, isDbBusyError, isOpenRetryExhausted, openLbugConnection, waitForWindowsHandleRelease, } from './lbug-config.js';
 import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 /**
@@ -140,18 +140,6 @@ let sessionLock = Promise.resolve();
 const DB_LOCK_RETRY_ATTEMPTS = 3;
 /** Base back-off in ms between BUSY retries (multiplied by attempt number). */
 const DB_LOCK_RETRY_DELAY_MS = 500;
-/**
- * Return true when the error message indicates that another process holds
- * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
- * `gitnexus serve` running at the same time).
- */
-export const isDbBusyError = (err) => {
-    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
-    return (msg.includes('busy') ||
-        msg.includes('lock') ||
-        msg.includes('already in use') ||
-        msg.includes('could not set lock'));
-};
 /**
  * Return true when the error message indicates a write was attempted against
  * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,
@@ -201,7 +189,11 @@ export const withLbugDb = async (dbPath, operation) => {
         }
         catch (err) {
             lastError = err;
-            if (!isDbBusyError(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
+            // Skip outer retry when the inner open-retry already exhausted: the
+            // ~1.5s open-time budget was just spent, repeating the full reset+
+            // reopen cycle would only add 4-5s of tail latency without changing
+            // the outcome (both layers consult the same isDbBusyError matcher).
+            if (!isDbBusyError(err) || isOpenRetryExhausted(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
                 throw err;
             }
             // Close stale connection inside the session lock to prevent race conditions
@@ -274,7 +266,16 @@ const doInitLbug = async (dbPath) => {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            if (!msg.includes('already exists')) {
+            // Suppression list:
+            //   - "already exists": expected idempotent re-create on existing DBs
+            //   - "could not set lock on file": LadybugDB v0.16.1 emits this on
+            //     Windows when CREATE NODE TABLE runs against a path that was
+            //     just opened (the WAL handle from a fresh Database briefly
+            //     contests the table's first-write lock). The table is created
+            //     anyway and any genuine cross-process lock contention surfaces
+            //     on the next operation via withLbugDb's retry. Logging it here
+            //     would just be noise in CI.
+            if (!msg.includes('already exists') && !isDbBusyError(err)) {
                 logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
             }
         }
@@ -940,6 +941,9 @@ export const flushWAL = async () => {
  */
 export const safeClose = async () => {
     await flushWAL();
+    // Capture before close — currentDbPath stays set so the Windows post-close
+    // probe below knows which file to wait on.
+    const closingDbPath = currentDbPath;
     if (conn) {
         try {
             // eslint-disable-next-line no-restricted-syntax -- sole authorised close site
@@ -960,6 +964,21 @@ export const safeClose = async () => {
         }
         db = null;
     }
+    // Windows: libuv reports `db.close()` resolved before the kernel has
+    // released the file handle. A subsequent `new Database(samePath)` in
+    // the same process can race the release. The probe (lbug-config.ts)
+    // forces any residual lock to surface as EBUSY/EPERM/EACCES so the
+    // open-time retry absorbs the lag.
+    if (process.platform === 'win32' && closingDbPath) {
+        const released = await waitForWindowsHandleRelease(closingDbPath);
+        if (!released) {
+            // Probe exhausted with a lock code still in flight. The next
+            // openLbugConnection will absorb whatever residual lag remains, but
+            // a chronic warning helps operators spot AV interference (Windows
+            // Defender holding the file far past the 250ms budget).
+            logger.warn({ dbPath: closingDbPath }, '⚠️ LadybugDB file handle still locked after close (Windows). If this repeats, check antivirus/Defender exclusions for the GitNexus storage directory.');
+        }
+    }
 };
 export const closeLbug = async () => {
     await safeClose();

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

@@ -32,15 +32,71 @@ import type lbug from '@ladybugdb/core';
  * integer; anything invalid falls back to the default.
  */
 export declare const LBUG_MAX_DB_SIZE: number;
+export declare const WAL_RECOVERY_SUGGESTION = "WAL corruption detected. Run `gitnexus analyze` to rebuild the index.";
+export declare function isWalCorruptionError(err: unknown): boolean;
 type LbugModule = typeof lbug;
 export interface LbugDatabaseOptions {
     readOnly?: boolean;
+    throwOnWalReplayFailure?: boolean;
 }
 export interface LbugConnectionHandle {
     db: lbug.Database;
     conn: lbug.Connection;
 }
+/**
+ * Return true when the error message indicates that a LadybugDB file lock
+ * could not be acquired — either at construction time
+ * (`new lbug.Database(...)` raises from `local_file_system.cpp`) or during
+ * a query (another writer holds the exclusive lock).
+ *
+ * Lives here (not in `lbug-adapter.ts`) so both the construction-time
+ * retry (`openWithLockRetry` in this file) and the query-time retry
+ * (`withLbugDb` in `lbug-adapter.ts`) consult the same matcher. Callers
+ * import directly from this module — no re-export to keep in sync.
+ */
+export declare const isDbBusyError: (err: unknown) => boolean;
 export declare function createLbugDatabase(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): lbug.Database;
+/**
+ * Marker symbol attached to lock errors after `openWithLockRetry` exhausts
+ * its budget. `withLbugDb`'s outer query-time retry consults this so it
+ * does not re-retry a path that just spent up to ~1.5s in the open-time
+ * loop — preventing 6s tail latencies (3× outer × 5× inner attempts).
+ *
+ * The symbol is internal to GitNexus; consumers should treat the underlying
+ * error message as the user-visible signal.
+ */
+export declare const LBUG_OPEN_RETRY_EXHAUSTED: unique symbol;
+export declare const isOpenRetryExhausted: (err: unknown) => boolean;
+/** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
+export declare const _isTestFixturePathForTest: (dbPath: string) => boolean;
 export declare function openLbugConnection(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): Promise<LbugConnectionHandle>;
 export declare function closeLbugConnection(handle: LbugConnectionHandle): Promise<void>;
+/**
+ * Probe `dbPath` AND its `.wal` sidecar after `db.close()` so any
+ * residual native file handle surfaces as EBUSY/EPERM/EACCES and the
+ * bounded retry absorbs the release lag. Windows-only — Linux/macOS do
+ * not exhibit this race.
+ *
+ * Both files matter. Empirically, on rapid open→close→reopen cycles the
+ * main `dbPath` handle releases first; the `.wal` handle from the
+ * previous Database lingers and the new Database's first write (CREATE
+ * NODE TABLE during schema init) fails with "Could not set lock on
+ * file". Probing both makes safeClose actually return when the kernel
+ * is fully done with the path.
+ *
+ * Returns `true` when both probes succeeded (or skipped on non-lock
+ * errors / missing files). Returns `false` when either probe exhausted
+ * its budget with a lock code still in flight.
+ *
+ * Defensive shape:
+ *   - Opens read+write (`'r+'`) so the probe actually surfaces exclusive
+ *     locks held by the previous Database. A read-only probe (`'r'`) is
+ *     insufficient — Windows will grant read access while the previous
+ *     handle's exclusive write lock is still in flight, which lets
+ *     `safeClose` return before the next CREATE NODE TABLE can lock the
+ *     file.
+ *   - `try/finally` around `handle.close()` guarantees no fd leak even
+ *     if close itself throws.
+ */
+export declare const waitForWindowsHandleRelease: (dbPath: string) => Promise<boolean>;
 export {};

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

@@ -1,3 +1,6 @@
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
 /**
  * Shared configuration for `@ladybugdb/core` `Database` construction.
  *
@@ -39,13 +42,193 @@ export const LBUG_MAX_DB_SIZE = (() => {
     }
     return 16 * 1024 * 1024 * 1024;
 })();
+/** Matches WAL corruption errors from the LadybugDB engine. */
+const WAL_CORRUPTION_RE = /corrupt(ed)?\s+wal|invalid\s+wal\s+record|wal.*corrupt|checksum.*wal/i;
+export const WAL_RECOVERY_SUGGESTION = 'WAL corruption detected. Run `gitnexus analyze` to rebuild the index.';
+export function isWalCorruptionError(err) {
+    if (!err)
+        return false;
+    const msg = err instanceof Error ? err.message : String(err);
+    return WAL_CORRUPTION_RE.test(msg);
+}
+/**
+ * Return true when the error message indicates that a LadybugDB file lock
+ * could not be acquired — either at construction time
+ * (`new lbug.Database(...)` raises from `local_file_system.cpp`) or during
+ * a query (another writer holds the exclusive lock).
+ *
+ * Lives here (not in `lbug-adapter.ts`) so both the construction-time
+ * retry (`openWithLockRetry` in this file) and the query-time retry
+ * (`withLbugDb` in `lbug-adapter.ts`) consult the same matcher. Callers
+ * import directly from this module — no re-export to keep in sync.
+ */
+export const isDbBusyError = (err) => {
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    // `lock` already subsumes `could not set lock`; the broader term is kept
+    // because graph-DB transient errors include "deadlock", "lock contention",
+    // and the LadybugDB native module's "could not set lock on file" — all of
+    // which deserve a retry. If a non-transient lock-shaped error ever
+    // surfaces (e.g., "lock file missing" during recovery), tighten this
+    // matcher rather than raising the retry budget.
+    return msg.includes('busy') || msg.includes('lock') || msg.includes('already in use');
+};
 export function createLbugDatabase(lbugModule, databasePath, options = {}) {
-    return new lbugModule.Database(databasePath, 0, false, options.readOnly ?? false, LBUG_MAX_DB_SIZE);
+    // .d.ts declares fewer args than the native constructor accepts.
+    return new lbugModule.Database(databasePath, 0, // bufferManagerSize
+    false, // enableCompression (pinned for v0.16.0)
+    options.readOnly ?? false, LBUG_MAX_DB_SIZE, true, // autoCheckpoint
+    -1, // checkpointThreshold
+    options.throwOnWalReplayFailure ?? true, true);
 }
+// ─── Lock-busy retry tuning knobs ───────────────────────────────────────────
+//
+// All four GitNexus retry pairs that touch native LadybugDB locks live with
+// a comment cross-reference here so an SRE tuning Windows flakes finds them
+// in one grep:
+//
+//   1. OPEN_LOCK_RETRY_ATTEMPTS / OPEN_LOCK_RETRY_DELAY_MS  (this file)
+//      → `new lbug.Database()` constructor lock failures
+//   2. HANDLE_RELEASE_PROBE_ATTEMPTS / HANDLE_RELEASE_PROBE_DELAY_MS  (this file)
+//      → post-close fs.open probe to absorb Windows handle-release lag
+//   3. DB_LOCK_RETRY_ATTEMPTS / DB_LOCK_RETRY_DELAY_MS  (lbug-adapter.ts withLbugDb)
+//      → query-time busy/lock retry around already-open connections
+//
+// `new lbug.Database()` calls into the native module which performs an
+// OS-level exclusive lock on `<dbPath>`. On Windows that lock can fail
+// for reasons specific to the OS (Defender briefly opens new files,
+// libuv handle release lags the JS-side close). 5 attempts × 100ms
+// linear back-off (max sleep 100+200+300+400 = 1s, plus 5 ctor RTTs
+// of 10–50ms each = ~1.0–1.2s worst case) clears the typical
+// AV-scanner hold without masking real cross-process conflicts.
+//
+// Source: https://github.com/LadybugDB/ladybug/blob/v0.16.1/src/common/file_system/local_file_system.cpp#L126
+const OPEN_LOCK_RETRY_ATTEMPTS = 5;
+const OPEN_LOCK_RETRY_DELAY_MS = 100;
+const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
+const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
+const HANDLE_RELEASE_LOCK_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+/**
+ * Test-fixture directory prefixes recognized by `isTestFixturePath`.
+ *
+ * IMPORTANT: this list must stay in sync with the prefixes passed to
+ * `createTempDir` in `gitnexus/test/helpers/test-db.ts` and the prefixes
+ * used by `withTestLbugDB` (`gitnexus/test/helpers/test-indexed-db.ts`).
+ * If you add a new test that passes a custom prefix to `createTempDir`,
+ * add it here too — otherwise the stale-sidecar sweep silently won't
+ * fire for that fixture and CI flakes return.
+ *
+ * The default `createTempDir('gitnexus-test-')` and the lbug variant
+ * `'gitnexus-lbug-'` cover today's call sites.
+ */
+const TEST_FIXTURE_PREFIXES = ['gitnexus-lbug-', 'gitnexus-test-'];
+/**
+ * Marker symbol attached to lock errors after `openWithLockRetry` exhausts
+ * its budget. `withLbugDb`'s outer query-time retry consults this so it
+ * does not re-retry a path that just spent up to ~1.5s in the open-time
+ * loop — preventing 6s tail latencies (3× outer × 5× inner attempts).
+ *
+ * The symbol is internal to GitNexus; consumers should treat the underlying
+ * error message as the user-visible signal.
+ */
+export const LBUG_OPEN_RETRY_EXHAUSTED = Symbol.for('gitnexus.lbug.openRetryExhausted');
+export const isOpenRetryExhausted = (err) => {
+    if (err === null || err === undefined || typeof err !== 'object')
+        return false;
+    return err[LBUG_OPEN_RETRY_EXHAUSTED] === true;
+};
+const tagOpenRetryExhausted = (err) => {
+    if (err && typeof err === 'object') {
+        err[LBUG_OPEN_RETRY_EXHAUSTED] = true;
+    }
+    return err;
+};
+/**
+ * True when `dbPath` resolves to a recognized test fixture under the OS
+ * temp directory. Used to gate the stale-sidecar sweep so production
+ * paths never have their `.wal` / `.lock` files deleted.
+ *
+ * Defensive shape:
+ *   - `path.resolve` normalizes `..` segments before the prefix check, so
+ *     `<tmp>/gitnexus-lbug-x/../../etc/passwd` is rejected.
+ *   - The tmpRoot check trims any trailing separator returned by some
+ *     Windows TMP configurations (`C:\Users\X\Temp\`) so the startsWith
+ *     comparison stays correct.
+ *   - Only the IMMEDIATE parent directory is matched against the prefix
+ *     list. An ancestor walk would let a tmpdir whose own basename starts
+ *     with `gitnexus-lbug-` accept arbitrary nested paths under it.
+ */
+const isTestFixturePath = (dbPath) => {
+    const tmpRoot = os.tmpdir().replace(new RegExp(`${path.sep === '\\' ? '\\\\' : path.sep}+$`), '');
+    const resolved = path.resolve(dbPath);
+    if (!resolved.startsWith(tmpRoot + path.sep) && resolved !== tmpRoot)
+        return false;
+    const parentBase = path.basename(path.dirname(resolved));
+    return TEST_FIXTURE_PREFIXES.some((p) => parentBase.startsWith(p));
+};
+/** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
+export const _isTestFixturePathForTest = isTestFixturePath;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Attempt to remove stale `.wal` / `.lock` sidecars that a previous aborted
+ * test run may have left behind. Best-effort: ENOENT is normal, anything
+ * else is swallowed so the caller's retry can surface the original error.
+ */
+const sweepStaleSidecars = async (dbPath) => {
+    for (const suffix of ['.wal', '.lock']) {
+        try {
+            await fs.unlink(dbPath + suffix);
+        }
+        catch {
+            /* missing sidecar or permission error — let the open retry surface it */
+        }
+    }
+};
+/**
+ * Run `construct` with bounded retries when `new lbug.Database(...)` throws
+ * a busy/lock error. The original (loop-captured) error is preferred over
+ * any post-sweep error so triage sees the real LadybugDB lock message.
+ * On exhaustion the rethrown error is tagged via
+ * `LBUG_OPEN_RETRY_EXHAUSTED` so the outer query-time retry in
+ * `withLbugDb` skips re-retrying a freshly-exhausted path.
+ */
+const openWithLockRetry = async (construct, dbPath) => {
+    let originalLockError;
+    for (let attempt = 1; attempt <= OPEN_LOCK_RETRY_ATTEMPTS; attempt++) {
+        try {
+            return construct();
+        }
+        catch (err) {
+            if (!isDbBusyError(err))
+                throw err;
+            originalLockError = err;
+            if (attempt === OPEN_LOCK_RETRY_ATTEMPTS)
+                break;
+            await sleep(OPEN_LOCK_RETRY_DELAY_MS * attempt);
+        }
+    }
+    // Final defense: only for recognized test fixtures, sweep stale sidecars
+    // (a prior aborted test run can leave a `.wal` lock that survives the
+    // tmp dir cleanup). Production paths never reach this branch — the guard
+    // requires the immediate parent dir to match a test prefix AND the
+    // resolved path to live under the OS temp directory.
+    if (isTestFixturePath(dbPath)) {
+        await sweepStaleSidecars(dbPath);
+        try {
+            return construct();
+        }
+        catch {
+            // Intentionally do NOT overwrite originalLockError. The user-actionable
+            // signal is "we exhausted lock retries" — a different error from the
+            // post-sweep attempt is less useful than the lock failure that drove
+            // the sweep in the first place.
+        }
+    }
+    throw tagOpenRetryExhausted(originalLockError);
+};
 export async function openLbugConnection(lbugModule, databasePath, options = {}) {
     let db;
     try {
-        db = createLbugDatabase(lbugModule, databasePath, options);
+        db = await openWithLockRetry(() => createLbugDatabase(lbugModule, databasePath, options), databasePath);
         return { db, conn: new lbugModule.Connection(db) };
     }
     catch (err) {
@@ -58,3 +241,63 @@ export async function closeLbugConnection(handle) {
     await handle.conn.close().catch(() => { });
     await handle.db.close().catch(() => { });
 }
+/**
+ * Probe `dbPath` AND its `.wal` sidecar after `db.close()` so any
+ * residual native file handle surfaces as EBUSY/EPERM/EACCES and the
+ * bounded retry absorbs the release lag. Windows-only — Linux/macOS do
+ * not exhibit this race.
+ *
+ * Both files matter. Empirically, on rapid open→close→reopen cycles the
+ * main `dbPath` handle releases first; the `.wal` handle from the
+ * previous Database lingers and the new Database's first write (CREATE
+ * NODE TABLE during schema init) fails with "Could not set lock on
+ * file". Probing both makes safeClose actually return when the kernel
+ * is fully done with the path.
+ *
+ * Returns `true` when both probes succeeded (or skipped on non-lock
+ * errors / missing files). Returns `false` when either probe exhausted
+ * its budget with a lock code still in flight.
+ *
+ * Defensive shape:
+ *   - Opens read+write (`'r+'`) so the probe actually surfaces exclusive
+ *     locks held by the previous Database. A read-only probe (`'r'`) is
+ *     insufficient — Windows will grant read access while the previous
+ *     handle's exclusive write lock is still in flight, which lets
+ *     `safeClose` return before the next CREATE NODE TABLE can lock the
+ *     file.
+ *   - `try/finally` around `handle.close()` guarantees no fd leak even
+ *     if close itself throws.
+ */
+export const waitForWindowsHandleRelease = async (dbPath) => {
+    const mainReleased = await probeSinglePath(dbPath);
+    const walReleased = await probeSinglePath(dbPath + '.wal');
+    return mainReleased && walReleased;
+};
+const probeSinglePath = async (filePath) => {
+    for (let attempt = 1; attempt <= HANDLE_RELEASE_PROBE_ATTEMPTS; attempt++) {
+        let handle;
+        try {
+            handle = await fs.open(filePath, 'r+');
+            return true;
+        }
+        catch (err) {
+            const code = err?.code;
+            if (!code || !HANDLE_RELEASE_LOCK_CODES.has(code))
+                return true; // ENOENT / unrelated → not our problem
+            if (attempt === HANDLE_RELEASE_PROBE_ATTEMPTS)
+                return false;
+            await sleep(HANDLE_RELEASE_PROBE_DELAY_MS * attempt);
+        }
+        finally {
+            if (handle) {
+                try {
+                    await handle.close();
+                }
+                catch {
+                    /* swallow — caller cannot do anything useful with a probe-close failure */
+                }
+            }
+        }
+    }
+    return false;
+};

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

@@ -17,7 +17,7 @@
 import fs from 'fs/promises';
 import lbug from '@ladybugdb/core';
 import { loadFTSExtension } from './lbug-adapter.js';
-import { createLbugDatabase } from './lbug-config.js';
+import { createLbugDatabase, isWalCorruptionError } from './lbug-config.js';
 const pool = new Map();
 const poolCloseListeners = new Set();
 /**
@@ -51,7 +51,7 @@ let idleTimer = null;
 // @ladybugdb/core), corrupting stdout in the pre-sentinel window. Routing
 // through the leaf breaks that chain.
 export { realStdoutWrite, realStderrWrite, setActiveStdoutWrite } from '../../mcp/stdio-capture.js';
-import { getActiveStdoutWrite } from '../../mcp/stdio-capture.js';
+import { getActiveStdoutWrite, realStderrWrite } from '../../mcp/stdio-capture.js';
 let stdoutSilenceCount = 0;
 /** True while pre-warming connections — prevents watchdog from prematurely restoring stdout */
 let preWarmActive = false;
@@ -203,6 +203,44 @@ const QUERY_TIMEOUT_MS = 30_000;
 const WAITER_TIMEOUT_MS = 15_000;
 const LOCK_RETRY_ATTEMPTS = 3;
 const LOCK_RETRY_DELAY_MS = 2000;
+async function openReadOnlyDatabase(dbPath) {
+    let db;
+    silenceStdout();
+    try {
+        db = createLbugDatabase(lbug, dbPath, {
+            readOnly: true,
+            throwOnWalReplayFailure: false,
+        });
+        await db.init();
+        return db;
+    }
+    catch (err) {
+        if (db)
+            await db.close().catch(() => { });
+        throw err;
+    }
+    finally {
+        restoreStdout();
+    }
+}
+/**
+ * Quarantine the .wal file and retry opening the database.
+ * Used when the initial open fails with a WAL corruption error.
+ */
+async function tryQuarantineAndReopen(dbPath, repoId) {
+    const walPath = dbPath + '.wal';
+    const quarantineName = `${walPath}.corrupt.${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await fs.rename(walPath, quarantineName);
+    }
+    catch {
+        throw new Error(`LadybugDB WAL corruption detected for ${repoId}. ` +
+            `Run \`gitnexus analyze\` to rebuild the index. (quarantine failed)`);
+    }
+    realStderrWrite(`GitNexus: LadybugDB WAL quarantined for ${repoId}; graph may be stale. ` +
+        `Run \`gitnexus analyze\` to rebuild the index.\n`);
+    return await openReadOnlyDatabase(dbPath);
+}
 /** Deduplicates concurrent initLbug calls for the same repoId */
 const initPromises = new Map();
 /**
@@ -256,17 +294,27 @@ async function doInitLbug(repoId, dbPath) {
         // avoids lock conflicts when `gitnexus analyze` is writing.
         let lastError = null;
         for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
-            silenceStdout();
             try {
-                const db = createLbugDatabase(lbug, dbPath, { readOnly: true });
-                restoreStdout();
+                const db = await openReadOnlyDatabase(dbPath);
                 shared = { db, refCount: 0, ftsLoaded: false };
                 dbCache.set(dbPath, shared);
                 break;
             }
             catch (err) {
-                restoreStdout();
                 lastError = err instanceof Error ? err : new Error(String(err));
+                if (isWalCorruptionError(lastError)) {
+                    try {
+                        const db = await tryQuarantineAndReopen(dbPath, repoId);
+                        shared = { db, refCount: 0, ftsLoaded: false };
+                        dbCache.set(dbPath, shared);
+                        break;
+                    }
+                    catch (retryErr) {
+                        throw new Error(`LadybugDB WAL corruption detected for ${repoId}. ` +
+                            `Run \`gitnexus analyze\` to rebuild the index. ` +
+                            `(${retryErr instanceof Error ? retryErr.message : String(retryErr)})`);
+                    }
+                }
                 const isLockError = lastError.message.includes('Could not set lock') || lastError.message.includes('lock');
                 if (!isLockError || attempt === LOCK_RETRY_ATTEMPTS)
                     break;

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

@@ -259,6 +259,7 @@ export declare class LocalBackend {
      * UID-based direct lookup. No cluster in output.
      */
     private context;
+    private _contextImpl;
     /**
      * Legacy explore — kept for backwards compatibility with resources.ts.
      * Routes cluster/process types to direct graph queries.

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

@@ -8,6 +8,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, isWriteQuery, } from '../../core/lbug/pool-adapter.js';
+import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
 export { isWriteQuery };
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
@@ -1022,7 +1023,14 @@ export class LocalBackend {
             return result;
         }
         catch (err) {
-            return { error: err.message || 'Query failed' };
+            const msg = err.message || 'Query failed';
+            if (isWalCorruptionError(err)) {
+                return {
+                    error: msg,
+                    recoverySuggestion: WAL_RECOVERY_SUGGESTION,
+                };
+            }
+            return { error: msg };
         }
     }
     /**
@@ -1389,6 +1397,21 @@ export class LocalBackend {
      * UID-based direct lookup. No cluster in output.
      */
     async context(repo, params) {
+        try {
+            return await this._contextImpl(repo, params);
+        }
+        catch (err) {
+            const msg = (err instanceof Error ? err.message : String(err)) || 'Context query failed';
+            if (isWalCorruptionError(err)) {
+                return {
+                    error: msg,
+                    recoverySuggestion: WAL_RECOVERY_SUGGESTION,
+                };
+            }
+            throw err;
+        }
+    }
+    async _contextImpl(repo, params) {
         await this.ensureInitialized(repo.id);
         const { name, uid, file_path, kind, include_content } = params;
         if (!name && !uid) {
@@ -1990,6 +2013,7 @@ export class LocalBackend {
                 impactedCount: 0,
                 risk: 'UNKNOWN',
                 suggestion: 'The graph query failed — try gitnexus context <symbol> as a fallback',
+                ...(isWalCorruptionError(err) ? { recoverySuggestion: WAL_RECOVERY_SUGGESTION } : {}),
             };
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.4-rc.91",
+  "version": "1.6.4-rc.93",
   "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",