gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/cli/analyze.js

@@ -14,9 +14,12 @@ import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { isLbugReady, LbugWipeError } from '../core/lbug/lbug-adapter.js';
 import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
-import { getOsPageSize, isLbugCheckpointIoError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
+import { findUndeclaredRelationPairError } from '../core/lbug/rel-pair-routing.js';
+import { causeChain } from '../lib/utils.js';
+import { getOsPageSize, isLbugCheckpointIoError, isLbugCheckpointBusyError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
-import { getGitRoot, hasGitDir, getDefaultBranch } from '../storage/git.js';
+import { getGitRoot, hasGitDir, getDefaultBranch, selfCommitContextFiles, snapshotSelfCommitSafety, } from '../storage/git.js';
+import { IndexLockTimeoutError } from '../storage/index-lock.js';
 import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import { getRuntimeFingerprint } from '../core/platform/capabilities.js';
@@ -24,7 +27,8 @@ import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-si
 import { warnMissingOptionalGrammars, getOptionalGrammarExtensions } from './optional-grammars.js';
 import { glob } from 'glob';
 import fs from 'fs/promises';
-import { cliError } from './cli-message.js';
+import { cliError, cliWarn } from './cli-message.js';
+import { heapCapMbFor, memoryAutopilotDisabled } from '../core/ingestion/utils/effective-ram.js';
 import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
@@ -52,15 +56,13 @@ const writeFatalToStderr = (label, err) => {
     // #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. Depth-bounded so a cyclic `cause` can't loop
-    // (the phase runner wraps one level; the bound leaves headroom for future
-    // nesting); uses realStderrWrite so the redirected console.error's ANSI
-    // clear-line wrapping can't erase it (#1169).
-    const MAX_CAUSE_DEPTH = 5;
-    let cause = isErr ? err.cause : undefined;
-    for (let depth = 0; depth < MAX_CAUSE_DEPTH && cause instanceof Error; depth++) {
+    // 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 causeChain(isErr ? err.cause : undefined)) {
         realStderrWrite(`\n  Caused by: ${cause.stack ?? cause.message}\n`);
-        cause = cause.cause;
     }
 };
 let fatalHandlersInstalled = false;
@@ -85,23 +87,20 @@ const installFatalHandlers = () => {
         process.exit(1);
     });
 };
-/** Historical floor for the re-exec heap cap — the auto-sizer never goes below
- *  this, so small boxes / CI never regress. */
-const DEFAULT_HEAP_MB = 16384;
 /**
- * RAM-aware re-exec heap cap (MB): `0.75 × effective RAM`, clamped to
- * `>= DEFAULT_HEAP_MB`. Kept BELOW physical RAM on purpose — a cap `>=` RAM makes
- * V8 collect lazily and inflate the heap into swap-thrash (observed analyzing the
- * Linux kernel at a 30GB cap on a 31GB box). `constrainedBytes` is the cgroup
- * limit or `null`; it is honored only as a real, smaller-than-physical cap, because
+ * 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.)
  */
 export function computeHeapCapMb(totalBytes, constrainedBytes) {
     const effectiveBytes = constrainedBytes !== null && constrainedBytes > 0 && constrainedBytes < totalBytes
         ? constrainedBytes
         : totalBytes;
-    const effectiveMb = Math.floor(effectiveBytes / (1024 * 1024));
-    return Math.max(DEFAULT_HEAP_MB, Math.floor(0.75 * effectiveMb));
+    return heapCapMbFor(effectiveBytes);
 }
 function readConstrainedBytes() {
     if (typeof process.constrainedMemory !== 'function')
@@ -386,21 +385,70 @@ const forceHeapOOMForTestIfEnabled = () => {
 // the `DEFAULT_WAL_CHECKPOINT_THRESHOLD` constant in
 // `gitnexus/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.
+ */
+export 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. A user-supplied NODE_OPTIONS heap wins (no re-exec). */
+ *  if we're currently below that.
+ *
+ *  Heap-source precedence (#2649):
+ *  - an explicit per-invocation `--max-old-space-size` (execArgv) always wins;
+ *  - `GITNEXUS_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() {
-    const nodeOpts = process.env.NODE_OPTIONS || '';
-    if (nodeOpts.includes('--max-old-space-size'))
+    // 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 (memoryAutopilotDisabled())
         return false;
-    const v8Heap = v8.getHeapStatistics().heap_size_limit;
-    if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
+    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;
+        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 GITNEXUS_MEMORY=off to keep the NODE_OPTIONS value).\n`);
+    }
+    else {
+        const v8Heap = v8.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);
-    const childArgs = [...cliFlags, ...process.argv.slice(1)];
+    // 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(),
@@ -485,7 +533,7 @@ const restoreAnalyzeEnv = (snap) => {
  * without booting the full analyze pipeline (#742 review).
  */
 export const shouldGenerateCommunitySkillFiles = (options, pipelineResult) => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
-export const analyzeCommand = async (inputPath, options) => {
+export const analyzeCommand = async (inputPath, options, runnerIdentityAtBootstrap) => {
     if (await ensureHeap())
         return;
     forceHeapOOMForTestIfEnabled();
@@ -506,7 +554,7 @@ export const analyzeCommand = async (inputPath, options) => {
     // pre-call values.
     const envSnap = snapshotAnalyzeEnv();
     try {
-        await analyzeCommandImpl(inputPath, options);
+        await analyzeCommandImpl(inputPath, options, runnerIdentityAtBootstrap);
     }
     finally {
         restoreAnalyzeEnv(envSnap);
@@ -523,7 +571,9 @@ export const analyzeCommand = async (inputPath, options) => {
         process.exit(typeof process.exitCode === 'number' ? process.exitCode : 1);
     }
 };
-const analyzeCommandImpl = async (inputPath, cliOptions) => {
+/** Commander entrypoint used only by the capture-before-import lazy bootstrap. */
+export const analyzeCommandWithRunnerIdentity = async (runnerIdentityAtBootstrap, inputPath, options) => analyzeCommand(inputPath, options, runnerIdentityAtBootstrap);
+const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstrap) => {
     console.log('\n  GitNexus Analyzer\n');
     // ── Resolve the target repo root ──────────────────────────────────
     // Resolved FIRST because `.gitnexusrc` is read from the repo root (not the
@@ -988,7 +1038,7 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         const skipAll = options.indexOnly;
         const skipAgentsMd = skipAll || options.skipAgentsMd;
         const skipSkills = skipAll || options.skipSkills;
-        const result = await runFullAnalysis(repoPath, {
+        const runOptions = {
             // Pipeline re-index — OR'd with --skills because skill generation
             // needs a fresh pipelineResult. Has no bearing on the registry
             // collision guard (see allowDuplicateName below).
@@ -1035,12 +1085,25 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             // 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]
+            : [];
+        // #2639 review round 2: snapshot which of AGENTS.md/CLAUDE.md are safe to
+        // auto-commit BEFORE runFullAnalysis (and the --skills regeneration
+        // further down) writes to them, so selfCommitContextFiles can tell a
+        // pre-existing unstaged user edit apart from this run's stats refresh
+        // and refuse to sweep the former into the latter's commit.
+        const selfCommitSafety = options.selfCommit === true
+            ? snapshotSelfCommitSafety(repoPath, ['AGENTS.md', 'CLAUDE.md'])
+            : undefined;
+        const result = await 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
@@ -1080,6 +1143,11 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             if (baseRefRefreshed.length > 0) {
                 console.log(`  Updated base_ref to "${resolvedDefaultBranch}" in ${baseRefRefreshed.join(', ')}\n`);
             }
+            // #2639: opt-in self-commit of any AGENTS.md/CLAUDE.md churn from this
+            // fast path (e.g. a base_ref refresh above). Best-effort — never throws.
+            if (options.selfCommit === true && selfCommitSafety) {
+                selfCommitContextFiles(repoPath, ['AGENTS.md', 'CLAUDE.md'], selfCommitSafety);
+            }
             // Safe to return without process.exit(0) — the early-return path in
             // runFullAnalysis never opens LadybugDB, so no native handles prevent exit.
             return;
@@ -1153,6 +1221,13 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
                 /* best-effort */
             }
         }
+        // #2639: opt-in self-commit of any AGENTS.md/CLAUDE.md churn written by
+        // this run (the primary generateAIContextFiles call inside
+        // runFullAnalysis, and/or the --skills regeneration above). Best-effort
+        // — never throws, so a missing git identity etc. can't fail `analyze`.
+        if (options.selfCommit === true && selfCommitSafety) {
+            selfCommitContextFiles(repoPath, ['AGENTS.md', 'CLAUDE.md'], selfCommitSafety);
+        }
         const totalTime = ((Date.now() - t0) / 1000).toFixed(1);
         clearInterval(elapsedTimer);
         process.removeListener('SIGINT', sigintHandler);
@@ -1165,6 +1240,25 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         bar.stop();
         // ── Summary ────────────────────────────────────────────────────
         const s = result.stats;
+        // A collapsed graph write is NOT a successful index. The other incomplete
+        // reasons (`incremental-in-progress`, `embedding-checkpoint-pending`)
+        // describe a run that did what it said and left work for next time; this
+        // one means most of your edges are gone, so every query answers a confident
+        // empty and the exit code is the only thing automation reads. Printing
+        // "indexed successfully" and exiting 0 here would be the same class of
+        // false certainty the check itself was written to remove.
+        if (result.graphWriteCollapsed) {
+            const { expected, persisted } = result.graphWriteCollapsed;
+            console.log(`\n  Repository indexed INCOMPLETELY (${totalTime}s)\n`);
+            console.log(`  Graph write collapsed: the pipeline produced ${expected.toLocaleString()} relationships\n` +
+                `  but only ${persisted.toLocaleString()} are readable from the index. Queries will answer\n` +
+                `  with missing edges rather than an error.\n\n` +
+                `  The index is recorded INCOMPLETE (graph-write-collapsed). Re-run\n` +
+                `  \`gitnexus analyze --force\`; if it recurs, check disk space and run \`gitnexus doctor\`.`);
+            console.log(`  ${repoPath}`);
+            process.exitCode = 1;
+            return;
+        }
         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}`);
@@ -1172,9 +1266,24 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         // progress-bar log() that fired mid-run has already scrolled away, so the
         // degraded-search state must also appear in the final summary (#1161).
         if (result.ftsSkipped) {
-            console.log(`\n  Warning: full-text/BM25 search is disabled — the LadybugDB FTS extension was unavailable.\n` +
-                `  Install it once with network access (GITNEXUS_LBUG_EXTENSION_INSTALL=auto) then rerun, or\n` +
-                `  run \`gitnexus analyze --repair-fts\` when connected. Run \`gitnexus doctor\` for details.`);
+            // #2658 review L2: a build/verify failure is NOT an extension-unavailable
+            // problem — sending the user to install the extension is the wrong remedy.
+            if (result.ftsSkipReason === 'build-failed') {
+                console.log(`\n  Warning: full-text/BM25 search is disabled — the search index build failed this run.\n` +
+                    `  The FTS extension is available; rerun \`gitnexus analyze --repair-fts\`. If it persists,\n` +
+                    `  check the disk for space or corruption. Run \`gitnexus doctor\` for details.`);
+            }
+            else {
+                console.log(
+                // NOT "then rerun" (#2841 §5.C): this run stamped `lastCommit`, so a
+                // plain rerun on an unchanged tree takes the up-to-date fast path and
+                // returns before Phase 3 could rebuild anything — the advice would be
+                // ineffective exactly when the user follows it. `--repair-fts` is the
+                // verb that rebuilds the search indexes without re-parsing the repo.
+                `\n  Warning: full-text/BM25 search is disabled — the LadybugDB FTS extension was unavailable.\n` +
+                    `  Install it once with network access (GITNEXUS_LBUG_EXTENSION_INSTALL=auto), then run\n` +
+                    `  \`gitnexus analyze --repair-fts\` to build the search indexes. Run \`gitnexus doctor\` for details.`);
+            }
         }
         try {
             await fs.access(getGlobalRegistryPath());
@@ -1205,6 +1314,18 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // Another analyze held the index lock past the configured wait ceiling
+        // (#2658, GITNEXUS_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 IndexLockTimeoutError) {
+            cliError(`  Another gitnexus 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` +
+                `  GITNEXUS_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.
@@ -1218,6 +1339,35 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             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 = 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, `.gitnexusignore` workaround) precisely
+            // because `gitnexus 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.
+            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).
@@ -1229,7 +1379,15 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             return;
         }
         if (isLbugCheckpointIoError(err)) {
+            // #2599: when the checkpoint IO error also looks busy/locked, another
+            // handle holds the store open — name that actionable cause alongside the
+            // threshold hint (the original error is preserved so the hint still fires).
+            const heldOpen = isLbugCheckpointBusyError(err)
+                ? `  Another process may hold the store open (a running \`gitnexus mcp\` server, or a\n` +
+                    `  stale reader) — close other GitNexus processes on this repo, then retry.\n`
+                : '';
             cliError(`  LadybugDB failed while rotating/removing WAL checkpoint files.\n` +
+                heldOpen +
                 `  This can happen when auto-checkpoint runs at the default threshold (~16MB).\n` +
                 `  Retry with a larger checkpoint threshold to reduce checkpoint frequency:\n` +
                 `    gitnexus analyze --wal-checkpoint-threshold ${RECOMMENDED_WAL_CHECKPOINT_THRESHOLD}\n` +

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'lbug-page-size' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'lbug-page-size' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid' | 'index-lock-timeout' | 'undeclared-relation-pair';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/detect-changes-format.js

@@ -1,13 +1,30 @@
 import { t } from './i18n/index.js';
+import { formatSymbolLine } from './format-symbol.js';
 export function formatDetectChangesResult(result) {
     const payload = (result ?? {});
     if (payload.error)
         return t('common.error', { message: String(payload.error) });
     const summary = payload.summary ?? {};
+    // A swallowed query failure sets `partial` and leaves the counts at zero
+    // (#2283). Printing only "No changes detected." turns a degraded run into a
+    // clean bill of health for the pre-commit gate, so say so either way.
+    // `truncated` is its sibling flag: the backend caps the changed_symbols
+    // LISTING (never the counts), so a short list is not proof of a short diff.
+    // Both lead the output — a caveat printed after the summary is read too late.
+    const notes = [];
+    if (payload.partial)
+        notes.push(t('tool.detectChanges.partial'));
+    // The plain truncation note reassures that the counts are whole. That is only
+    // true when the run did NOT also degrade — `changed_count` sums the batches
+    // that succeeded — so the two flags together get a different sentence.
+    if (payload.truncated)
+        notes.push(t(payload.partial ? 'tool.detectChanges.truncatedDegraded' : 'tool.detectChanges.truncated'));
     if ((summary.changed_count ?? 0) === 0) {
-        return t('tool.detectChanges.noChanges');
+        return [...notes, t('tool.detectChanges.noChanges')].join('\n');
     }
     const lines = [];
+    if (notes.length > 0)
+        lines.push(...notes, '');
     lines.push(t('tool.detectChanges.changesSummary', {
         files: summary.changed_files ?? 0,
         symbols: summary.changed_count ?? 0,
@@ -22,7 +39,7 @@ export function formatDetectChangesResult(result) {
         lines.push(t('tool.detectChanges.changedSymbols'));
         const shown = changed.slice(0, 15);
         for (const symbol of shown) {
-            lines.push(`  ${symbol.type ?? 'Symbol'} ${symbol.name ?? '?'} → ${symbol.filePath ?? '?'}`);
+            lines.push(formatSymbolLine(symbol.type, symbol.name, symbol.filePath));
         }
         // Overflow is measured against the TRUE total (summary.changed_count), not
         // the array length — the array may already be `--limit`-sliced, so using its

package/dist/cli/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
+import { type NativeCheckResult } from '../core/lbug/native-check.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -36,4 +37,26 @@ export declare function localEmbeddingDoctorStatus(opts: {
  * detect the OS page size at runtime).
  */
 export declare function pageSizeDoctorLines(pageSize: number | undefined, ladybugVersion: string | undefined): string[];
+/**
+ * The hintless buffer-pool doctor line (#2631) — the pool the next Database
+ * open in THIS process would get. Same plain-params testable-helper shape as
+ * pageSizeDoctorLines above. `pool` is getEffectiveBufferPoolSize(): `0` is
+ * the pass-through sentinel for LadybugDB's native 80%-of-RAM default, never
+ * printed as "0 MiB". `envRaw` (the raw GITNEXUS_LBUG_BUFFER_POOL_SIZE value)
+ * marks operator-supplied absolute values as "(env override)" — no scaling
+ * suffix: the hintless default is deliberately unscaled (#2557), and an env
+ * value is absolute, so a "×N" note would misdescribe both.
+ */
+export declare function poolSizeDoctorLine(pool: number, envRaw: string | undefined): string;
+/**
+ * The `native` status line. Literal label like the page-size and pool-size lines
+ * above (no i18n key).
+ *
+ * A failed check is not automatically a MISSING binary, and saying so is the
+ * same misdiagnosis #2672 fixed one layer down: on a host whose glibc is too
+ * old, `lbugjs.node` is present and merely unloadable, so "missing" sent users
+ * to reinstall a file that was already there — while the detail written to
+ * stderr right below said the opposite. Render what the check actually found.
+ */
+export declare function nativeStatusLine(check: NativeCheckResult): string;
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -4,8 +4,8 @@ import { isHttpMode } from '../core/embeddings/http-client.js';
 import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
 import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
-import { checkLbugNative, probeFtsExtensionLoad } from '../core/lbug/native-check.js';
-import { getOsPageSize, isPageSizeAwareLadybug } from '../core/lbug/lbug-config.js';
+import { checkLbugNative, probeFtsExtensionLoad, probeVectorExtensionLoad, } from '../core/lbug/native-check.js';
+import { getEffectiveBufferPoolSize, getOsPageSize, isPageSizeAwareLadybug, } from '../core/lbug/lbug-config.js';
 import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
@@ -115,6 +115,51 @@ export function pageSizeDoctorLines(pageSize, ladybugVersion) {
     }
     return lines;
 }
+/**
+ * The hintless buffer-pool doctor line (#2631) — the pool the next Database
+ * open in THIS process would get. Same plain-params testable-helper shape as
+ * pageSizeDoctorLines above. `pool` is getEffectiveBufferPoolSize(): `0` is
+ * the pass-through sentinel for LadybugDB's native 80%-of-RAM default, never
+ * printed as "0 MiB". `envRaw` (the raw GITNEXUS_LBUG_BUFFER_POOL_SIZE value)
+ * marks operator-supplied absolute values as "(env override)" — no scaling
+ * suffix: the hintless default is deliberately unscaled (#2557), and an env
+ * value is absolute, so a "×N" note would misdescribe both.
+ */
+export function poolSizeDoctorLine(pool, envRaw) {
+    const value = pool === 0 ? 'native 80% of RAM' : `${Math.round(pool / (1024 * 1024))} MiB`;
+    const envNote = envRaw !== undefined && envRaw.trim().length > 0 ? ' (env override)' : '';
+    return `  ${padDisplayEnd('pool size', 10)}${value}${envNote}`;
+}
+/**
+ * The `native` status line. Literal label like the page-size and pool-size lines
+ * above (no i18n key).
+ *
+ * A failed check is not automatically a MISSING binary, and saying so is the
+ * same misdiagnosis #2672 fixed one layer down: on a host whose glibc is too
+ * old, `lbugjs.node` is present and merely unloadable, so "missing" sent users
+ * to reinstall a file that was already there — while the detail written to
+ * stderr right below said the opposite. Render what the check actually found.
+ */
+export function nativeStatusLine(check) {
+    return `  ${padDisplayEnd('native', 10)}${nativeStatusText(check)}`;
+}
+function nativeStatusText(check) {
+    if (check.ok)
+        return '✓ lbugjs.node loaded';
+    switch (check.kind) {
+        case 'package_missing':
+            return '✗ @ladybugdb/core not installed';
+        case 'load_failed':
+            return '✗ lbugjs.node present but failed to load';
+        case 'binary_unwritable':
+            // The prebuilt exists; only the copy into node_modules was refused. Saying
+            // "missing" here would contradict the detail printed underneath (#2672).
+            return '✗ lbugjs.node not installed (node_modules not writable)';
+        default:
+            // 'binary_missing', and any future kind: the conservative claim.
+            return '✗ lbugjs.node missing';
+    }
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -132,12 +177,12 @@ export const doctorCommand = async () => {
     for (const line of pageSizeDoctorLines(getOsPageSize(), fingerprint.ladybugdb)) {
         console.log(line);
     }
+    // Hintless buffer pool for the next DB open (#2631). Literal label like
+    // the page size line above (no i18n key).
+    console.log(poolSizeDoctorLine(getEffectiveBufferPoolSize(), process.env.GITNEXUS_LBUG_BUFFER_POOL_SIZE));
     const nativeCheck = checkLbugNative();
-    if (nativeCheck.ok) {
-        console.log(`  ${padDisplayEnd('native', 10)}✓ lbugjs.node loaded`);
-    }
-    else {
-        console.log(`  ${padDisplayEnd('native', 10)}✗ lbugjs.node missing`);
+    console.log(nativeStatusLine(nativeCheck));
+    if (!nativeCheck.ok) {
         process.stderr.write(`\n${nativeCheck.message?.replace(/^/gm, '  ')}\n\n`);
     }
     console.log(`  ${label('doctor.labels.onnx', 10)}${fingerprint.onnxruntime ?? 'unknown'}`);
@@ -162,8 +207,26 @@ export const doctorCommand = async () => {
             console.log(`  ${padDisplayEnd('', 18)}${remedy}`);
         }
     }
-    console.log(`  ${label('doctor.labels.vectorIndex', 18)}${capabilities.vector}`);
-    console.log(`  ${label('doctor.labels.semanticMode', 18)}${capabilities.semanticMode}`);
+    // Live LOAD probe for VECTOR too (#2623). The static capability is just
+    // `platform !== 'win32'`, so it printed "available" on the very machines
+    // where analyze was failing to load the extension — the same contradiction
+    // #2374 fixed for FTS above, and exactly what #2623's reporter saw while
+    // every incremental analyze died on an unloaded VECTOR extension.
+    const vectorProbe = nativeCheck.ok
+        ? await probeVectorExtensionLoad()
+        : { loaded: false, reason: 'LadybugDB native module (lbugjs.node) failed to load' };
+    console.log(`  ${label('doctor.labels.vectorIndex', 18)}${vectorProbe.loaded ? 'available' : 'unavailable'}`);
+    if (!vectorProbe.loaded && vectorProbe.reason) {
+        console.log(`  ${padDisplayEnd('', 18)}${vectorProbe.reason}`);
+        const { kind, remedy } = diagnoseExtensionLoad(vectorProbe.reason, 'VECTOR');
+        if (kind !== 'unknown') {
+            console.log(`  ${padDisplayEnd('', 18)}${remedy}`);
+        }
+    }
+    // Semantic mode follows the probe, not the platform: without a loadable
+    // VECTOR extension the index can be neither built nor queried, so search is
+    // really on exact scan no matter what the platform would allow.
+    console.log(`  ${label('doctor.labels.semanticMode', 18)}${vectorProbe.loaded ? capabilities.semanticMode : 'exact-scan'}`);
     // Surface the optional-extension install policy so offline users can see
     // whether analyze/query will reach the network (extension.ladybugdb.com).
     // Literal label (like the 'native' line) to avoid adding i18n keys.

package/dist/cli/editor-targets.js

@@ -47,6 +47,12 @@ export function getEditorTargets(home = os.homedir()) {
             id: 'opencode',
             label: 'OpenCode',
             file: path.join(home, '.config', 'opencode', 'opencode.json'),
+            // OpenCode merges config.json -> opencode.json -> opencode.jsonc; setup
+            // writes an existing readable config to avoid creating a shadow file.
+            legacyFiles: [
+                path.join(home, '.config', 'opencode', 'opencode.jsonc'),
+                path.join(home, '.config', 'opencode', 'config.json'),
+            ],
             // OpenCode nests servers under `mcp`, not `mcpServers`.
             keyPath: ['mcp', 'gitnexus'],
         },

package/dist/cli/eval-server.d.ts

@@ -16,7 +16,8 @@
  * Usage:
  *   gitnexus eval-server                        # default port 4848, binds 127.0.0.1
  *   gitnexus eval-server --port 4848            # explicit port
- *   gitnexus eval-server --host 0.0.0.0         # reachable from other VMs / containers
+ *   GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host 0.0.0.0
+ *   GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host devbox.local
  *   gitnexus eval-server --idle-timeout 300     # auto-shutdown after 300s idle
  *
  * READY signal format: GITNEXUS_EVAL_SERVER_READY:<host>:<port>
@@ -42,6 +43,27 @@ export interface EvalServerOptions {
  * address (127.0.0.1 or ::1) at bind time rather than forcing IPv4.
  */
 export declare function validateHost(raw: string): string | null;
+type EvalServerHostLookup = (hostname: string) => Promise<string>;
+/** Resolve a DNS bind name once so validation and listen() use the same concrete address. */
+export declare function resolveEvalServerBindHost(raw: string, resolveHostname?: EvalServerHostLookup): Promise<string | null>;
+/** Resolve the bearer token from the shell, then .env.local, then .env. */
+export declare function resolveEvalServerAuthToken(env: NodeJS.ProcessEnv, cwd?: string): string | undefined;
+/** True only for literal loopback addresses; DNS names are resolved before this check. */
+export declare function isEvalServerLoopbackHost(host: string): boolean;
+/**
+ * Resolve the bearer token for a concrete bind host. An unreadable `.env` /
+ * `.env.local` only matters when the binding actually requires a token, so
+ * loopback binds degrade to a warning instead of refusing to start; any
+ * non-loopback bind keeps the fail-closed error.
+ */
+export declare function resolveEvalServerAuthTokenForHost(host: string, env: NodeJS.ProcessEnv, cwd?: string): {
+    token?: string;
+    warning?: string;
+};
+/** Refuse exposure of the eval-server query surface without authentication. */
+export declare function assertSecureEvalServerBinding(host: string, authToken: string | undefined): void;
+/** Validate the exact Bearer header while keeping token comparison constant-time. */
+export declare function isEvalServerBearerAuthorized(authorization: string | string[] | undefined, authToken: string | undefined): boolean;
 export declare function formatQueryResult(result: any): string;
 export declare function formatContextResult(result: any): string;
 export declare function formatImpactResult(result: any): string;