cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/cli/analyze.js

@@ -0,0 +1,1086 @@
+"use strict";
+/**
+ * Analyze Command
+ *
+ * Indexes a repository and stores the knowledge graph in .cgraphx/code/
+ *
+ * Delegates core analysis to the shared runFullAnalysis orchestrator.
+ * This CLI wrapper handles: heap management, progress bar, SIGINT,
+ * summary output, and process.exit().
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCommandWithRunnerIdentity = exports.analyzeCommand = void 0;
+exports.computeHeapCapMb = computeHeapCapMb;
+exports.parseMaxOldSpaceMb = parseMaxOldSpaceMb;
+const path_1 = __importDefault(require("path"));
+const node_fs_1 = require("node:fs");
+const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
+const v8_1 = __importDefault(require("v8"));
+const cli_progress_1 = __importDefault(require("cli-progress"));
+const lbug_adapter_js_1 = require("../core/lbug/lbug-adapter.js");
+const shutdown_helpers_js_1 = require("../core/lbug/shutdown-helpers.js");
+const rel_pair_routing_js_1 = require("../core/lbug/rel-pair-routing.js");
+const utils_js_1 = require("../lib/utils.js");
+const lbug_config_js_1 = require("../core/lbug/lbug-config.js");
+const repo_manager_js_1 = require("../storage/repo-manager.js");
+const git_js_1 = require("../storage/git.js");
+const index_lock_js_1 = require("../storage/index-lock.js");
+const analyze_config_js_1 = require("./analyze-config.js");
+const run_analyze_js_1 = require("../core/run-analyze.js");
+const workspace_config_js_1 = require("../core/ingestion/workspace-config.js");
+const capabilities_js_1 = require("../core/platform/capabilities.js");
+const max_file_size_js_1 = require("../core/ingestion/utils/max-file-size.js");
+const optional_grammars_js_1 = require("./optional-grammars.js");
+const glob_1 = require("glob");
+const cli_message_js_1 = require("./cli-message.js");
+const effective_ram_js_1 = require("../core/ingestion/utils/effective-ram.js");
+const format_elapsed_js_1 = require("./format-elapsed.js");
+const resolve_invocation_js_1 = require("./resolve-invocation.js");
+// Capture stderr.write at module load BEFORE anything (LadybugDB native
+// init, progress bar, console redirection) can monkey-patch it. The
+// fatal handlers below MUST reach the user even when the analyze path
+// has redirected console.* through the progress bar's bar.log() — the
+// previous behaviour silently swallowed stack traces and made #1169
+// indistinguishable from a no-op success on Windows.
+const realStderrWrite = process.stderr.write.bind(process.stderr);
+const realStdoutWrite = process.stdout.write.bind(process.stdout);
+const writeFatalToStderr = (label, err) => {
+    const isErr = err instanceof Error;
+    const message = isErr ? err.message : String(err);
+    realStderrWrite(`\n  ${label}: ${message}\n`);
+    if (isErr && err.stack)
+        realStderrWrite(`${err.stack}\n`);
+    // Walk and print the `cause` chain. The phase runner wraps the underlying
+    // failure as `new Error("Phase 'X' failed: …", { cause })`, so the original
+    // error (e.g. a WorkerPoolDispatchError carrying the worker-side stack from
+    // #2068) is only reachable via `.cause`. Without this the user sees the
+    // wrapper's main-thread stack and never the real frame. `cause.stack` already
+    // begins with the cause's message, so we print the stack alone (not message +
+    // stack) to avoid repeating it. `causeChain` owns the traversal and the depth
+    // bound that stops a cyclic `cause` looping — this used to be one of four
+    // hand-rolled copies that had already drifted apart on both. Uses
+    // realStderrWrite so the redirected console.error's ANSI clear-line wrapping
+    // can't erase it (#1169). The head is skipped: it was just printed above.
+    for (const cause of (0, utils_js_1.causeChain)(isErr ? err.cause : undefined)) {
+        realStderrWrite(`\n  Caused by: ${cause.stack ?? cause.message}\n`);
+    }
+};
+let fatalHandlersInstalled = false;
+/**
+ * Install one-shot `unhandledRejection` / `uncaughtException` handlers
+ * that surface the failure to the real stderr (bypassing any console
+ * redirection installed by the progress bar) and force a non-zero exit
+ * code. Without these, an async error escaping {@link analyzeCommand}'s
+ * try/catch was reported as exit 0 with no diagnostic — the silent
+ * failure mode tracked in #1169.
+ */
+const installFatalHandlers = () => {
+    if (fatalHandlersInstalled)
+        return;
+    fatalHandlersInstalled = true;
+    process.on('unhandledRejection', (err) => {
+        writeFatalToStderr('Analysis failed (unhandled rejection)', err);
+        process.exit(1);
+    });
+    process.on('uncaughtException', (err) => {
+        writeFatalToStderr('Analysis failed (uncaught exception)', err);
+        process.exit(1);
+    });
+};
+/**
+ * RAM-aware re-exec heap cap (MB) — the formula itself is single-sourced in
+ * `core/ingestion/utils/effective-ram.ts` (`heapCapMbFor`), shared with the
+ * server's analyze fork. `constrainedBytes` is the cgroup limit or `null`;
+ * it is honored only as a real, smaller-than-physical cap, because
+ * `process.constrainedMemory()` returns a huge sentinel when UNCONSTRAINED.
+ * (Observed rationale: a cap ≥ RAM made V8 collect lazily and swap-thrash —
+ * the #2649 worker-timeout cascade on 16 GB boxes.)
+ */
+function computeHeapCapMb(totalBytes, constrainedBytes) {
+    const effectiveBytes = constrainedBytes !== null && constrainedBytes > 0 && constrainedBytes < totalBytes
+        ? constrainedBytes
+        : totalBytes;
+    return (0, effective_ram_js_1.heapCapMbFor)(effectiveBytes);
+}
+function readConstrainedBytes() {
+    if (typeof process.constrainedMemory !== 'function')
+        return null;
+    const c = process.constrainedMemory();
+    return typeof c === 'number' && c > 0 ? c : null;
+}
+const HEAP_MB = computeHeapCapMb(os_1.default.totalmem(), readConstrainedBytes());
+const TEST_RESPAWN_HEAP_MB = Number(process.env.CGRAPH_TEST_RESPAWN_HEAP_MB);
+const RESPAWN_HEAP_MB = Number.isFinite(TEST_RESPAWN_HEAP_MB) && TEST_RESPAWN_HEAP_MB > 0
+    ? Math.floor(TEST_RESPAWN_HEAP_MB)
+    : HEAP_MB;
+const HEAP_FLAG = `--max-old-space-size=${RESPAWN_HEAP_MB}`;
+/** Larger semi-space (young-gen) cuts minor-GC frequency + promotion churn during
+ *  the multi-million-node graph build/emit. Allowed in NODE_OPTIONS (unlike
+ *  --stack-size), so it propagates to the re-exec env cleanly. */
+const SEMI_SPACE_MB = 128;
+const SEMI_FLAG = `--max-semi-space-size=${SEMI_SPACE_MB}`;
+/** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
+const STACK_KB = 4096;
+const STACK_FLAG = `--stack-size=${STACK_KB}`;
+const RESPAWN_OUTPUT_TAIL_CHARS = 1024 * 1024;
+const RESPAWN_PROGRESS_ENV = 'CGRAPH_RESPAWN_PROGRESS_TTY';
+const terminalColumns = () => {
+    const parsed = Number(process.env.COLUMNS);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 80;
+};
+const ANSI_ESCAPE_PATTERN = /\x1B(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\)|[PX^_][\s\S]*?\x1B\\|[78]|[@-Z\\-_])/y;
+const splitGraphemes = (text) => {
+    const Segmenter = Intl.Segmenter;
+    if (Segmenter) {
+        return Array.from(new Segmenter(undefined, { granularity: 'grapheme' }).segment(text), (s) => s.segment);
+    }
+    return Array.from(text);
+};
+const isZeroWidthCodePoint = (codePoint) => codePoint === 0x200d ||
+    (codePoint >= 0x0300 && codePoint <= 0x036f) ||
+    (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+    (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+    (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+    (codePoint >= 0xfe00 && codePoint <= 0xfe0f) ||
+    (codePoint >= 0xfe20 && codePoint <= 0xfe2f);
+const isWideCodePoint = (codePoint) => codePoint >= 0x1100 &&
+    (codePoint <= 0x115f ||
+        codePoint === 0x2329 ||
+        codePoint === 0x232a ||
+        (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+        (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+        (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+        (codePoint >= 0x1f300 && codePoint <= 0x1faff) ||
+        (codePoint >= 0x20000 && codePoint <= 0x3fffd));
+const visibleColumns = (text) => {
+    let columns = 0;
+    for (const char of Array.from(text)) {
+        const codePoint = char.codePointAt(0);
+        if (codePoint === undefined || isZeroWidthCodePoint(codePoint))
+            continue;
+        columns += isWideCodePoint(codePoint) ? 2 : 1;
+    }
+    return columns;
+};
+const readAnsiEscapeAt = (text, index) => {
+    ANSI_ESCAPE_PATTERN.lastIndex = index;
+    return ANSI_ESCAPE_PATTERN.exec(text)?.[0];
+};
+const truncateAnsiToColumns = (text, maxColumns) => {
+    if (!Number.isFinite(maxColumns) || maxColumns <= 0)
+        return '';
+    let output = '';
+    let columns = 0;
+    let index = 0;
+    while (index < text.length) {
+        const escape = readAnsiEscapeAt(text, index);
+        if (escape) {
+            output += escape;
+            index += escape.length;
+            continue;
+        }
+        const nextEscapeIndex = text.indexOf('\x1B', index);
+        const plainEnd = nextEscapeIndex === -1 ? text.length : nextEscapeIndex;
+        const plainText = text.slice(index, plainEnd);
+        for (const segment of splitGraphemes(plainText)) {
+            const width = visibleColumns(segment);
+            if (width > 0 && columns + width > maxColumns)
+                return output;
+            output += segment;
+            columns += width;
+        }
+        index = plainEnd;
+    }
+    return output;
+};
+const createAnsiPipeTerminal = (stream) => {
+    let linewrap = true;
+    let dy = 0;
+    const write = (s) => {
+        stream.write(s);
+    };
+    const moveVertical = (delta) => {
+        if (delta > 0)
+            write(`\x1B[${delta}B`);
+        else if (delta < 0)
+            write(`\x1B[${Math.abs(delta)}A`);
+    };
+    return {
+        cursorSave: () => write('\x1B7'),
+        cursorRestore: () => write('\x1B8'),
+        cursor: (enabled) => write(enabled ? '\x1B[?25h' : '\x1B[?25l'),
+        lineWrapping: (enabled) => {
+            linewrap = enabled;
+            write(enabled ? '\x1B[?7h' : '\x1B[?7l');
+        },
+        cursorTo: (x = null, y = null) => {
+            if (typeof y === 'number' && typeof x === 'number') {
+                write(`\x1B[${y + 1};${x + 1}H`);
+                return;
+            }
+            if (typeof x === 'number') {
+                write(x === 0 ? '\r' : `\x1B[${x + 1}G`);
+            }
+        },
+        cursorRelative: (dx = null, nextDy = null) => {
+            if (typeof dx === 'number' && dx !== 0) {
+                write(dx > 0 ? `\x1B[${dx}C` : `\x1B[${Math.abs(dx)}D`);
+            }
+            if (typeof nextDy === 'number' && nextDy !== 0) {
+                dy += nextDy;
+                moveVertical(nextDy);
+            }
+        },
+        cursorRelativeReset: () => {
+            moveVertical(-dy);
+            write('\r');
+            dy = 0;
+        },
+        clearRight: () => write('\x1B[0K'),
+        clearLine: () => write('\x1B[2K'),
+        clearBottom: () => write('\x1B[0J'),
+        newline: () => {
+            write('\n');
+            dy++;
+        },
+        write: (s, rawWrite = false) => {
+            const width = terminalColumns();
+            write(linewrap && rawWrite === false ? truncateAnsiToColumns(s, width) : s);
+        },
+        isTTY: () => true,
+        getWidth: terminalColumns,
+    };
+};
+const shouldBridgeRespawnProgressTty = () => process.stderr.isTTY === true || process.stdout.isTTY === true;
+const appendOutputTail = (tail, chunk) => {
+    const text = Buffer.isBuffer(chunk)
+        ? chunk.toString('utf8')
+        : typeof chunk === 'string'
+            ? chunk
+            : String(chunk ?? '');
+    if (!text)
+        return tail;
+    const next = tail + text;
+    return next.length > RESPAWN_OUTPUT_TAIL_CHARS ? next.slice(-RESPAWN_OUTPUT_TAIL_CHARS) : next;
+};
+/**
+ * Run the respawned analyzer while teeing child output through to the parent
+ * and keeping a bounded tail for crash classification.
+ *
+ * `execFileSync(..., { stdio: 'inherit' })` preserved live progress but hid
+ * stderr/stdout from the parent on abnormal exits. That made every
+ * SIGABRT/status-134 child look like an output-less V8 heap OOM, even when the
+ * terminal had already shown a native crash such as
+ * `libc++abi: ... Napi::Error`. Piped streams plus an explicit tee keeps the UX
+ * and gives `childProcessLikelyOom` the evidence it needs.
+ */
+const runRespawnedAnalyze = (args, env) => new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (exit) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve(exit);
+    };
+    const child = (0, child_process_1.spawn)(process.execPath, [...args], {
+        stdio: ['inherit', 'pipe', 'pipe'],
+        windowsHide: true,
+        env,
+    });
+    child.stdout?.on('data', (chunk) => {
+        stdout = appendOutputTail(stdout, chunk);
+        realStdoutWrite(chunk);
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderr = appendOutputTail(stderr, chunk);
+        realStderrWrite(chunk);
+    });
+    child.on('error', (err) => {
+        finish({
+            status: 1,
+            signal: null,
+            stdout,
+            stderr,
+            message: err instanceof Error ? err.message : String(err),
+        });
+    });
+    child.on('close', (status, signal) => {
+        finish({
+            status,
+            signal,
+            stdout,
+            stderr,
+            message: `Command failed: ${process.execPath} ${args.join(' ')}`,
+        });
+    });
+});
+/**
+ * Heuristic for "child re-exec likely died from V8 OOM".
+ *
+ * Platform-independent detection is best-effort: V8/Node usually emit stable
+ * heap-exhaustion phrases in stderr/message across Linux/macOS/Windows (for
+ * example "JavaScript heap out of memory" or "Reached heap limit"). When the
+ * child produced no output at all, we still treat status 134/SIGABRT as likely
+ * heap OOM. If stderr/stdout contains a native crash diagnostic, the output
+ * evidence wins and we do not print heap guidance.
+ */
+const childProcessLikelyOom = (err) => {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    const hasHeapOomSignature = (v) => {
+        const text = (Buffer.isBuffer(v) ? v.toString('utf8') : typeof v === 'string' ? v : '').toLowerCase();
+        if (!text)
+            return false;
+        return (text.includes('javascript heap out of memory') ||
+            text.includes('reached heap limit') ||
+            text.includes('allocation failed - javascript heap out of memory') ||
+            text.includes('fatalprocessoutofmemory'));
+    };
+    const fields = [e.message, e.stderr, e.stdout];
+    if (fields.some((v) => hasHeapOomSignature(v)))
+        return true;
+    const hasAnyChildOutput = [e.stderr, e.stdout].some((v) => (Buffer.isBuffer(v) && v.length > 0) || (typeof v === 'string' && v.length > 0));
+    if (hasAnyChildOutput)
+        return false;
+    return e.status === 134 || e.signal === 'SIGABRT';
+};
+const childProcessLikelyNativeAbort = (err) => {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    const hasNativeAbortSignature = (v) => {
+        const text = (Buffer.isBuffer(v) ? v.toString('utf8') : typeof v === 'string' ? v : '').toLowerCase();
+        if (!text)
+            return false;
+        return (text.includes('napi::error') ||
+            text.includes('libc++abi: terminating') ||
+            text.includes('abort trap') ||
+            text.includes('native stack') ||
+            text.includes('native worker') ||
+            text.includes('native binding'));
+    };
+    return [e.message, e.stderr, e.stdout].some((v) => hasNativeAbortSignature(v));
+};
+const forceHeapOOMForTestIfEnabled = () => {
+    if (process.env.CGRAPH_TEST_FORCE_HEAP_OOM !== '1')
+        return;
+    // Allocate JS strings (not Buffers) so pressure lands on V8 heap itself.
+    // Buffers can allocate off-heap, which makes OOM triggering less reliable.
+    const chunks = [];
+    for (;;)
+        chunks.push('x'.repeat(1024 * 1024));
+};
+// 64 MiB keeps auto-checkpoint enabled but triggers less frequently than
+// Ladybug's stock ~16 MiB threshold, reducing rename/remove churn on large
+// runs. Also matches the GitNexus default in `lbug-config.ts`.
+//
+// IMPORTANT: keep README examples (`README.md`, `cgraph/README.md`) and
+// the `DEFAULT_WAL_CHECKPOINT_THRESHOLD` constant in
+// `cgraph/src/core/lbug/lbug-config.ts` in sync with this value.
+const RECOMMENDED_WAL_CHECKPOINT_THRESHOLD = 64 * 1024 * 1024;
+/**
+ * Last `--max-old-space-size` value (MB) in a NODE_OPTIONS string, or `null`
+ * when absent/unparseable. Last occurrence wins, matching V8's own
+ * later-flag-wins semantics when NODE_OPTIONS repeats a flag.
+ */
+function parseMaxOldSpaceMb(nodeOptions) {
+    // V8 accepts `-` and `_` interchangeably in flag names, and Node accepts a
+    // space-separated value in NODE_OPTIONS — honor every spelling of the pin
+    // instead of silently overriding it (#2649 review).
+    const matches = [...nodeOptions.matchAll(/--max[-_]old[-_]space[-_]size(?:=|\s+)(\d+)/g)];
+    if (matches.length === 0)
+        return null;
+    const mb = Number(matches[matches.length - 1][1]);
+    return Number.isFinite(mb) && mb > 0 ? mb : null;
+}
+/** Re-exec the process with the RAM-aware auto heap cap + larger semi-space/stack
+ *  if we're currently below that.
+ *
+ *  Heap-source precedence (#2649):
+ *  - an explicit per-invocation `--max-old-space-size` (execArgv) always wins;
+ *  - `CGRAPH_MEMORY=off` declines the memory autopilot entirely;
+ *  - an ambient NODE_OPTIONS heap >= the auto cap is honored as-is;
+ *  - an ambient NODE_OPTIONS heap BELOW the auto cap is treated as an
+ *    inherited environment default (devcontainers/CI export one for other
+ *    tooling), not a deliberate per-run choice: warn and respawn with the
+ *    auto cap. Pre-#2649 this returned early and large repos then OOM'd on
+ *    whatever heap the environment happened to specify. */
+async function ensureHeap() {
+    // Explicit opt-out disables auto-sizing ENTIRELY — both the ambient-pin
+    // override and the default v8-limit respawn — and is honored SILENTLY:
+    // the operator already made the call, and stderr-sensitive consumers
+    // (test harnesses, scripts, supervisors that track a single PID) rely on
+    // a quiet, single-process run.
+    if ((0, effective_ram_js_1.memoryAutopilotDisabled)())
+        return false;
+    const nodeOpts = process.env.NODE_OPTIONS || '';
+    if (process.execArgv.some((a) => a.startsWith('--max-old-space-size')))
+        return false;
+    const ambientHeapMb = parseMaxOldSpaceMb(nodeOpts);
+    if (ambientHeapMb !== null) {
+        if (ambientHeapMb >= RESPAWN_HEAP_MB)
+            return false;
+        (0, cli_message_js_1.cliWarn)(`  NODE_OPTIONS pins the heap to ${ambientHeapMb}MB — below the ${RESPAWN_HEAP_MB}MB this machine's RAM supports.\n` +
+            `  Re-running analyze with the larger auto-sized cap (set CGRAPH_MEMORY=off to keep the NODE_OPTIONS value).\n`);
+    }
+    else {
+        const v8Heap = v8_1.default.getHeapStatistics().heap_size_limit;
+        if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
+            return false;
+    }
+    // --stack-size is a V8 flag not allowed in NODE_OPTIONS on Node 24+, so pass it
+    // only as a direct CLI argument. --max-semi-space-size IS allowed in NODE_OPTIONS.
+    const cliFlags = [HEAP_FLAG, SEMI_FLAG];
+    if (!nodeOpts.includes('--stack-size'))
+        cliFlags.push(STACK_FLAG);
+    // Preserve the parent's node flags (execArgv) — dropping them breaks any
+    // loader-launched CLI: `node --import tsx src/cli/index.ts` respawned
+    // without `--import tsx` cannot execute TypeScript and dies with a
+    // swallowed exit 1 (#2649 review). Our heap/semi/stack flags come AFTER
+    // execArgv so V8's later-flag-wins semantics resolve duplicates our way.
+    // Inspector flags are the one exception: replaying `--inspect[-brk]` makes
+    // the child fight the parent for the debug port and die with EADDRINUSE.
+    const preservedExecArgv = process.execArgv.filter((a) => !a.startsWith('--inspect'));
+    const childArgs = [...preservedExecArgv, ...cliFlags, ...process.argv.slice(1)];
+    const childEnv = {
+        ...process.env,
+        NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG} ${SEMI_FLAG}`.trim(),
+    };
+    if (shouldBridgeRespawnProgressTty())
+        childEnv[RESPAWN_PROGRESS_ENV] = '1';
+    const childExit = await runRespawnedAnalyze(childArgs, childEnv);
+    if (childExit.status !== 0 || childExit.signal) {
+        if (childProcessLikelyOom(childExit)) {
+            (0, cli_message_js_1.cliError)(`  Analysis likely ran out of memory (heap cap auto-sized to ${RESPAWN_HEAP_MB}MB ≈ 0.75x RAM).\n` +
+                `  This repository's working set exceeds available RAM. Use a machine with more RAM,\n` +
+                `  or override the cap (a cap above physical RAM causes swap-thrash — use with care):\n` +
+                `    NODE_OPTIONS="--max-old-space-size=<MB>" cgraph analyze [your-args]\n` +
+                `    (Windows: set NODE_OPTIONS=--max-old-space-size=<MB> && cgraph analyze [your-args])\n` +
+                `  If this persists, it may be a native crash unrelated to heap size.\n`, { recoveryHint: 'heap-oom-respawn' });
+        }
+        else if (childProcessLikelyNativeAbort(childExit)) {
+            (0, cli_message_js_1.cliError)(`  Analysis aborted in a native worker or native binding path.\n` +
+                `  Try one of these recovery paths:\n` +
+                `    npm uninstall -g cgraph && npm install -g cgraph@latest (rebuilds native bindings)\n` +
+                `    Use Node 22 LTS if you are on a newer non-LTS runtime.\n`, { recoveryHint: 'native-worker-abort' });
+        }
+        const status = typeof childExit.status === 'number' && childExit.status !== 0 ? childExit.status : 1;
+        process.exitCode = status;
+    }
+    return true;
+}
+/**
+ * CGRAPH_* env vars that `analyzeCommand` writes for backward-compatible
+ * downstream consumption. Snapshotted at function entry and restored in the
+ * finally block so that programmatic callers (tests, long-running hosts)
+ * don't see leaked state across invocations. `CGRAPH_WORKER_POOL_SIZE` is
+ * NOT in this list: that knob is threaded through `runFullAnalysis` options
+ * (see `workerPoolSize` plumbing) so the CLI never has to mutate `process.env`
+ * for it in the first place.
+ */
+const ANALYZE_CLI_ENV_KEYS = [
+    'CGRAPH_VERBOSE',
+    'CGRAPH_PROFILE_DEFERRED',
+    'CGRAPH_PROFILE_DEFERRED_SLOW_MS',
+    'CGRAPH_DEBUG_HEAP',
+    'CGRAPH_MAX_FILE_SIZE',
+    'CGRAPH_WORKER_SUB_BATCH_TIMEOUT_MS',
+    'CGRAPH_WAL_CHECKPOINT_THRESHOLD',
+    'CGRAPH_WAL_MANUAL_CHECKPOINT',
+    'CGRAPH_ANALYZE_PROGRESS_ACTIVE',
+];
+const snapshotAnalyzeEnv = () => {
+    const snap = {};
+    for (const k of ANALYZE_CLI_ENV_KEYS)
+        snap[k] = process.env[k];
+    return snap;
+};
+const restoreAnalyzeEnv = (snap) => {
+    for (const k of ANALYZE_CLI_ENV_KEYS) {
+        const v = snap[k];
+        if (v === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = v;
+    }
+};
+const analyzeCommand = async (inputPath, options, runnerIdentityAtBootstrap) => {
+    if (await ensureHeap())
+        return;
+    forceHeapOOMForTestIfEnabled();
+    // Install fatal handlers immediately after re-exec resolution so any
+    // async error that escapes the try/catch below (#1169) surfaces with
+    // a stack trace and a non-zero exit code instead of a silent exit 0.
+    installFatalHandlers();
+    // npm-11 npx-crash nudge (#1939). Runs here, after the heap re-exec guard,
+    // so it fires once in the working process and never on the lazy-startup path
+    // of other commands (e.g. `cgraph mcp`).
+    (0, resolve_invocation_js_1.warnIfNpm11NpxRisk)();
+    // Snapshot the CGRAPH_* env vars that the impl writes for downstream
+    // consumption, so they don't leak across `analyzeCommand` invocations in
+    // programmatic callers (tests, long-running hosts). `process.exit(0)` on
+    // the success path bypasses `finally` — intentional: when the process is
+    // exiting, restoration is moot. For early-return paths (validation
+    // errors) and the alreadyUpToDate fast path the finally restores the
+    // pre-call values.
+    const envSnap = snapshotAnalyzeEnv();
+    try {
+        await analyzeCommandImpl(inputPath, options, runnerIdentityAtBootstrap);
+    }
+    finally {
+        restoreAnalyzeEnv(envSnap);
+    }
+    // If analyzeCommandImpl returned via a soft `process.exitCode = 1` error path
+    // while LadybugDB native handles are still open, the event loop won't drain and
+    // the process would HANG (#2264 review P1). The full analyze paths skip-close the
+    // DB — handles are left open and reclaimed by process.exit — so a soft return
+    // after a real analyze must force the exit. The success path never reaches here
+    // (analyzeCommandImpl calls process.exit(0) itself); early-validation errors and
+    // unit tests that mock runFullAnalysis never open the DB, so isLbugReady() is
+    // false and the soft return is preserved.
+    if ((0, lbug_adapter_js_1.isLbugReady)()) {
+        process.exit(typeof process.exitCode === 'number' ? process.exitCode : 1);
+    }
+};
+exports.analyzeCommand = analyzeCommand;
+/** Commander entrypoint used only by the capture-before-import lazy bootstrap. */
+const analyzeCommandWithRunnerIdentity = async (runnerIdentityAtBootstrap, inputPath, options) => (0, exports.analyzeCommand)(inputPath, options, runnerIdentityAtBootstrap);
+exports.analyzeCommandWithRunnerIdentity = analyzeCommandWithRunnerIdentity;
+const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstrap) => {
+    console.log('\n  GitNexus Analyzer\n');
+    // ── 解析索引根目录 ────────────────────────────────────────────────
+    // 最先解析:`.cgraphrc` 从索引根读取(而非调用方 cwd),配置可为下方校验设置默认值。
+    // 无 git 仓库时自动降级为纯目录索引(plain-folder)——给出警告但不报错退出,
+    // 支持「根非 git + 子工程各自 git」的聚合根(spec §4/§9)。
+    let repoPath;
+    if (inputPath) {
+        repoPath = path_1.default.resolve(inputPath);
+        // 显式指定的路径不存在 → 直接报错退出。plain-folder 降级仅适用于「存在但非 git」
+        // 的目录,不适用于不存在的路径(spec §4)。仅在显式 inputPath 时检查:
+        // 未指定时 repoPath 来自 getGitRoot(cwd) 或 cwd 本身,必然存在。
+        if (!(0, node_fs_1.existsSync)(repoPath)) {
+            (0, cli_message_js_1.cliError)(`[cgraph] 索引根目录不存在: ${repoPath}\n  请检查路径是否正确。\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else {
+        const gitRoot = (0, git_js_1.getGitRoot)(process.cwd());
+        // 无 git root → 降级为 cwd 纯目录;显式 inputPath 同样不向上查找 git 根。
+        repoPath = gitRoot ?? path_1.default.resolve(process.cwd());
+    }
+    const repoHasGit = (0, git_js_1.hasGitDir)(repoPath);
+    if (!repoHasGit) {
+        // plain-folder 降级:commit 跟踪不可用,但索引正常构建。
+        // v1 无增量概念,警告不得提及 incremental(spec §4)。
+        (0, cli_message_js_1.cliWarn)('[cgraph] 未发现 .git——按纯目录分析(commit 跟踪不可用)');
+    }
+    // Validate the index-branch selector (#2106), so a malformed
+    // `--branch` exits before any expensive analysis starts. Capture the TRIMMED
+    // return so a whitespace-padded value (e.g. " feature" from shell completion)
+    // normalizes before the checked-out-branch mismatch guard and slug — otherwise
+    // it would false-reject on-branch or create a ghost index when detached.
+    if (cliOptions?.branch !== undefined) {
+        try {
+            cliOptions.branch = (0, analyze_config_js_1.validateBranchName)(cliOptions.branch, '--branch');
+        }
+        catch (err) {
+            (0, cli_message_js_1.cliError)(`  ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // ── Load .cgraphrc and merge: CLI flags override config (#243) ───
+    // Parse/validate before the progress bar so a malformed config produces an
+    // actionable error and exits before any expensive analysis starts.
+    let options;
+    try {
+        const fileConfig = (0, analyze_config_js_1.loadAnalyzeConfig)(repoPath);
+        options = (0, analyze_config_js_1.mergeAnalyzeOptions)(cliOptions ?? {}, fileConfig);
+    }
+    catch (err) {
+        const msg = err instanceof analyze_config_js_1.GitNexusRcError
+            ? err.message
+            : `Invalid .cgraphrc: ${err instanceof Error ? err.message : String(err)}`;
+        (0, cli_message_js_1.cliError)(`  ${msg}\n`, { recoveryHint: 'cgraphrc-invalid' });
+        process.exitCode = 1;
+        return;
+    }
+    if (options.verbose) {
+        process.env.CGRAPH_VERBOSE = '1';
+    }
+    if (options.maxFileSize) {
+        process.env.CGRAPH_MAX_FILE_SIZE = options.maxFileSize;
+    }
+    if (options.workerTimeout) {
+        const workerTimeoutSeconds = Number(options.workerTimeout);
+        if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
+            (0, cli_message_js_1.cliError)('  --worker-timeout must be at least 1 second.\n');
+            process.exitCode = 1;
+            return;
+        }
+        process.env.CGRAPH_WORKER_SUB_BATCH_TIMEOUT_MS = String(Math.round(workerTimeoutSeconds * 1000));
+    }
+    if (options.walCheckpointThreshold !== undefined) {
+        const parsed = (0, lbug_config_js_1.parseWalCheckpointThreshold)(options.walCheckpointThreshold);
+        if (parsed === undefined) {
+            (0, cli_message_js_1.cliError)('  --wal-checkpoint-threshold must be an integer >= -1.\n');
+            process.exitCode = 1;
+            return;
+        }
+        process.env.CGRAPH_WAL_CHECKPOINT_THRESHOLD = String(parsed);
+    }
+    // `--workers` is threaded through `runFullAnalysis` options → PipelineOptions
+    // → createWorkerPool, intentionally bypassing the CGRAPH_WORKER_POOL_SIZE
+    // env channel so this CLI surface never mutates `process.env` for pool size.
+    // Tests can therefore re-invoke analyzeCommand with different --workers
+    // values back-to-back and observe the value they passed, not whatever the
+    // previous call leaked.
+    let workerPoolSize;
+    if (options.workers !== undefined) {
+        const parsedWorkers = Number(options.workers);
+        if (!Number.isInteger(parsedWorkers) || parsedWorkers < 1) {
+            (0, cli_message_js_1.cliError)('  --workers must be a positive integer (>= 1). ' +
+                'GitNexus parses through a worker pool only — there is no sequential ' +
+                'mode, so 0 is not allowed. Omit --workers for an auto-sized pool.\n');
+            process.exitCode = 1;
+            return;
+        }
+        workerPoolSize = parsedWorkers;
+    }
+    // If the target repo contains files an optional grammar would parse but
+    // that grammar's native binding is absent (or disabled via
+    // CGRAPH_SKIP_OPTIONAL_GRAMMARS), warn before analysis so users learn why
+    // those files end up unparsed instead of silently getting a degraded index.
+    // The extension set is derived from OPTIONAL_GRAMMARS so it can't drift.
+    try {
+        const optionalGlobs = (0, optional_grammars_js_1.getOptionalGrammarExtensions)().map((e) => `**/*${e}`);
+        const matches = await (0, glob_1.glob)(optionalGlobs, {
+            cwd: repoPath,
+            ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
+            dot: false,
+            nodir: true,
+            absolute: false,
+        });
+        if (matches.length > 0) {
+            const present = new Set();
+            for (const m of matches) {
+                const ext = path_1.default.extname(m).toLowerCase();
+                if (ext)
+                    present.add(ext);
+            }
+            (0, optional_grammars_js_1.warnMissingOptionalGrammars)({ context: 'analyze', relevantExtensions: present });
+        }
+    }
+    catch {
+        // Best-effort warning \u2014 never block analyze on the precheck.
+    }
+    // KuzuDB migration cleanup is handled by runFullAnalysis internally.
+    if (process.env.CGRAPH_NO_GITIGNORE) {
+        console.log('  CGRAPH_NO_GITIGNORE is set — skipping .gitignore (still reading .cgraphignore)\n');
+    }
+    const maxFileSizeBanner = (0, max_file_size_js_1.getMaxFileSizeBannerMessage)();
+    if (maxFileSizeBanner) {
+        console.log(`${maxFileSizeBanner}\n`);
+    }
+    // ── CLI progress bar setup ─────────────────────────────────────────
+    const barOptions = {
+        format: '  {bar} {percentage}% | {phase}',
+        barCompleteChar: '\u2588',
+        barIncompleteChar: '\u2591',
+        hideCursor: true,
+        barGlue: '',
+        autopadding: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
+    };
+    if (process.env[RESPAWN_PROGRESS_ENV] === '1' && process.stderr.isTTY !== true) {
+        // Heap respawn pipes stderr so the parent can classify native/OOM crashes.
+        // The parent was a real TTY when it opted into this env var, so forward
+        // ANSI cursor controls through the pipe instead of cli-progress' non-TTY
+        // newline mode. That keeps one-line redraw UX while retaining stderr tail
+        // capture for diagnostics.
+        barOptions.terminal = createAnsiPipeTerminal(process.stderr);
+    }
+    const bar = new cli_progress_1.default.SingleBar(barOptions, cli_progress_1.default.Presets.shades_grey);
+    bar.start(100, 0, { phase: 'Initializing...' });
+    // Graceful SIGINT handling. Pino's default destination is `sync: false`
+    // (buffered) — flush before exit so in-flight records reach stderr.
+    // See `cgraph/src/core/logger.ts:flushLoggerSync`.
+    let aborted = false;
+    const sigintHandler = () => {
+        if (aborted)
+            process.exit(1);
+        aborted = true;
+        bar.stop();
+        console.log('\n  Interrupted — cleaning up...');
+        // Bounded CHECKPOINT-then-exit (#2264 review P3): skip the native close (the
+        // LadybugDB destructor can double-free after --pdg writes), but don't hang
+        // behind a long --pdg COPY holding the connection lock — bound it so a single
+        // Ctrl-C stays responsive; the WAL replays on the next analyze. A second
+        // Ctrl-C (`if (aborted) process.exit(1)` above) remains the escape hatch.
+        void (0, shutdown_helpers_js_1.boundedCheckpointBeforeExit)({
+            exitCode: 130,
+            beforeExit: async () => {
+                const { flushLoggerSync } = await import('../core/logger.js');
+                flushLoggerSync();
+            },
+        });
+    };
+    process.on('SIGINT', sigintHandler);
+    // Route console output through bar.log() to prevent progress bar corruption.
+    // This is a deliberate UI pattern (not a logging concern): analyze runs a
+    // long-lived progress bar on stdout; any concurrent console.* write would
+    // overwrite the bar mid-render. We capture originals, swap to barLog for
+    // the lifetime of the run, and restore on completion/error/SIGINT.
+    const origLog = console.log.bind(console);
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
+    const origWarn = console.warn.bind(console);
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
+    const origError = console.error.bind(console);
+    let barCurrentValue = 0;
+    const barLog = (...args) => {
+        process.stdout.write('\x1b[2K\r');
+        origLog(args.map((a) => (typeof a === 'string' ? a : String(a))).join(' '));
+        bar.update(barCurrentValue);
+    };
+    console.log = barLog;
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
+    console.warn = barLog;
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
+    console.error = barLog;
+    process.env.CGRAPH_ANALYZE_PROGRESS_ACTIVE = '1';
+    // Track elapsed time per phase
+    let lastPhaseLabel = 'Initializing...';
+    let phaseStart = Date.now();
+    const updateBar = (value, phaseLabel) => {
+        barCurrentValue = value;
+        if (phaseLabel !== lastPhaseLabel) {
+            lastPhaseLabel = phaseLabel;
+            phaseStart = Date.now();
+        }
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        const display = elapsed >= 3 ? `${phaseLabel} (${(0, format_elapsed_js_1.formatElapsed)(elapsed)})` : phaseLabel;
+        bar.update(value, { phase: display });
+    };
+    const elapsedTimer = setInterval(() => {
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        if (elapsed >= 3) {
+            bar.update({ phase: `${lastPhaseLabel} (${(0, format_elapsed_js_1.formatElapsed)(elapsed)})` });
+        }
+    }, 1000);
+    const t0 = Date.now();
+    // ── Run shared analysis orchestrator ───────────────────────────────
+    try {
+        const runOptions = {
+            // Has no bearing on the registry collision guard (see
+            // allowDuplicateName below).
+            force: options.force,
+            verbose: options.verbose,
+            // CFG/PDG substrate opt-in (#2081 M1) — threaded to both sinks downstream.
+            pdg: options.pdg === true,
+            // Index-branch selector (#2106). Read straight from the CLI flag (not
+            // the .cgraphrc-merged options). Undefined → auto-detect in pipeline.
+            branch: cliOptions?.branch,
+            registryName: options.name,
+            // Registry-collision bypass — its own CLI flag, intentionally NOT
+            // overloading --force. A user who hits the collision guard should
+            // be able to accept the duplicate name without also paying the
+            // cost of a full pipeline re-index. See #829 review round 2.
+            allowDuplicateName: options.allowDuplicateName,
+            // Worker pool size threaded from --workers, replacing the previous
+            // CGRAPH_WORKER_POOL_SIZE env mutation. `undefined` defers to the
+            // env / auto-formula fallback inside the pipeline.
+            workerPoolSize,
+            // Extra fetch-wrapper names from `.cgraphrc` (#1589/#1852 residual);
+            // forwarded to the routes phase consumer scan.
+            fetchWrappers: options.fetchWrappers,
+            // The CLI always process.exit()s after this returns (success path at the
+            // end of analyzeCommandImpl, error/interrupt paths via process.exit too),
+            // so the finalize close skips the native conn/db close — it can double-free
+            // in LadybugDB's ClientContext destructor after --pdg writes (#2264). The
+            // CHECKPOINT keeps the index durable; process exit reclaims the handles.
+            skipNativeCloseOnExit: true,
+        };
+        const runCallbacks = {
+            onProgress: (_phase, percent, message) => {
+                updateBar(percent, message);
+            },
+            onLog: barLog,
+        };
+        const bootstrapArgs = runnerIdentityAtBootstrap
+            ? [runnerIdentityAtBootstrap]
+            : [];
+        const result = await (0, run_analyze_js_1.runFullAnalysis)(repoPath, runOptions, runCallbacks, ...bootstrapArgs);
+        if (result.alreadyUpToDate) {
+            // Even the fast path must prove the repo is discoverable. A prior
+            // run can write meta.json and then fail before registerRepo(); in
+            // that half-finalized state, runFullAnalysis returns alreadyUpToDate
+            // on the next invocation unless we check the registry here too.
+            await (0, repo_manager_js_1.assertAnalysisFinalized)(repoPath);
+            clearInterval(elapsedTimer);
+            process.removeListener('SIGINT', sigintHandler);
+            console.log = origLog;
+            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+            console.warn = origWarn;
+            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+            console.error = origError;
+            bar.stop();
+            console.log('  Already up to date\n');
+            // Safe to return without process.exit(0) — the early-return path in
+            // runFullAnalysis never opens LadybugDB, so no native handles prevent exit.
+            return;
+        }
+        // Post-finalize invariant (#1169): runFullAnalysis nominally writes
+        // meta.json and registers the repo, but on Windows it has been
+        // observed to return successfully with neither artifact present
+        // (banner-only output, exit 0). Verify both before declaring
+        // success so the silent-finalize state surfaces with a non-zero
+        // exit code and an actionable error instead of being mistaken for
+        // a healthy index.
+        await (0, repo_manager_js_1.assertAnalysisFinalized)(repoPath);
+        const totalTime = ((Date.now() - t0) / 1000).toFixed(1);
+        clearInterval(elapsedTimer);
+        process.removeListener('SIGINT', sigintHandler);
+        console.log = origLog;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+        console.warn = origWarn;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+        console.error = origError;
+        bar.update(100, { phase: 'Done' });
+        bar.stop();
+        // ── Summary ────────────────────────────────────────────────────
+        const s = result.stats;
+        console.log(`\n  Repository indexed successfully (${totalTime}s)\n`);
+        console.log(`  ${(s.nodes ?? 0).toLocaleString()} nodes | ${(s.edges ?? 0).toLocaleString()} edges | ${s.communities ?? 0} clusters | ${s.processes ?? 0} flows`);
+        console.log(`  ${repoPath}`);
+        console.log('');
+    }
+    catch (err) {
+        clearInterval(elapsedTimer);
+        process.removeListener('SIGINT', sigintHandler);
+        console.log = origLog;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+        console.warn = origWarn;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+        console.error = origError;
+        bar.stop();
+        const msg = err instanceof Error ? err.message : String(err);
+        // Registry name-collision from --name (#829) — surface as an
+        // actionable error rather than a generic stack-trace.
+        if (err instanceof repo_manager_js_1.RegistryNameCollisionError) {
+            (0, cli_message_js_1.cliError)(`\n  Registry name collision:\n` +
+                `    "${err.registryName}" is already used by "${err.existingPath}".\n\n` +
+                `  Options:\n` +
+                `    • Pick a different alias:  cgraph analyze --name <alias>\n` +
+                `    • Allow the duplicate:     cgraph analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)\n`, { registryName: err.registryName, existingPath: err.existingPath });
+            process.exitCode = 1;
+            return;
+        }
+        // Another analyze held the index lock past the configured wait ceiling
+        // (#2658, CGRAPH_INDEX_LOCK_TIMEOUT_MS). The on-disk index is being
+        // refreshed by the holder — this is a clean, expected condition, not a
+        // crash, so render the message without a stack trace.
+        if (err instanceof index_lock_js_1.IndexLockTimeoutError) {
+            (0, cli_message_js_1.cliError)(`  Another cgraph analyze (pid ${err.holder.pid} on ${err.holder.hostname}) is ` +
+                `already refreshing this index and did not finish within the wait window.\n` +
+                `  The on-disk index is being updated by that run. Retry later, or raise\n` +
+                `  CGRAPH_INDEX_LOCK_TIMEOUT_MS to wait longer.\n`, { recoveryHint: 'index-lock-timeout', holderPid: err.holder.pid });
+            process.exitCode = 1;
+            return;
+        }
+        // Finalize invariant failure (#1169) — keep the rich actionable
+        // message intact and write through realStderrWrite so it can't be
+        // erased by a leftover bar refresh on slow terminals.
+        if (err instanceof repo_manager_js_1.AnalysisNotFinalizedError) {
+            writeFatalToStderr('Analysis did not finalize', err);
+            realStderrWrite(`\n  Diagnostic checklist:\n` +
+                `    1. Re-run "cgraph analyze" - transient native errors often clear on retry.\n` +
+                `    2. Inspect ${err.storagePath} - a leftover lbug.wal indicates an aborted write.\n` +
+                `    3. If the failure persists, run with NODE_OPTIONS="--max-old-space-size=8192 --trace-exit"\n` +
+                `       and attach the trace to the GitNexus issue tracker.\n\n`);
+            process.exitCode = 1;
+            return;
+        }
+        // workspace 配置文件存在但解析失败/结构非法(spec §9):错误消息已自带
+        // 字段路径与修复提示,直接渲染消息(用户可修复错误,不带 stack trace 噪音)。
+        if (err instanceof workspace_config_js_1.WorkspaceConfigError) {
+            (0, cli_message_js_1.cliError)(`  ${msg.replace(/\n/g, '\n  ')}\n`, { recoveryHint: 'workspace-config' });
+            process.exitCode = 1;
+            return;
+        }
+        // An extracted edge whose FROM→TO label pair is missing from GitNexus's own
+        // relation DDL (#2789). `assertDeclaredPair` aborts the run rather than let
+        // the bulk COPY fail late and silently drop the edge, so the user sees a
+        // mid-run crash inside GitNexus internals with nothing to act on. Name the
+        // pair, the relationship and the file that produced it, and say plainly that
+        // a re-run cannot help — this is deterministic for the same input.
+        // Checked by TYPE (repo norm, #2385) BEFORE the message-text heuristics
+        // below, and through the `cause` chain because the ingestion phase runner
+        // rewraps every phase failure as `Phase 'X' failed: …`.
+        const undeclaredPair = (0, rel_pair_routing_js_1.findUndeclaredRelationPairError)(err);
+        if (undeclaredPair !== undefined) {
+            // Render the error's OWN message indented — same idiom as the
+            // `LbugWipeError` and page-size branches below. `UndeclaredRelationPairError`
+            // builds a fully self-contained message (pair, relationship type, both node
+            // ids, source file, issue URL, `.cgraphignore` workaround) precisely
+            // because `cgraph serve` forwards only `err.message` over worker IPC.
+            // Re-rendering those fields here would be a second copy of one string, free
+            // to drift from the first — and the actionable half would reach CLI users
+            // only. `undeclaredPair.message`, not the outer `msg`: the real error may be
+            // several `cause` levels below the phase wrapper `msg` came from.
+            (0, cli_message_js_1.cliError)(`  ${undeclaredPair.message.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'undeclared-relation-pair',
+                labelPair: undeclaredPair.pairKey,
+                relationType: undeclaredPair.relationType,
+                sourceFile: undeclaredPair.sourceFile,
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // WAL corruption — the index file is unreadable. Give a clear recovery
+        // path without a confusing stack trace (the native error message alone
+        // is enough signal).
+        if ((0, lbug_config_js_1.isWalCorruptionError)(err) || msg.includes('LadybugDB WAL corruption')) {
+            (0, cli_message_js_1.cliError)(`  The GitNexus index has a corrupted WAL file.\n` +
+                `  This usually happens when a previous analysis was interrupted mid-write.\n` +
+                `  ${lbug_config_js_1.WAL_RECOVERY_SUGGESTION}\n`, { recoveryHint: 'wal-corruption' });
+            process.exitCode = 1;
+            return;
+        }
+        if ((0, lbug_config_js_1.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 = (0, lbug_config_js_1.isLbugCheckpointBusyError)(err)
+                ? `  Another process may hold the store open (a running \`cgraph mcp\` server, or a\n` +
+                    `  stale reader) — close other GitNexus processes on this repo, then retry.\n`
+                : '';
+            (0, cli_message_js_1.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` +
+                `    cgraph analyze --wal-checkpoint-threshold ${RECOMMENDED_WAL_CHECKPOINT_THRESHOLD}\n` +
+                `    (or set CGRAPH_WAL_CHECKPOINT_THRESHOLD=${RECOMMENDED_WAL_CHECKPOINT_THRESHOLD})\n` +
+                `    (Try 33554432 = 32 MiB on small-disk / CI runners.)\n`, { recoveryHint: 'wal-checkpoint-threshold' });
+            process.exitCode = 1;
+            return;
+        }
+        // DB-family wipe failure (#2409, tri-review 4669518496 P2-4): the rebuild
+        // could not verify the LadybugDB file family was removed — usually another
+        // process (MCP server, serve worker, antivirus) holding the index open.
+        // Keyed on the error *type* (repo norm from #2385), never message text.
+        // The message itself is fully self-contained (survivor paths + stop-MCP /
+        // AV-exclusion / re-run guidance) because the serve worker forwards only
+        // `err.message` over IPC — this branch just renders it without the
+        // raw-stack fallback below.
+        if (err instanceof lbug_adapter_js_1.LbugWipeError) {
+            (0, cli_message_js_1.cliError)(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'lbug-wipe-failed',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Buffer-manager frame-release failure on non-4K-page kernels (#1231).
+        // LadybugDB <= 0.17.x assumed 4 KiB OS pages when releasing evicted
+        // frames; Raspberry Pi 5 (16 KiB kernel pages) and other arm64 systems
+        // crash mid-COPY with a raw native message. 0.18.0 detects the page size
+        // at runtime, so the actionable fix depends on which side of that
+        // boundary the installed @ladybugdb/core is.
+        if ((0, lbug_config_js_1.isLbugPageSizeFrameError)(err)) {
+            const pageSize = (0, lbug_config_js_1.getOsPageSize)();
+            const ladybug = (0, capabilities_js_1.getRuntimeFingerprint)().ladybugdb;
+            const pageLine = pageSize !== undefined && pageSize !== 4096
+                ? `  Detected OS page size: ${pageSize} bytes (non-4K — e.g. Raspberry Pi 5 16K kernel, Asahi Linux).\n`
+                : '';
+            // The upgrade variant must not assert version facts about an unknown
+            // version — mirror the doctor-side wording rule (#2424 review R2).
+            const upgradeIntro = ladybug === undefined
+                ? `  The installed @ladybugdb/core version is unknown — it may predate the\n` +
+                    `  runtime OS-page-size detection added in 0.18.0.\n`
+                : `  The installed @ladybugdb/core (${ladybug}) assumes 4 KiB pages in its buffer\n` +
+                    `  manager.\n`;
+            const guidance = (0, lbug_config_js_1.isPageSizeAwareLadybug)(ladybug)
+                ? `  The installed @ladybugdb/core (${ladybug}) already detects the OS page size at runtime,\n` +
+                    `  so this configuration was expected to work. Please report it:\n` +
+                    `    https://github.com/abhigyanpatwari/GitNexus/issues/1231\n` +
+                    `  and include: gitnexus --version, node --version, getconf PAGE_SIZE, uname -a,\n` +
+                    `  and the full error message above.\n`
+                : upgradeIntro +
+                    `  Upgrade GitNexus to a release that bundles @ladybugdb/core >= 0.18.0\n` +
+                    `  (gitnexus >= 1.6.9), which detects the OS page size at runtime:\n` +
+                    `    npm install -g cgraph@latest\n` +
+                    `  Last-resort workaround on Raspberry Pi 5: boot the 4 KiB-page kernel\n` +
+                    `  (config.txt: kernel=kernel8.img), at the cost of Pi 5 optimizations.\n`;
+            // Embed the raw native text (indented, no stack) so "the full error
+            // message above" is fulfillable — same idiom as the LbugWipeError
+            // branch. The errno suffix and the 0.18.0 guard's frame/granule numbers
+            // are the discriminating triage content (#2424 review P2).
+            (0, cli_message_js_1.cliError)(`  LadybugDB's buffer manager failed to release frame memory.\n` +
+                `    ${msg.replace(/\n/g, '\n    ')}\n` +
+                pageLine +
+                guidance, { recoveryHint: 'lbug-page-size', pageSize, ladybugVersion: ladybug });
+            process.exitCode = 1;
+            return;
+        }
+        // Bypass the redirected console.error and write the full stack to
+        // the real stderr captured at module load. The redirected
+        // console.error wraps every line with `\\x1b[2K\\r` (ANSI clear-line)
+        // and forces a bar.update() afterwards, which on some Windows
+        // terminals visually erases the failure message — the canonical
+        // shape of the silent-exit symptom in #1169.
+        writeFatalToStderr('Analysis failed', err);
+        // Provide helpful guidance for known failure modes
+        if (msg.includes('Maximum call stack size exceeded') ||
+            msg.includes('call stack') ||
+            msg.includes('Map maximum size') ||
+            msg.includes('Invalid array length') ||
+            msg.includes('Invalid string length') ||
+            msg.includes('allocation failed') ||
+            msg.includes('heap out of memory') ||
+            msg.includes('JavaScript heap')) {
+            (0, cli_message_js_1.cliError)(`  This error typically occurs on very large repositories.\n` +
+                `  Suggestions:\n` +
+                `    1. Add large vendored/generated directories to .cgraphignore\n` +
+                `    2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"\n` +
+                `    3. Increase stack size: NODE_OPTIONS="--stack-size=4096"\n`, { recoveryHint: 'large-repo' });
+        }
+        else if (msg.includes('ERESOLVE') || msg.includes('Could not resolve dependency')) {
+            // Note: the original arborist "Cannot destructure property 'package' of
+            // 'node.target'" crash happens inside npm *before* gitnexus code runs,
+            // so it can't be caught here.  This branch handles dependency-resolution
+            // errors that surface at runtime (e.g. dynamic require failures).
+            (0, cli_message_js_1.cliError)(`  This looks like an npm dependency resolution issue.\n` +
+                `  Suggestions:\n` +
+                `    1. Clear the npm cache:    npm cache clean --force\n` +
+                `    2. Update npm:             npm install -g npm@latest\n` +
+                `    3. Reinstall cgraph:     npm install -g cgraph@latest\n` +
+                `    4. Or try npx directly:    npx cgraph@latest analyze\n`, { recoveryHint: 'npm-resolution' });
+        }
+        else if (msg.includes('MODULE_NOT_FOUND') ||
+            msg.includes('Cannot find module') ||
+            msg.includes('ERR_MODULE_NOT_FOUND')) {
+            (0, cli_message_js_1.cliError)(`  A required module could not be loaded. The installation may be corrupt.\n` +
+                `  Suggestions:\n` +
+                `    1. Reinstall:   npm install -g cgraph@latest\n` +
+                `    2. Clear cache: npm cache clean --force && npx cgraph@latest analyze\n`, { recoveryHint: 'module-not-found' });
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // LadybugDB's native module holds open handles that prevent Node from exiting.
+    // ONNX Runtime also registers native atexit hooks that segfault on some
+    // platforms (#38, #40). Force-exit to ensure clean termination.
+    process.exit(0);
+};