gitnexus 1.6.6-rc.98 → 1.6.6

package/dist/cli/analyze.js

@@ -8,13 +8,15 @@
  * skill generation (--skills), summary output, and process.exit().
  */
 import path from 'path';
+import os from 'os';
 import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
 import { isLbugCheckpointIoError, 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 } from '../storage/git.js';
+import { getGitRoot, hasGitDir, getDefaultBranch } from '../storage/git.js';
+import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
 import { warnMissingOptionalGrammars } from './optional-grammars.js';
@@ -23,6 +25,8 @@ import fs from 'fs/promises';
 import { cliError } from './cli-message.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
+import { isLocalEmbeddingRuntimeBlockerMessage } from '../core/embeddings/runtime-support.js';
+import { warnIfNpm11NpxRisk } from './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
@@ -37,6 +41,22 @@ const writeFatalToStderr = (label, 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. 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++) {
+        realStderrWrite(`\n  Caused by: ${cause.stack ?? cause.message}\n`);
+        cause = cause.cause;
+    }
 };
 let fatalHandlersInstalled = false;
 /**
@@ -60,12 +80,41 @@ const installFatalHandlers = () => {
         process.exit(1);
     });
 };
-const HEAP_MB = 16384;
+/** 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
+ * `process.constrainedMemory()` returns a huge sentinel when UNCONSTRAINED.
+ */
+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));
+}
+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.totalmem(), readConstrainedBytes());
 const TEST_RESPAWN_HEAP_MB = Number(process.env.GITNEXUS_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}`;
@@ -332,7 +381,8 @@ 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;
-/** Re-exec the process with a 16GB heap and larger stack if we're currently below that. */
+/** 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). */
 async function ensureHeap() {
     const nodeOpts = process.env.NODE_OPTIONS || '';
     if (nodeOpts.includes('--max-old-space-size'))
@@ -340,32 +390,32 @@ async function ensureHeap() {
     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, not via the environment.
-    const cliFlags = [HEAP_FLAG];
+    // --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)];
     const childEnv = {
         ...process.env,
-        NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim(),
+        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)) {
-            cliError(`  Analysis likely ran out of memory.\n` +
-                `  Retry with a larger heap if your machine allows it:\n` +
-                `    NODE_OPTIONS="--max-old-space-size=24576" gitnexus analyze [your-args]\n` +
-                `    (Windows: set NODE_OPTIONS=--max-old-space-size=24576 && gitnexus analyze [your-args])\n` +
+            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>" gitnexus analyze [your-args]\n` +
+                `    (Windows: set NODE_OPTIONS=--max-old-space-size=<MB> && gitnexus 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)) {
             cliError(`  Analysis aborted in a native worker or native binding path.\n` +
                 `  Try one of these recovery paths:\n` +
-                `    gitnexus analyze --workers 0\n` +
-                `    npm uninstall -g gitnexus && npm install -g gitnexus@latest\n` +
+                `    npm uninstall -g gitnexus && npm install -g gitnexus@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;
@@ -386,6 +436,7 @@ const ANALYZE_CLI_ENV_KEYS = [
     'GITNEXUS_VERBOSE',
     'GITNEXUS_PROFILE_DEFERRED',
     'GITNEXUS_PROFILE_DEFERRED_SLOW_MS',
+    'GITNEXUS_DEBUG_HEAP',
     'GITNEXUS_MAX_FILE_SIZE',
     'GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS',
     'GITNEXUS_WAL_CHECKPOINT_THRESHOLD',
@@ -433,6 +484,10 @@ export const analyzeCommand = async (inputPath, options) => {
     // 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. `gitnexus mcp`).
+    warnIfNpm11NpxRisk();
     // Snapshot the GITNEXUS_* 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
@@ -448,14 +503,101 @@ export const analyzeCommand = async (inputPath, options) => {
         restoreAnalyzeEnv(envSnap);
     }
 };
-const analyzeCommandImpl = async (inputPath, options) => {
-    if (options?.verbose) {
+const analyzeCommandImpl = async (inputPath, cliOptions) => {
+    console.log('\n  GitNexus Analyzer\n');
+    // ── Resolve the target repo root ──────────────────────────────────
+    // Resolved FIRST because `.gitnexusrc` is read from the repo root (not the
+    // caller's cwd), and config can set defaults that the validation below
+    // consumes. `--skip-git` is a CLI-only flag (never a config key), so the raw
+    // CLI options are authoritative for repo-root resolution.
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else if (cliOptions?.skipGit) {
+        // --skip-git: treat cwd as the index root, do not walk up to a parent git repo.
+        repoPath = path.resolve(process.cwd());
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            console.log('  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+            process.exitCode = 1;
+            return;
+        }
+        repoPath = gitRoot;
+    }
+    const repoHasGit = hasGitDir(repoPath);
+    if (!repoHasGit && !cliOptions?.skipGit) {
+        console.log('  Not a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (!repoHasGit) {
+        console.log('  Warning: no .git directory found — commit-tracking and incremental updates disabled.\n');
+    }
+    // Validate an explicit `--default-branch` up front so its errors are
+    // attributed to the flag (with a CLI-specific recovery hint) rather than to
+    // `.gitnexusrc`, which the user may not even have (#1996 tri-review).
+    if (cliOptions?.defaultBranch !== undefined) {
+        try {
+            validateBranchName(cliOptions.defaultBranch, '--default-branch');
+        }
+        catch (err) {
+            cliError(`  ${err instanceof Error ? err.message : String(err)}\n`, {
+                recoveryHint: 'default-branch-invalid',
+            });
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // ── Load .gitnexusrc 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;
+    let resolvedDefaultBranch;
+    try {
+        const fileConfig = loadAnalyzeConfig(repoPath);
+        options = mergeAnalyzeOptions(cliOptions ?? {}, fileConfig);
+        // Resolve the default branch threaded into generated context:
+        //   CLI --default-branch > .gitnexusrc defaultBranch/branch
+        //     > auto-detected origin/HEAD > "main".
+        // Only shell out to git when no branch was configured AND the generated
+        // context will actually use it, keeping the common path free of an extra
+        // git call. Detection is best-effort and never blocks analyze.
+        const cliBranch = cliOptions?.defaultBranch;
+        const configBranch = fileConfig?.defaultBranch;
+        const willGenerateContext = !options.indexOnly && !options.skipAgentsMd;
+        let detectedBranch = null;
+        if (cliBranch === undefined &&
+            configBranch === undefined &&
+            repoHasGit &&
+            !cliOptions?.skipGit &&
+            willGenerateContext) {
+            try {
+                detectedBranch = getDefaultBranch(repoPath);
+            }
+            catch {
+                detectedBranch = null;
+            }
+        }
+        resolvedDefaultBranch = resolveDefaultBranch({ cliBranch, configBranch, detectedBranch });
+    }
+    catch (err) {
+        const msg = err instanceof GitNexusRcError
+            ? err.message
+            : `Invalid .gitnexusrc: ${err instanceof Error ? err.message : String(err)}`;
+        cliError(`  ${msg}\n`, { recoveryHint: 'gitnexusrc-invalid' });
+        process.exitCode = 1;
+        return;
+    }
+    if (options.verbose) {
         process.env.GITNEXUS_VERBOSE = '1';
     }
-    if (options?.maxFileSize) {
+    if (options.maxFileSize) {
         process.env.GITNEXUS_MAX_FILE_SIZE = options.maxFileSize;
     }
-    if (options?.workerTimeout) {
+    if (options.workerTimeout) {
         const workerTimeoutSeconds = Number(options.workerTimeout);
         if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
             cliError('  --worker-timeout must be at least 1 second.\n');
@@ -464,7 +606,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
         }
         process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(Math.round(workerTimeoutSeconds * 1000));
     }
-    if (options?.walCheckpointThreshold !== undefined) {
+    if (options.walCheckpointThreshold !== undefined) {
         const parsed = parseWalCheckpointThreshold(options.walCheckpointThreshold);
         if (parsed === undefined) {
             cliError('  --wal-checkpoint-threshold must be an integer >= -1.\n');
@@ -480,11 +622,12 @@ const analyzeCommandImpl = async (inputPath, options) => {
     // values back-to-back and observe the value they passed, not whatever the
     // previous call leaked.
     let workerPoolSize;
-    if (options?.workers !== undefined) {
+    if (options.workers !== undefined) {
         const parsedWorkers = Number(options.workers);
-        if (!Number.isInteger(parsedWorkers) || parsedWorkers < 0) {
-            cliError('  --workers must be a non-negative integer. ' +
-                'Pass 0 to disable the worker pool (sequential fallback).\n');
+        if (!Number.isInteger(parsedWorkers) || parsedWorkers < 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;
         }
@@ -495,7 +638,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
     // sibling-validation pattern (exit before bar.start() — otherwise
     // process.exit() leaves the progress bar's hidden cursor uncleared).
     let embeddingsNodeLimit;
-    if (typeof options?.embeddings === 'string') {
+    if (typeof options.embeddings === 'string') {
         const parsed = Number(options.embeddings);
         if (!Number.isInteger(parsed) || parsed < 0) {
             cliError(`  --embeddings expects a non-negative integer (got "${options.embeddings}"). ` +
@@ -505,7 +648,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
         }
         embeddingsNodeLimit = parsed;
     }
-    const embeddingsEnabled = !!options?.embeddings;
+    const embeddingsEnabled = !!options.embeddings;
     const setPositiveEnv = (optionName, envName, value) => {
         if (value === undefined)
             return true;
@@ -518,12 +661,12 @@ const analyzeCommandImpl = async (inputPath, options) => {
         process.env[envName] = String(parsed);
         return true;
     };
-    if (!setPositiveEnv('--embedding-threads', 'GITNEXUS_EMBEDDING_THREADS', options?.embeddingThreads) ||
-        !setPositiveEnv('--embedding-batch-size', 'GITNEXUS_EMBEDDING_BATCH_SIZE', options?.embeddingBatchSize) ||
-        !setPositiveEnv('--embedding-sub-batch-size', 'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', options?.embeddingSubBatchSize)) {
+    if (!setPositiveEnv('--embedding-threads', 'GITNEXUS_EMBEDDING_THREADS', options.embeddingThreads) ||
+        !setPositiveEnv('--embedding-batch-size', 'GITNEXUS_EMBEDDING_BATCH_SIZE', options.embeddingBatchSize) ||
+        !setPositiveEnv('--embedding-sub-batch-size', 'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', options.embeddingSubBatchSize)) {
         return;
     }
-    if (options?.embeddingDevice) {
+    if (options.embeddingDevice) {
         const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
         if (!allowed.has(options.embeddingDevice)) {
             cliError('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
@@ -532,48 +675,21 @@ const analyzeCommandImpl = async (inputPath, options) => {
         }
         process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
     }
-    if (options?.repairFts && options?.force) {
+    if (options.repairFts && options.force) {
         cliError('  Cannot combine `--repair-fts` with `--force`. ' +
             'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
         process.exitCode = 1;
         return;
     }
-    console.log('\n  GitNexus Analyzer\n');
     // `--index-only` is the stronger contract — it suppresses every form of file
     // injection, including community skill writes that `--skills` would normally
     // produce. Surface the override explicitly so users don't wonder why a
     // pipeline re-index ran but no skill files appeared. The pipeline still
-    // re-runs (see `force: options?.force || options?.skills` below); the warning
+    // re-runs (see `force: options.force || options.skills` below); the warning
     // is purely about the dropped post-index write step.
-    if (options?.indexOnly && options?.skills) {
+    if (options.indexOnly && options.skills) {
         console.log('  Note: --index-only overrides --skills; community skill files will not be written.\n');
     }
-    let repoPath;
-    if (inputPath) {
-        repoPath = path.resolve(inputPath);
-    }
-    else if (options?.skipGit) {
-        // --skip-git: treat cwd as the index root, do not walk up to a parent git repo.
-        repoPath = path.resolve(process.cwd());
-    }
-    else {
-        const gitRoot = getGitRoot(process.cwd());
-        if (!gitRoot) {
-            console.log('  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
-            process.exitCode = 1;
-            return;
-        }
-        repoPath = gitRoot;
-    }
-    const repoHasGit = hasGitDir(repoPath);
-    if (!repoHasGit && !options?.skipGit) {
-        console.log('  Not a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
-        process.exitCode = 1;
-        return;
-    }
-    if (!repoHasGit) {
-        console.log('  Warning: no .git directory found \u2014 commit-tracking and incremental updates disabled.\n');
-    }
     // If the target repo contains files an optional grammar would parse but
     // that grammar's native binding is absent, warn before analysis so users
     // learn why those files end up unparsed instead of silently getting a
@@ -692,34 +808,37 @@ const analyzeCommandImpl = async (inputPath, options) => {
     const t0 = Date.now();
     // ── Run shared analysis orchestrator ───────────────────────────────
     try {
-        const skipAll = options?.indexOnly;
-        const skipAgentsMd = skipAll || options?.skipAgentsMd;
-        const skipSkills = skipAll || options?.skipSkills;
+        const skipAll = options.indexOnly;
+        const skipAgentsMd = skipAll || options.skipAgentsMd;
+        const skipSkills = skipAll || options.skipSkills;
         const result = await runFullAnalysis(repoPath, {
             // 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).
-            force: options?.force || options?.skills,
-            repairFts: options?.repairFts,
+            force: options.force || options.skills,
+            repairFts: options.repairFts,
             embeddings: embeddingsEnabled,
             embeddingsNodeLimit,
-            dropEmbeddings: options?.dropEmbeddings,
-            verbose: options?.verbose,
-            skipGit: options?.skipGit,
+            dropEmbeddings: options.dropEmbeddings,
+            verbose: options.verbose,
+            skipGit: options.skipGit,
             skipAgentsMd,
             skipSkills,
+            // Resolved default branch (CLI > .gitnexusrc > auto-detect > "main")
+            // threaded into the generated regression-compare example (#243).
+            defaultBranch: resolvedDefaultBranch,
             // commander.js `.option('--no-stats', …)` registers the flag as
             // `options.stats` (boolean, default true; `false` when the user
-            // passed --no-stats). Reading `options?.noStats` here returns
+            // passed --no-stats). Reading `options.noStats` here returns
             // undefined every time, so the flag was a no-op on the markdown
             // rewrite path before this fix. See #1477.
-            noStats: options?.stats === false,
-            registryName: options?.name,
+            noStats: options.stats === false,
+            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,
+            allowDuplicateName: options.allowDuplicateName,
             // Worker pool size threaded from --workers, replacing the previous
             // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
             // env / auto-formula fallback inside the pipeline.
@@ -736,6 +855,20 @@ const analyzeCommandImpl = async (inputPath, options) => {
             // that half-finalized state, runFullAnalysis returns alreadyUpToDate
             // on the next invocation unless we check the registry here too.
             await assertAnalysisFinalized(repoPath);
+            // The fast path skips context regeneration, but a changed `.gitnexusrc`
+            // defaultBranch / `--default-branch` must still take effect. Surgically
+            // refresh just the `base_ref` line in AGENTS.md/CLAUDE.md in place,
+            // preserving the rest of the block (incl. --skills community rows). No-op
+            // when the value already matches, so a routine up-to-date run is silent
+            // (#1996 tri-review P2).
+            let baseRefRefreshed = [];
+            try {
+                const { refreshBaseRefLine } = await import('./ai-context.js');
+                baseRefRefreshed = (await refreshBaseRefLine(repoPath, resolvedDefaultBranch, { skipAgentsMd })).files;
+            }
+            catch {
+                /* best-effort — never fail the fast path over a context refresh */
+            }
             clearInterval(elapsedTimer);
             process.removeListener('SIGINT', sigintHandler);
             console.log = origLog;
@@ -745,6 +878,9 @@ const analyzeCommandImpl = async (inputPath, options) => {
             console.error = origError;
             bar.stop();
             console.log('  Already up to date\n');
+            if (baseRefRefreshed.length > 0) {
+                console.log(`  Updated base_ref to "${resolvedDefaultBranch}" in ${baseRefRefreshed.join(', ')}\n`);
+            }
             // Safe to return without process.exit(0) — the early-return path in
             // runFullAnalysis never opens LadybugDB, so no native handles prevent exit.
             return;
@@ -803,9 +939,13 @@ const analyzeCommandImpl = async (inputPath, options) => {
                     }, skillResult.skills, {
                         skipAgentsMd,
                         skipSkills,
+                        // Same resolved branch as the main run (#243) so the --skills
+                        // re-generation of AGENTS.md/CLAUDE.md does not revert base_ref
+                        // to "main".
+                        defaultBranch: resolvedDefaultBranch,
                         // Mirror runFullAnalysis `noStats` bridge (#1477) — same expression;
                         // exercised on the `--skills` path by analyze-no-stats-bridge.test.ts.
-                        noStats: options?.stats === false,
+                        noStats: options.stats === false,
                     });
                 }
             }
@@ -898,6 +1038,19 @@ const analyzeCommandImpl = async (inputPath, options) => {
             process.exitCode = 1;
             return;
         }
+        // Local embedding runtime unsupported on this platform (macOS Intel ships no
+        // darwin/x64 ONNX native binding, #1515). The guard threw before importing
+        // transformers.js, so this is a clean, actionable GitNexus message. Checked
+        // before the network-heuristic isHfDownloadFailure branch below (and before
+        // the generic module-not-found "installation may be corrupt" hint) so the
+        // explicit platform message always takes priority.
+        if (isLocalEmbeddingRuntimeBlockerMessage(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-unsupported',
+            });
+            process.exitCode = 1;
+            return;
+        }
         // HF download failure — show clean guidance without the raw stack trace.
         // Checked before writeFatalToStderr so the user sees one focused message
         // rather than a stack-trace dump followed by a second remediation block.

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' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'large-repo' | 'npm-resolution' | 'module-not-found';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/doctor.d.ts

@@ -1,3 +1,21 @@
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
+/**
+ * Embedding-runtime support status for the `doctor` Embeddings section.
+ * Pure and DI-friendly so it can be unit-tested without running the whole
+ * command. Delegates the platform decision to
+ * {@link getLocalEmbeddingRuntimeBlocker} so the wording stays in one place.
+ *
+ * - HTTP mode: always supported (never touches the native runtime).
+ * - Local mode on an unsupported platform (macOS Intel, #1515): reports the
+ *   blocker as `detail` so the caller can surface the full guidance.
+ */
+export declare function localEmbeddingDoctorStatus(opts: {
+    httpMode: boolean;
+    platform?: NodeJS.Platform;
+    arch?: NodeJS.Architecture;
+}): {
+    status: string;
+    detail: string | null;
+};
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -1,6 +1,7 @@
 import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
+import { getLocalEmbeddingRuntimeBlocker } from '../core/embeddings/runtime-support.js';
 import { checkLbugNative } from '../core/lbug/native-check.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
@@ -42,6 +43,28 @@ export function padDisplayEnd(value, columns) {
     return value + ' '.repeat(Math.max(0, columns - displayWidth(value)));
 }
 const label = (key, width) => padDisplayEnd(t(key), width);
+/**
+ * Embedding-runtime support status for the `doctor` Embeddings section.
+ * Pure and DI-friendly so it can be unit-tested without running the whole
+ * command. Delegates the platform decision to
+ * {@link getLocalEmbeddingRuntimeBlocker} so the wording stays in one place.
+ *
+ * - HTTP mode: always supported (never touches the native runtime).
+ * - Local mode on an unsupported platform (macOS Intel, #1515): reports the
+ *   blocker as `detail` so the caller can surface the full guidance.
+ */
+export function localEmbeddingDoctorStatus(opts) {
+    if (opts.httpMode) {
+        return { status: '✓ http endpoint configured', detail: null };
+    }
+    const platform = opts.platform ?? process.platform;
+    const arch = opts.arch ?? process.arch;
+    const blocker = getLocalEmbeddingRuntimeBlocker({ platform, arch });
+    if (blocker) {
+        return { status: `✗ local embeddings unavailable on ${platform}/${arch}`, detail: blocker };
+    }
+    return { status: '✓ local embeddings supported', detail: null };
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -87,4 +110,13 @@ export const doctorCommand = async () => {
     console.log(`  ${label('doctor.labels.threads', 12)}${embeddingConfig.threads}`);
     console.log(`  ${label('doctor.labels.batch', 12)}${t('doctor.nodes', { count: embeddingConfig.batchSize })}`);
     console.log(`  ${label('doctor.labels.subBatch', 12)}${t('doctor.chunks', { count: embeddingConfig.subBatchSize })}`);
+    // Surface local-runtime support so macOS Intel users see up front that local
+    // embeddings can't load here (the bundled ONNX Runtime ships no darwin/x64
+    // native binding, #1515) — rather than discovering it only when
+    // `analyze --embeddings` fails. Literal label like the 'native' line above.
+    const support = localEmbeddingDoctorStatus({ httpMode: isHttpMode() });
+    console.log(`  ${padDisplayEnd('Support:', 12)}${support.status}`);
+    if (support.detail) {
+        process.stderr.write(`\n${support.detail.replace(/^/gm, '  ')}\n\n`);
+    }
 };

package/dist/cli/i18n/en.d.ts

@@ -143,7 +143,7 @@ export declare const en: {
     readonly 'help.option.analyze.maxFileSize': "Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).";
     readonly 'help.option.analyze.workerTimeout': "Worker sub-batch idle timeout before retry/fallback. Default: 30.";
     readonly 'help.option.analyze.walCheckpointThreshold': "LadybugDB WAL auto-checkpoint threshold in bytes during analyze (integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).";
-    readonly 'help.option.analyze.workers': "Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).";
+    readonly 'help.option.analyze.workers': "Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.";
     readonly 'help.option.analyze.embeddingThreads': "Limit local ONNX embedding CPU threads";
     readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
     readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";
@@ -156,7 +156,7 @@ export declare const en: {
     readonly 'help.option.clean.all': "Clean all indexed repos";
     readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
     readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
-    readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, or codex (default: openai)";
+    readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
     readonly 'help.option.wiki.model': "LLM model or Azure deployment name (default: minimax/minimax-m2.5)";
     readonly 'help.option.wiki.baseUrl': "LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1";
     readonly 'help.option.wiki.apiKey': "LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)";

package/dist/cli/i18n/en.js

@@ -143,7 +143,7 @@ export const en = {
     'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).',
     'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.',
     'help.option.analyze.walCheckpointThreshold': 'LadybugDB WAL auto-checkpoint threshold in bytes during analyze (integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).',
-    'help.option.analyze.workers': 'Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).',
+    'help.option.analyze.workers': 'Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.',
     'help.option.analyze.embeddingThreads': 'Limit local ONNX embedding CPU threads',
     'help.option.analyze.embeddingBatchSize': 'Number of nodes per embedding batch',
     'help.option.analyze.embeddingSubBatchSize': 'Number of chunks per embedding model call',
@@ -156,7 +156,7 @@ export const en = {
     'help.option.clean.all': 'Clean all indexed repos',
     'help.option.clean.lbugSidecars': 'Clean quarantined LadybugDB missing-shadow WAL sidecars',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
-    'help.option.wiki.provider': 'LLM provider: openai, openrouter, azure, custom, cursor, claude, or codex (default: openai)',
+    'help.option.wiki.provider': 'LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)',
     'help.option.wiki.model': 'LLM model or Azure deployment name (default: minimax/minimax-m2.5)',
     'help.option.wiki.baseUrl': 'LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1',
     'help.option.wiki.apiKey': 'LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)',

package/dist/cli/i18n/resources.d.ts

@@ -144,7 +144,7 @@ export declare const cliResources: {
         readonly 'help.option.analyze.maxFileSize': "Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).";
         readonly 'help.option.analyze.workerTimeout': "Worker sub-batch idle timeout before retry/fallback. Default: 30.";
         readonly 'help.option.analyze.walCheckpointThreshold': "LadybugDB WAL auto-checkpoint threshold in bytes during analyze (integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).";
-        readonly 'help.option.analyze.workers': "Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).";
+        readonly 'help.option.analyze.workers': "Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.";
         readonly 'help.option.analyze.embeddingThreads': "Limit local ONNX embedding CPU threads";
         readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
         readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";
@@ -157,7 +157,7 @@ export declare const cliResources: {
         readonly 'help.option.clean.all': "Clean all indexed repos";
         readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
         readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
-        readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, or codex (default: openai)";
+        readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
         readonly 'help.option.wiki.model': "LLM model or Azure deployment name (default: minimax/minimax-m2.5)";
         readonly 'help.option.wiki.baseUrl': "LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1";
         readonly 'help.option.wiki.apiKey': "LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)";