gitnexus 1.6.8 → 1.6.9-rc.2

package/dist/core/lbug/shutdown-helpers.d.ts

@@ -0,0 +1,18 @@
+/** Default cap so a CHECKPOINT queued behind a long COPY can't wedge the signal. */
+export declare const DEFAULT_EXIT_CLEANUP_TIMEOUT_MS = 2000;
+export interface BoundedCheckpointExitOptions {
+    /** Exit code to terminate with (130 for SIGINT, 0 for a worker SIGTERM). */
+    exitCode: number;
+    /** Cap on the CHECKPOINT; defaults to {@link DEFAULT_EXIT_CLEANUP_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Report a CHECKPOINT failure (e.g. over IPC) rather than swallowing it. */
+    onFlushError?: (err: unknown) => void;
+    /** Run just before exit (e.g. flush the logger synchronously). */
+    beforeExit?: () => void | Promise<void>;
+}
+/**
+ * Best-effort CHECKPOINT bounded by a timeout, then exit. Never rejects — the
+ * exit always fires (in `finally`) even if the CHECKPOINT throws. Fire-and-forget
+ * from a signal handler (`void boundedCheckpointBeforeExit({...})`).
+ */
+export declare function boundedCheckpointBeforeExit(opts: BoundedCheckpointExitOptions): Promise<void>;

package/dist/core/lbug/shutdown-helpers.js

@@ -0,0 +1,36 @@
+/**
+ * Shared bounded "checkpoint, then exit" cleanup for interrupt/cancel signals
+ * (#2264). The CLI SIGINT handler and the forked worker's SIGTERM handler both
+ * need to: CHECKPOINT the WAL for durability (skipping the native close — see
+ * closeLbugBeforeExit), but NOT hang behind an in-flight COPY that holds the
+ * connection lock, and then exit. Bounding the CHECKPOINT with a short timeout
+ * keeps a single Ctrl-C / cancel responsive; the WAL replays on the next analyze.
+ */
+import { closeLbugBeforeExit } from './lbug-adapter.js';
+/** Default cap so a CHECKPOINT queued behind a long COPY can't wedge the signal. */
+export const DEFAULT_EXIT_CLEANUP_TIMEOUT_MS = 2000;
+/**
+ * Best-effort CHECKPOINT bounded by a timeout, then exit. Never rejects — the
+ * exit always fires (in `finally`) even if the CHECKPOINT throws. Fire-and-forget
+ * from a signal handler (`void boundedCheckpointBeforeExit({...})`).
+ */
+export async function boundedCheckpointBeforeExit(opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_EXIT_CLEANUP_TIMEOUT_MS;
+    const checkpoint = opts.checkpoint ?? closeLbugBeforeExit;
+    const exit = opts.exit ?? ((code) => process.exit(code));
+    let timer;
+    try {
+        await Promise.race([
+            checkpoint().catch((err) => opts.onFlushError?.(err)),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        await opts.beforeExit?.();
+        exit(opts.exitCode);
+    }
+}

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

@@ -33,6 +33,7 @@
  */
 import { logger } from '../logger.js';
 import { tryFlushWAL } from './lbug-adapter.js';
+import { markWalDriverActive } from './wal-driver-state.js';
 import { isLbugCheckpointIoError } from './lbug-config.js';
 /**
  * Bounded retry budget. Total worst-case wall time is dominated by the
@@ -120,9 +121,21 @@ export const startWalCheckpointDriver = (options = {}) => {
     const periodMs = options.periodMs ?? DEFAULT_PERIOD_MS;
     let stopped = false;
     let inflight = null;
+    // Arm the streamQuery guard: while this driver runs, an unlocked streamQuery on
+    // the singleton connection could race a CHECKPOINT (#2264). Cleared in stop().
+    markWalDriverActive(true);
     const tick = async () => {
         if (stopped)
             return;
+        // Reentrancy guard: setInterval keeps firing on its fixed cadence even when
+        // the previous checkpoint has not settled (a CHECKPOINT can outlast the
+        // period during a large `--pdg` writeback). Without this, each overdue tick
+        // would queue another CHECKPOINT — they now serialize on the connection lock
+        // (lbug-adapter `withConnLock`), but letting them pile up is still pointless
+        // work and widens the window for a backlog at stop(). Skip while one is in
+        // flight; the next tick covers any WAL accumulated in the meantime.
+        if (inflight)
+            return;
         inflight = runCheckpointWithRetry()
             .then(() => undefined)
             .catch((err) => {
@@ -167,6 +180,9 @@ export const startWalCheckpointDriver = (options = {}) => {
                     /* swallowed in tick() — surface path is the surrounding write */
                 }
             }
+            // Disarm AFTER the in-flight CHECKPOINT drains — clearing it earlier would
+            // briefly let a streamQuery race the still-finishing CHECKPOINT (#2264).
+            markWalDriverActive(false);
         },
     };
 };

package/dist/core/lbug/wal-driver-state.d.ts

@@ -0,0 +1,4 @@
+/** Toggled by the WAL-checkpoint driver's start (true) / stop (false). */
+export declare const markWalDriverActive: (active: boolean) => void;
+/** True while the manual WAL-checkpoint driver is running. @see streamQuery */
+export declare const isWalDriverActive: () => boolean;

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

@@ -0,0 +1,23 @@
+/**
+ * Shared "is the manual WAL-checkpoint driver running?" flag (#2264).
+ *
+ * Lives in its own tiny module — NOT in lbug-adapter — on purpose: the
+ * wal-checkpoint-driver toggles it and lbug-adapter's `streamQuery` reads it, and
+ * putting it here keeps that one-bit coupling out of the big, heavily-mocked
+ * lbug-adapter surface. (Importing it from lbug-adapter forced every test that
+ * mocks lbug-adapter + loads the real driver to also stub the toggle — a brittle
+ * ripple this module avoids.)
+ *
+ * streamQuery is deliberately not wrapped in withConnLock (its per-row callback can
+ * re-enter the adapter), so it must refuse to run while the driver is live —
+ * otherwise its unlocked per-row reads could race a CHECKPOINT on the shared
+ * connection. The serve/read path never starts the driver, so this stays false
+ * there.
+ */
+let walDriverActive = false;
+/** Toggled by the WAL-checkpoint driver's start (true) / stop (false). */
+export const markWalDriverActive = (active) => {
+    walDriverActive = active;
+};
+/** True while the manual WAL-checkpoint driver is running. @see streamQuery */
+export const isWalDriverActive = () => walDriverActive;

package/dist/core/run-analyze.d.ts

@@ -142,6 +142,15 @@ export interface AnalyzeOptions {
      * consumer scan unchanged.
      */
     fetchWrappers?: string[];
+    /**
+     * The caller will `process.exit()` immediately after this analyze returns (the
+     * CLI `analyze` command). When set, the finalize/error close CHECKPOINTs for
+     * durability but skips the native `conn.close()`/`db.close()`, which can
+     * double-free in LadybugDB's `ClientContext` destructor after large `--pdg`
+     * writes (gdb-confirmed) — aborting the process AFTER a fully-written index.
+     * Process exit reclaims the handles. Long-lived callers (MCP server, tests)
+     * leave this unset so they get a real close. See `closeLbug`. */
+    skipNativeCloseOnExit?: boolean;
 }
 export interface AnalyzeResult {
     repoName: string;

package/dist/core/run-analyze.js

@@ -13,11 +13,11 @@ import fs from 'fs/promises';
 import { execFileSync } from 'child_process';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
-import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
+import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
 import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
-import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
+import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, isRepoRegistered, cleanupOldKuzuFiles, 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';
 import { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './ingestion/taint/propagate.js';
@@ -463,7 +463,20 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     return true; // conservative on git failure
                 }
             })();
-            if (!dirty) {
+            // Registration wrinkle around the fast path (#2264). A prior
+            // `analyze --name X` that hit a name collision writes meta.json (meta-save
+            // runs before registerRepo) then fails before registering, leaving the
+            // index up-to-date but UNREGISTERED. When the user re-runs with
+            // --allow-duplicate-name they explicitly want it registered, so fall
+            // through to the pipeline (which registers it, honoring the flag) instead
+            // of early-returning an unregistered repo the flag could never heal.
+            // For a PLAIN analyze we deliberately do NOT self-heal: an up-to-date but
+            // unregistered repo early-returns here and the CLI's assertAnalysisFinalized
+            // surfaces it as a hard failure (#1169) rather than silently registering a
+            // possibly half-finalized index. `isRepoRegistered` is only read on the
+            // opt-in branch so the common fast path keeps its single-stat cost.
+            const healUnregistered = options.allowDuplicateName === true && !(await isRepoRegistered(repoPath));
+            if (!dirty && !healUnregistered) {
                 await ensureGitNexusIgnored(repoPath);
                 return {
                     // `resolveRepoIdentityRoot` collapses worktree roots to the
@@ -1152,7 +1165,11 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // Stop the manual checkpoint driver before closeLbug so its
         // in-flight CHECKPOINT cannot race the `safeClose` CHECKPOINT.
         await walCheckpointDriver.stop();
-        await closeLbug();
+        // CLI callers (about to process.exit) skip the native close to dodge a
+        // 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());
         progress('done', 100, 'Done');
         return {
             repoName: projectName,
@@ -1173,7 +1190,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             /* swallow — surface path is the rethrow below */
         }
         try {
-            await closeLbug();
+            // Skip the native close on the error path too: a real conn.close() after
+            // large --pdg writes can itself abort in LadybugDB's ClientContext
+            // destructor (#2264 review P2), turning an actionable exit-1 into a raw
+            // SIGABRT. closeLbugBeforeExit leaves the handles open, but the CLI catch
+            // now force-exits when isLbugReady() (analyze.ts, #2264 review P1), so the
+            // process still terminates — no hang, no abort. flushWAL keeps the partial
+            // index durable; process exit reclaims the handles. Long-lived callers
+            // (skipNativeCloseOnExit unset) close for real.
+            await (options.skipNativeCloseOnExit ? closeLbugBeforeExit() : closeLbug());
         }
         catch {
             /* swallow */

package/dist/server/analyze-job.js

@@ -63,6 +63,12 @@ export class JobManager {
         const job = this.jobs.get(id);
         if (!job)
             return;
+        // Once a job is terminal (complete/failed) its outcome is immutable — drop any
+        // later update so a worker `complete` racing a SIGTERM-driven `error` (or vice
+        // versa) can't flip a reported result (#2264 P3). The transition INTO a terminal
+        // state still applies because `job.status` is not yet terminal at that point.
+        if (this.isTerminal(job.status))
+            return;
         Object.assign(job, update);
         if (this.isTerminal(job.status)) {
             job.completedAt = job.completedAt ?? Date.now();

package/dist/server/analyze-launch.js

@@ -52,6 +52,13 @@ export function createLaunchAnalysisWorker(deps) {
                     stderrChunks = stderrChunks.slice(-4096);
             });
             child.on('message', (msg) => {
+                // Ignore any message once the job is terminal — a late worker message (a
+                // SIGTERM-driven `error` after `complete`, or vice versa) must not
+                // re-release the repo lock or flip the reported status. Mirrors the `exit`
+                // handler guard below; pairs with the worker's terminal-claim (#2264 P3).
+                const current = jobManager.getJob(job.id);
+                if (!current || current.status === 'complete' || current.status === 'failed')
+                    return;
                 if (msg.type === 'progress') {
                     jobManager.updateJob(job.id, {
                         status: 'analyzing',

package/dist/server/analyze-worker-core.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Side-effect-free core of the analyze worker's message handler.
+ *
+ * Extracted from `analyze-worker.ts` — a `fork()` entry module whose top-level
+ * `process.on(...)` handlers and `ready` handshake make it unsafe to import in a
+ * unit test. This module has no top-level side effects and takes its collaborators
+ * by dependency injection, so the worker's run → finalize → report contract is
+ * unit-testable without spawning a process. The entry module wires the real deps
+ * and owns the `process.exit` lifecycle.
+ *
+ * The `import type ... typeof import(...)` forms below are erased at runtime, so
+ * importing this module does NOT load `run-analyze`, `repo-manager`, or the entry
+ * worker — only the lightweight `analyze-worker-ipc` projection helper.
+ */
+import type { AnalyzeOptions } from '../core/run-analyze.js';
+import type { WorkerMessage } from './analyze-worker.js';
+export interface WorkerAnalysisDeps {
+    runFullAnalysis: typeof import('../core/run-analyze.js').runFullAnalysis;
+    assertAnalysisFinalized: typeof import('../storage/repo-manager.js').assertAnalysisFinalized;
+    send: (msg: WorkerMessage) => void;
+    /**
+     * Claim the single terminal-outcome slot. Returns `true` for the first caller
+     * (which may then send its `complete`/`error`) and `false` for every caller
+     * after — so a SIGTERM cancellation and a near-simultaneous completion can't
+     * both report a terminal outcome (#2264 P3). See {@link createTerminalClaim}.
+     */
+    claimTerminal: () => boolean;
+}
+/**
+ * Run the analysis and report the outcome to the parent over IPC. Reports at most
+ * one terminal message (`complete` or `error`) — and none if a cancellation
+ * already claimed the terminal slot — and never throws; the caller schedules
+ * `process.exit` after this resolves.
+ */
+export declare function runWorkerAnalysis(repoPath: string, options: AnalyzeOptions, deps: WorkerAnalysisDeps): Promise<void>;
+/**
+ * Create the single-use terminal-outcome claim shared by the worker's message
+ * handler and its SIGTERM handler. The first call returns `true`; every later
+ * call returns `false`. This is the coordination point that prevents a cancel and
+ * a completion from both reporting a terminal status (#2264 P3). Single-threaded
+ * JS guarantees the check-and-set is atomic (no preemption mid-call).
+ */
+export declare function createTerminalClaim(): () => boolean;

package/dist/server/analyze-worker-core.js

@@ -0,0 +1,56 @@
+import { projectAnalyzeResultForIpc } from './analyze-worker-ipc.js';
+/**
+ * Run the analysis and report the outcome to the parent over IPC. Reports at most
+ * one terminal message (`complete` or `error`) — and none if a cancellation
+ * already claimed the terminal slot — and never throws; the caller schedules
+ * `process.exit` after this resolves.
+ */
+export async function runWorkerAnalysis(repoPath, options, deps) {
+    let terminal;
+    try {
+        const result = await deps.runFullAnalysis(repoPath, 
+        // This worker force-exits right after reporting, so skip the native close
+        // (it can double-free in LadybugDB's ClientContext destructor after --pdg
+        // writes); flushWAL still persists the index, process.exit reclaims handles.
+        { ...options, skipNativeCloseOnExit: true }, {
+            onProgress: (phase, percent, message) => deps.send({ type: 'progress', phase, percent, message }),
+            onLog: (message) => deps.send({ type: 'progress', phase: 'log', percent: -1, message }),
+        });
+        // P2 (#2264): a half-finalized repo — meta.json written but the global
+        // registry entry missing (e.g. a prior collision-aborted run, or a wiped
+        // registry) — must NOT be reported as a successful analysis. Mirror the CLI's
+        // assertAnalysisFinalized guard so the worker surfaces it as an error instead
+        // of a false `complete` that leaves the repo invisible to list_repos.
+        await deps.assertAnalysisFinalized(repoPath);
+        // Send a JSON-safe projection, NOT the raw result: the IPC channel is
+        // default-JSON serialization and `result.pipelineResult` carries the live
+        // KnowledgeGraph. See analyze-worker-ipc.ts.
+        terminal = { type: 'complete', result: projectAnalyzeResultForIpc(result) };
+    }
+    catch (err) {
+        // Report the failure to the parent over IPC (the parent surfaces the message).
+        const message = err instanceof Error ? err.message : 'Analysis failed';
+        terminal = { type: 'error', message };
+    }
+    // P3 (#2264): only report if a SIGTERM cancellation hasn't already claimed the
+    // terminal slot — otherwise a cancel near the finish line would report the
+    // analysis as `complete` over the top of the cancellation.
+    if (deps.claimTerminal())
+        deps.send(terminal);
+}
+/**
+ * Create the single-use terminal-outcome claim shared by the worker's message
+ * handler and its SIGTERM handler. The first call returns `true`; every later
+ * call returns `false`. This is the coordination point that prevents a cancel and
+ * a completion from both reporting a terminal status (#2264 P3). Single-threaded
+ * JS guarantees the check-and-set is atomic (no preemption mid-call).
+ */
+export function createTerminalClaim() {
+    let claimed = false;
+    return () => {
+        if (claimed)
+            return false;
+        claimed = true;
+        return true;
+    };
+}

package/dist/server/analyze-worker.js

@@ -11,28 +11,63 @@
  *   Child -> Parent: { type: 'error', message: string }
  */
 import { runFullAnalysis } from '../core/run-analyze.js';
-import { projectAnalyzeResultForIpc } from './analyze-worker-ipc.js';
-import { closeLbug } from '../core/lbug/lbug-adapter.js';
+import { runWorkerAnalysis, createTerminalClaim } from './analyze-worker-core.js';
+import { assertAnalysisFinalized } from '../storage/repo-manager.js';
+import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
 function send(msg) {
+    // No try/catch: if the IPC channel is gone, process.send throws
+    // (ERR_IPC_CHANNEL_CLOSED) and that failure must NOT be swallowed. Every caller
+    // schedules its process.exit inside a `finally`, so a throw here still tears the
+    // worker down deterministically instead of wedging the event loop (#2264 P3).
     process.send?.(msg);
 }
-// Catch uncaught exceptions and unhandled rejections — report to parent
+// Single terminal-outcome slot shared by the message handler and the SIGTERM
+// handler: whoever claims it first reports its complete/error; the other skips its
+// terminal send, so a cancel near the finish line can't also report success and a
+// late SIGTERM can't flip an already-reported job (#2264 P3).
+const claimTerminal = createTerminalClaim();
+// Catch uncaught exceptions and unhandled rejections — report them to the parent
+// over IPC (the same channel the analysis path uses), then exit. The report runs
+// in `try` and the exit in `finally` so a throw from send() on a closed channel
+// can't skip the exit and leave the worker wedged (#2264 review P3).
 process.on('uncaughtException', (err) => {
-    send({ type: 'error', message: err?.message || 'Uncaught exception in worker' });
-    setTimeout(() => process.exit(1), 500);
+    try {
+        const message = err instanceof Error ? err.message : 'Uncaught exception in worker';
+        send({ type: 'error', message });
+    }
+    finally {
+        setTimeout(() => process.exit(1), 500);
+    }
 });
 process.on('unhandledRejection', (reason) => {
-    send({ type: 'error', message: reason?.message || 'Unhandled rejection in worker' });
-    setTimeout(() => process.exit(1), 500);
-});
-// Handle graceful shutdown — notify parent before exit
-process.on('SIGTERM', async () => {
-    send({ type: 'error', message: 'Analysis cancelled (worker received SIGTERM)' });
     try {
-        await closeLbug();
+        const message = reason instanceof Error ? reason.message : 'Unhandled rejection in worker';
+        send({ type: 'error', message });
+    }
+    finally {
+        setTimeout(() => process.exit(1), 500);
+    }
+});
+// Handle cancellation / timeout shutdown (analyze-job.ts `cancelJob` sends
+// SIGTERM). Bounded CHECKPOINT-then-exit shared with the CLI SIGINT path (#2264):
+// skip the native close (the LadybugDB destructor can double-free after --pdg
+// writes), but don't block behind the in-flight COPY's connection lock — so a
+// single cancel can't abort or hang the worker. A CHECKPOINT failure is reported
+// to the parent over IPC, not swallowed; the exit always fires.
+process.on('SIGTERM', () => {
+    // Only report the cancellation if the analysis hasn't already reported a
+    // terminal outcome (#2264 P3) — otherwise this would flip an already-complete
+    // job to failed. The cleanup + exit below run regardless.
+    if (claimTerminal()) {
+        send({ type: 'error', message: 'Analysis cancelled (worker received SIGTERM)' });
     }
-    catch { }
-    process.exit(0);
+    void boundedCheckpointBeforeExit({
+        exitCode: 0,
+        onFlushError: (err) => {
+            const message = err instanceof Error ? err.message : 'Worker checkpoint failed during SIGTERM';
+            send({ type: 'error', message });
+        },
+    });
 });
 // Listen for start command from parent — guarded against re-entry
 let started = false;
@@ -41,25 +76,21 @@ process.on('message', async (msg) => {
         return;
     started = true;
     try {
-        const result = await runFullAnalysis(msg.repoPath, msg.options, {
-            onProgress: (phase, percent, message) => {
-                send({ type: 'progress', phase, percent, message });
-            },
-            onLog: (message) => {
-                send({ type: 'progress', phase: 'log', percent: -1, message });
-            },
+        // The run → finalize → report contract lives in the side-effect-free
+        // analyze-worker-core seam (unit-testable without this entry module's
+        // process.on side effects). It reports exactly one terminal message and
+        // never throws.
+        await runWorkerAnalysis(msg.repoPath, msg.options, {
+            runFullAnalysis,
+            assertAnalysisFinalized,
+            send,
+            claimTerminal,
         });
-        // Send a JSON-safe projection, NOT the raw result: the IPC channel is
-        // default-JSON serialization and `result.pipelineResult` carries the live
-        // KnowledgeGraph (wasteful to materialize, silently corrupted by JSON, and
-        // a BigInt/circular value would throw and mis-report this success as a
-        // failure). See analyze-worker-ipc.ts.
-        send({ type: 'complete', result: projectAnalyzeResultForIpc(result) });
     }
-    catch (err) {
-        send({ type: 'error', message: err?.message || 'Analysis failed' });
+    finally {
+        // LadybugDB's native module prevents clean exit — force it (same reason the
+        // CLI uses process.exit(0)). In `finally` so the exit still fires even if the
+        // report above throws on a closed IPC channel (#2264 review P3).
+        setTimeout(() => process.exit(0), 500);
     }
-    // LadybugDB's native module prevents clean exit — force it
-    // (same reason the CLI uses process.exit(0))
-    setTimeout(() => process.exit(0), 500);
 });

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

@@ -39,6 +39,13 @@ export type { BranchSummary };
  * so the registry stabilises over analyze/re-analyze cycles.
  */
 export declare const canonicalizePath: (p: string) => string;
+/**
+ * Compare two already-canonicalised registry paths. Case-insensitive on Windows
+ * (its filesystem is), case-sensitive elsewhere. Both arguments must already be
+ * run through {@link canonicalizePath}; this is the single comparison the registry
+ * lookups/dedup/finalize checks all share so they answer identically.
+ */
+export declare const registryPathEquals: (a: string, b: string) => boolean;
 export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
@@ -476,6 +483,13 @@ export declare class AnalysisNotFinalizedError extends Error {
     readonly kind: "AnalysisNotFinalizedError";
     constructor(repoPath: string, storagePath: string, missing: 'meta' | 'registry-entry', registryPath: string);
 }
+/**
+ * True when the global registry already contains an entry whose canonical path
+ * matches `repoPath`. Uses the same canonical, case-folded (Windows) comparison
+ * as {@link assertAnalysisFinalized} so "is it registered?" answers identically
+ * at the analyze fast-path gate and at the finalize assertion. Pure read.
+ */
+export declare const isRepoRegistered: (repoPath: string) => Promise<boolean>;
 /**
  * Verify that a successful `analyze` call actually produced an indexed,
  * registered repo on disk. Two checks, both strictly required:

package/dist/storage/repo-manager.js

@@ -54,6 +54,13 @@ export const canonicalizePath = (p) => {
         return resolved;
     }
 };
+/**
+ * Compare two already-canonicalised registry paths. Case-insensitive on Windows
+ * (its filesystem is), case-sensitive elsewhere. Both arguments must already be
+ * run through {@link canonicalizePath}; this is the single comparison the registry
+ * lookups/dedup/finalize checks all share so they answer identically.
+ */
+export const registryPathEquals = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
 /**
  * Bumped whenever incremental-indexing invariants change incompatibly.
  * v2: `BasicBlock.callees` column added (statement-precise inter-procedural
@@ -445,7 +452,7 @@ export const registerRepo = async (repoPath, meta, opts) => {
         // to a stable key instead of throwing.
         const a = canonicalizePath(e.path);
         const b = canonicalInput;
-        return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+        return registryPathEquals(a, b);
     });
     const existing = existingIdx >= 0 ? entries[existingIdx] : null;
     // Precedence: explicit --name > preserved alias > remote-inferred > basename.
@@ -548,9 +555,7 @@ export const registerRepo = async (repoPath, meta, opts) => {
     const fresh = await readRegistry();
     const freshIdx = fresh.findIndex((e) => {
         const a = canonicalizePath(e.path);
-        return process.platform === 'win32'
-            ? a.toLowerCase() === canonicalInput.toLowerCase()
-            : a === canonicalInput;
+        return registryPathEquals(a, canonicalInput);
     });
     const freshExisting = freshIdx >= 0 ? fresh[freshIdx] : null;
     let merged;
@@ -591,8 +596,7 @@ export const unregisterRepo = async (repoPath) => {
     // `resolveRegistryEntry` post-#1003 review.
     const resolved = canonicalizePath(repoPath);
     const entries = await readRegistry();
-    const matches = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
-    const filtered = entries.filter((e) => !matches(canonicalizePath(e.path), resolved));
+    const filtered = entries.filter((e) => !registryPathEquals(canonicalizePath(e.path), resolved));
     await writeRegistry(filtered);
 };
 /**
@@ -605,9 +609,8 @@ export const unregisterRepo = async (repoPath) => {
  */
 export const removeBranchIndex = async (repoPath, branch) => {
     const resolved = canonicalizePath(repoPath);
-    const matches = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
     const entries = await readRegistry();
-    const idx = entries.findIndex((e) => matches(canonicalizePath(e.path), resolved));
+    const idx = entries.findIndex((e) => registryPathEquals(canonicalizePath(e.path), resolved));
     if (idx < 0)
         return false;
     const entry = entries[idx];
@@ -708,6 +711,17 @@ export class AnalysisNotFinalizedError extends Error {
         this.name = 'AnalysisNotFinalizedError';
     }
 }
+/**
+ * True when the global registry already contains an entry whose canonical path
+ * matches `repoPath`. Uses the same canonical, case-folded (Windows) comparison
+ * as {@link assertAnalysisFinalized} so "is it registered?" answers identically
+ * at the analyze fast-path gate and at the finalize assertion. Pure read.
+ */
+export const isRepoRegistered = async (repoPath) => {
+    const entries = await readRegistry();
+    const canonicalInput = canonicalizePath(path.resolve(repoPath));
+    return entries.some((e) => registryPathEquals(canonicalizePath(e.path), canonicalInput));
+};
 /**
  * Verify that a successful `analyze` call actually produced an indexed,
  * registered repo on disk. Two checks, both strictly required:
@@ -731,14 +745,7 @@ export const assertAnalysisFinalized = async (repoPath) => {
     catch {
         throw new AnalysisNotFinalizedError(resolved, storagePath, 'meta', getGlobalRegistryPath());
     }
-    const entries = await readRegistry();
-    const canonicalInput = canonicalizePath(resolved);
-    const isWin = process.platform === 'win32';
-    const found = entries.some((e) => {
-        const a = canonicalizePath(e.path);
-        return isWin ? a.toLowerCase() === canonicalInput.toLowerCase() : a === canonicalInput;
-    });
-    if (!found) {
+    if (!(await isRepoRegistered(resolved))) {
         throw new AnalysisNotFinalizedError(resolved, storagePath, 'registry-entry', getGlobalRegistryPath());
     }
 };
@@ -845,7 +852,7 @@ export const resolveRegistryEntry = (entries, target) => {
     const pathMatch = entries.find((e) => {
         const a = canonicalizePath(e.path);
         const b = canonicalTarget;
-        return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+        return registryPathEquals(a, b);
     });
     if (pathMatch)
         return pathMatch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8",
+  "version": "1.6.9-rc.2",
   "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",