gitnexus 1.6.13-rc.39 → 1.6.13-rc.40

package/README.md

@@ -212,25 +212,25 @@ Note that the bundled Graphology path is no longer the slow option it once was:
 
 Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
 
-| Tool             | What It Does                                                           |
-| ---------------- | ---------------------------------------------------------------------- |
-| `list_repos`     | Discover all indexed repositories (paginated — `limit`/`offset`)       |
-| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF); optional `chain_depth` expands each result's call chain |
+| Tool             | What It Does                                                                                                                                      |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_repos`     | Discover all indexed repositories (paginated — `limit`/`offset`)                                                                                  |
+| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF); optional `chain_depth` expands each result's call chain                                    |
 | `context`        | 360-degree symbol view — categorized refs, process participation, HTTP routes, `is_entry_point` flag; optional `chain_depth` call-chain expansion |
-| `impact`         | Blast radius analysis with depth grouping and confidence               |
-| `trace`          | Shortest directed path between two symbols (call + class-member edges) |
-| `detect_changes` | Git-diff impact — maps changed lines to affected processes             |
-| `check`          | Read-only structural checks against the indexed graph                  |
-| `rename`         | Multi-file coordinated rename with graph + text search                 |
-| `cypher`         | Raw Cypher graph queries                                               |
-| `route_map`      | API route map — which components fetch which endpoints, and handlers   |
-| `tool_map`       | MCP/RPC tool definitions — where they're defined and handled           |
-| `shape_check`    | Validate API response shapes against consumers' property accesses      |
-| `api_impact`     | Pre-change impact report for an API route handler                      |
-| `explain`        | Explain persisted taint findings (source→sink flows, `--pdg` indexes)  |
-| `pdg_query`      | Query control/data dependence at statement level (`--pdg` indexes)     |
-| `group_list`     | List configured repository groups                                      |
-| `group_sync`     | Rebuild a group's Contract Registry and cross-repo links               |
+| `impact`         | Blast radius analysis with depth grouping and confidence                                                                                          |
+| `trace`          | Shortest directed path between two symbols (call + class-member edges)                                                                            |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes                                                                                        |
+| `check`          | Read-only structural checks against the indexed graph                                                                                             |
+| `rename`         | Multi-file coordinated rename with graph + text search                                                                                            |
+| `cypher`         | Raw Cypher graph queries                                                                                                                          |
+| `route_map`      | API route map — which components fetch which endpoints, and handlers                                                                              |
+| `tool_map`       | MCP/RPC tool definitions — where they're defined and handled                                                                                      |
+| `shape_check`    | Validate API response shapes against consumers' property accesses                                                                                 |
+| `api_impact`     | Pre-change impact report for an API route handler                                                                                                 |
+| `explain`        | Explain persisted taint findings (source→sink flows, `--pdg` indexes)                                                                             |
+| `pdg_query`      | Query control/data dependence at statement level (`--pdg` indexes)                                                                                |
+| `group_list`     | List configured repository groups                                                                                                                 |
+| `group_sync`     | Rebuild a group's Contract Registry and cross-repo links                                                                                          |
 
 > Read-only tools can omit `repo` when one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing into an unindexed nested Git checkout. Otherwise—and for mutating tools with multiple indexed repos and no MCP default—specify it explicitly: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`; omitting it queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
 
@@ -279,6 +279,7 @@ gitnexus analyze --spring-actuator ./actuator  # Enrich with local Spring Boot A
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
 gitnexus analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
 gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
+gitnexus analyze --memory-budget 3000  # Main-thread V8 heap in MB (>= 200); overrides the auto-sizer and any --max-old-space-size pin
 gitnexus analyze --wal-checkpoint-threshold 67108864  # 64 MiB. Control LadybugDB WAL auto-checkpoint threshold (default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB)
 gitnexus auto-sync [init|start|restart|stop|status|reset]  # Scheduled remote clone/pull + analyze from GITNEXUS_HOME/watch_config.yml
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
@@ -754,6 +755,11 @@ If analyze says the repository doesn't fit, do what the message says:
 - **The machine is the ceiling**: shrink the scope (exclude generated or
   vendored directories, below) or use a machine with more RAM.
 
+To set the main-thread heap yourself on a memory-constrained host, pass
+`--memory-budget <mb>`: analyze re-runs with exactly that V8 heap, overriding
+the auto-sizer and any `--max-old-space-size` pin. It sizes the main thread
+only; parse workers keep their own caps.
+
 Escape hatches (`GITNEXUS_MEMORY=off` to decline the autopilot,
 `GITNEXUS_WORKER_HEAP_MB` to size workers yourself) are listed in the
 environment-variable table below —
@@ -839,6 +845,7 @@ Four env vars expose the pool's resilience layers (respawn budget, cumulative-ti
 | `GITNEXUS_WORKER_READY_TIMEOUT_MS`              | `5000`                             | Startup budget for a parse worker to load its grammar bindings and report `{type:'ready'}`. Slots that miss it are treated as startup crashes. Raise it on a slow or heavily loaded host where a full pool cold-starting concurrently needs more than 5s. |
 | `GITNEXUS_MEMORY`                               | `off`                              | unset (autopilot on)                                                                                                                                                                                                                                      | `off` declines GitNexus's memory autopilot: analyze will neither re-run itself with a RAM-aware heap cap nor abort the parse before V8 enters its ineffective-mark-compact death spiral. Use it when you want to drive memory manually; to simply pin a heap size, pass Node's own `--max-old-space-size`, which is already honoured as your decision. |
 | `GITNEXUS_WORKER_HEAP_MB`                       | `clamp(512, RAM/2/poolSize, 4096)` | Per-worker V8 old-generation heap cap (#2649). Bounds pool RSS on large repos; a worker exceeding it dies with a real heap error handled by quarantine/respawn.                                                                                           |
+| `GITNEXUS_HEAP_LIMIT_SOURCE`                    | unset                              | Set by analyze itself (`budget` or `auto`) to record where the heap limit came from, so out-of-memory advice points at `--memory-budget` rather than a `--max-old-space-size` pin.                                                                        | Never — internal; set `--memory-budget` instead.                                                                                                                                                                                                                                                                                                       |
 | `GITNEXUS_SERVER_ANALYZE_HEAP_MB`               | `min(8192, auto cap)`              | Heap for the web/MCP server's forked analyze worker (#2649). Defaults to the historical 8192 MB bounded by the machine/container's RAM-aware auto cap; set an absolute MB value to override.                                                              |
 | `GITNEXUS_CPP_CAPTURE_BUDGET_MS`                | `20000`                            | Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning (#2432). `0` expires immediately.                                                                                                         |
 

package/dist/cli/analyze-options.d.ts

@@ -117,6 +117,14 @@ export interface AnalyzeOptions {
     workerTimeout?: string;
     /** Control LadybugDB WAL auto-checkpoint threshold during analyze. */
     walCheckpointThreshold?: string;
+    /**
+     * `--memory-budget <mb>` (#3137): the main-thread V8 heap limit in MB.
+     * `ensureHeap` applies it through the existing heap respawn, replacing the
+     * RAM-aware auto cap and any `--max-old-space-size` pin, so the #2649
+     * guards read it as the live limit. Parse workers keep their own heap caps.
+     * Integer, minimum 200; CLI-only (not a `.gitnexusrc` key).
+     */
+    memoryBudget?: string;
     /** Parse worker pool size (>=1); 0 is rejected (no sequential mode). */
     workers?: string;
     /** Process-detection process cap. Positive integer string; `0` is invalid. */

package/dist/cli/analyze-watch.js

@@ -11,6 +11,7 @@ import { GITNEXUS_DIR } from '../storage/repo-meta.js';
 import { loadAnalyzeConfigStrict, mergeAnalyzeOptions, validateBranchName, } from './analyze-config.js';
 import { ensureHeap } from './analyze.js';
 import { cliError, cliInfo, cliWarn } from './cli-message.js';
+import { parseIntegerOption } from './int-option.js';
 import { formatInvalidProcessDetectionOverride, parseProcessDetectionBudgetStrings, } from '../core/ingestion/process-detection-budget.js';
 import { WATCH_FULL_REFRESH_PATH, WatchRefreshQueue, } from './watch-queue.js';
 const DEFAULT_DEBOUNCE_MS = 300;
@@ -54,9 +55,7 @@ function setEnvironment(name, value) {
 function positiveInteger(value, flag, maximum) {
     if (value === undefined)
         return undefined;
-    const parsed = Number(value);
-    if (!Number.isInteger(parsed) || parsed < 1)
-        throw new Error(`${flag} must be a positive integer`);
+    const parsed = parseIntegerOption(value, flag, { minimum: 1 });
     if (maximum !== undefined && parsed > maximum) {
         throw new Error(`${flag} must not exceed ${maximum}`);
     }
@@ -329,8 +328,9 @@ export async function startWatchFileLoop(repoPath, debounceMs, refresh, onError,
     };
 }
 export async function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, cliOptions = {}) {
-    if (await ensureHeap({ cleanForwardedTermination: true }))
+    if (await ensureHeap({ cleanForwardedTermination: true, memoryBudget: cliOptions.memoryBudget })) {
         return;
+    }
     const requestedRepoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
     if (requestedRepoPath === null || !hasGitDir(requestedRepoPath)) {
         cliError('  gitnexus analyze --watch requires a Git repository.');

package/dist/cli/analyze.d.ts

@@ -25,21 +25,69 @@ export declare function computeHeapCapMb(totalBytes: number, constrainedBytes: n
  * later-flag-wins semantics when NODE_OPTIONS repeats a flag.
  */
 export declare function parseMaxOldSpaceMb(nodeOptions: string): number | null;
+export declare function forwardedSignalExitCode(signal: NodeJS.Signals, cleanTermination: boolean): number;
+/** Old-space and semi-space flags (MB) that give a child a V8 heap of exactly the budget. */
+export interface BudgetHeapSizing {
+    oldSpaceMb: number;
+    semiSpaceMb: number;
+}
+/**
+ * Size the respawn flags so the child's `heap_size_limit` equals the budget
+ * (#3137). V8's limit is old space plus three semi-spaces, and V8 rounds the
+ * semi-space up to a power of two (measured on Node 22.18: semi 10 → 16), so
+ * the semi-space is budget/25 rounded up the same way, capped at the usual
+ * 128MB, and the old space takes the rest: 2000 → 1616 + 3 × 128, 200 → 176 + 3 × 8.
+ */
+export declare function budgetHeapSizing(budgetMb: number): BudgetHeapSizing;
+export interface BudgetHeapInput {
+    budgetMb: number;
+    execArgv: readonly string[];
+    nodeOptions: string;
+    /** The RAM-aware auto cap the budget replaces. */
+    autoCapMb: number;
+    /** `GITNEXUS_MEMORY=off`: names Node's default limit as the one replaced. */
+    autopilotDisabled: boolean;
+    /** Inherited `GITNEXUS_HEAP_LIMIT_SOURCE`; `budget` marks a budget-respawned child. */
+    inheritedSource: string | undefined;
+}
+export interface BudgetHeapDecision {
+    respawn: boolean;
+    sizing: BudgetHeapSizing;
+    /** At most one warning line for the operator; absent in a budget-respawned child. */
+    warning?: string;
+}
+/**
+ * The `--memory-budget` heap decision (#3137), kept pure so every branch is
+ * testable without a process. The effective requested old space is the last
+ * `--max-old-space-size` in execArgv, else in NODE_OPTIONS (every spelling
+ * `parseMaxOldSpaceMb` accepts). Only the budget-respawned child keeps
+ * running; anything else respawns once at the budget. The budget's own flags
+ * follow the user's in the child, so the child always resolves to "at the
+ * budget".
+ */
+export declare function resolveBudgetHeap(input: BudgetHeapInput): BudgetHeapDecision;
 /** Re-exec the process with the RAM-aware auto heap cap + larger semi-space/stack
- *  if we're currently below that.
+ *  if we're currently below that, or at the `--memory-budget` heap (#3137).
  *
- *  Heap-source precedence (#2649):
- *  - an explicit per-invocation `--max-old-space-size` (execArgv) always wins;
+ *  Heap-source precedence (#2649, #3137):
+ *  - an explicit `--memory-budget` wins over everything, including
+ *    `GITNEXUS_MEMORY=off` and any `--max-old-space-size` pin;
+ *  - an explicit per-invocation `--max-old-space-size` (execArgv) wins next;
  *  - `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. */
-export declare function forwardedSignalExitCode(signal: NodeJS.Signals, cleanTermination: boolean): number;
+ *    whatever heap the environment happened to specify.
+ *
+ *  Paths managed by the auto-sizer or `--memory-budget` record the source in
+ *  `GITNEXUS_HEAP_LIMIT_SOURCE` (this process when kept, the child env when
+ *  respawned) so the parse phase's remedy text advises by source. Explicit
+ *  heap pins and `GITNEXUS_MEMORY=off` intentionally leave it unset. */
 export declare function ensureHeap(options?: {
     cleanForwardedTermination?: boolean;
+    memoryBudget?: string;
 }): Promise<boolean>;
 /**
  * CLI `analyze` flag shape. Defined in `./analyze-options.js` so

package/dist/cli/analyze.js

@@ -30,7 +30,8 @@ import { warnMissingOptionalGrammars, getOptionalGrammarExtensions } from './opt
 import { glob } from 'glob';
 import fs from 'fs/promises';
 import { cliError, cliWarn } from './cli-message.js';
-import { heapCapMbFor, memoryAutopilotDisabled } from '../core/ingestion/utils/effective-ram.js';
+import { IntegerOptionError, parseIntegerOption, parseMemoryBudgetMb } from './int-option.js';
+import { HEAP_LIMIT_SOURCE_ENV, 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';
@@ -405,27 +406,22 @@ const RECOMMENDED_WAL_CHECKPOINT_THRESHOLD = 64 * 1024 * 1024;
  * 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)];
+    return parseV8SizeFlagMb(nodeOptions, 'max-old-space-size');
+}
+/**
+ * Last value (MB) of a V8 `--<name>` size flag in a flag string. V8 accepts
+ * `-` and `_` interchangeably in flag names, and Node accepts a
+ * space-separated value — honor every spelling instead of silently
+ * overriding it (#2649 review).
+ */
+function parseV8SizeFlagMb(flags, name) {
+    const stem = name.split('-').join('[-_]');
+    const matches = [...flags.matchAll(new RegExp(`--${stem}(?:=|\\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;
- *  - `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. */
 export function forwardedSignalExitCode(signal, cleanTermination) {
     if (cleanTermination)
         return 0;
@@ -435,7 +431,118 @@ export function forwardedSignalExitCode(signal, cleanTermination) {
         return 143;
     return 1;
 }
+/**
+ * Size the respawn flags so the child's `heap_size_limit` equals the budget
+ * (#3137). V8's limit is old space plus three semi-spaces, and V8 rounds the
+ * semi-space up to a power of two (measured on Node 22.18: semi 10 → 16), so
+ * the semi-space is budget/25 rounded up the same way, capped at the usual
+ * 128MB, and the old space takes the rest: 2000 → 1616 + 3 × 128, 200 → 176 + 3 × 8.
+ */
+export function budgetHeapSizing(budgetMb) {
+    const scaled = Math.max(1, Math.floor(budgetMb / 25));
+    const semiSpaceMb = Math.min(SEMI_SPACE_MB, 2 ** Math.ceil(Math.log2(scaled)));
+    return { oldSpaceMb: budgetMb - 3 * semiSpaceMb, semiSpaceMb };
+}
+/**
+ * The `--memory-budget` heap decision (#3137), kept pure so every branch is
+ * testable without a process. The effective requested old space is the last
+ * `--max-old-space-size` in execArgv, else in NODE_OPTIONS (every spelling
+ * `parseMaxOldSpaceMb` accepts). Only the budget-respawned child keeps
+ * running; anything else respawns once at the budget. The budget's own flags
+ * follow the user's in the child, so the child always resolves to "at the
+ * budget".
+ */
+export function resolveBudgetHeap(input) {
+    const { budgetMb, autoCapMb } = input;
+    const sizing = budgetHeapSizing(budgetMb);
+    const execFlags = input.execArgv.join(' ');
+    const pinnedMb = parseMaxOldSpaceMb(execFlags) ?? parseMaxOldSpaceMb(input.nodeOptions);
+    const semiSpaceMb = parseV8SizeFlagMb(execFlags, 'max-semi-space-size') ??
+        parseV8SizeFlagMb(input.nodeOptions, 'max-semi-space-size');
+    // Only a budget-respawned child carries both the budget's old space and its
+    // semi-space, so only it is exactly at the budget. A pin that merely equals
+    // the budget leaves V8's young generation on top (a 2000MB pin is a 2048MB
+    // heap), so that process respawns once like any other. The respawning
+    // parent already logged; the child stays quiet. The env marker alone is not
+    // proof — it is inherited — so both budget flags must be present too.
+    if (input.inheritedSource === 'budget' &&
+        pinnedMb === sizing.oldSpaceMb &&
+        semiSpaceMb === sizing.semiSpaceMb) {
+        return { respawn: false, sizing };
+    }
+    const swapWarning = budgetMb > autoCapMb
+        ? `  --memory-budget ${budgetMb}MB is above the ${autoCapMb}MB this machine's RAM supports — analyze may swap-thrash.\n`
+        : '';
+    const replaced = pinnedMb !== null
+        ? `the ${pinnedMb}MB --max-old-space-size heap limit`
+        : input.autopilotDisabled
+            ? `Node's default heap limit`
+            : `the auto-sized ${autoCapMb}MB heap cap`;
+    return {
+        respawn: true,
+        sizing,
+        warning: `  --memory-budget replaces ${replaced}: re-running analyze with a ${budgetMb}MB heap.\n` +
+            swapWarning,
+    };
+}
+/** Re-exec the process with the RAM-aware auto heap cap + larger semi-space/stack
+ *  if we're currently below that, or at the `--memory-budget` heap (#3137).
+ *
+ *  Heap-source precedence (#2649, #3137):
+ *  - an explicit `--memory-budget` wins over everything, including
+ *    `GITNEXUS_MEMORY=off` and any `--max-old-space-size` pin;
+ *  - an explicit per-invocation `--max-old-space-size` (execArgv) wins next;
+ *  - `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.
+ *
+ *  Paths managed by the auto-sizer or `--memory-budget` record the source in
+ *  `GITNEXUS_HEAP_LIMIT_SOURCE` (this process when kept, the child env when
+ *  respawned) so the parse phase's remedy text advises by source. Explicit
+ *  heap pins and `GITNEXUS_MEMORY=off` intentionally leave it unset. */
 export async function ensureHeap(options = {}) {
+    const nodeOpts = process.env.NODE_OPTIONS || '';
+    // The budget is checked BEFORE the GITNEXUS_MEMORY=off return: an explicit
+    // flag is a deliberate per-run choice, which the opt-out does not cover.
+    if (options.memoryBudget !== undefined) {
+        let budgetMb;
+        try {
+            budgetMb = parseMemoryBudgetMb(options.memoryBudget);
+        }
+        catch (error) {
+            // The CLI's preAction hook rejects bad values first; this covers
+            // programmatic callers.
+            if (!(error instanceof IntegerOptionError))
+                throw error;
+            cliError(`  ${error.message}\n`);
+            process.exitCode = 1;
+            return true;
+        }
+        const decision = resolveBudgetHeap({
+            budgetMb,
+            execArgv: process.execArgv,
+            nodeOptions: nodeOpts,
+            autoCapMb: RESPAWN_HEAP_MB,
+            autopilotDisabled: memoryAutopilotDisabled(),
+            inheritedSource: process.env[HEAP_LIMIT_SOURCE_ENV],
+        });
+        if (decision.warning)
+            cliWarn(decision.warning);
+        if (!decision.respawn) {
+            process.env[HEAP_LIMIT_SOURCE_ENV] = 'budget';
+            return false;
+        }
+        const { oldSpaceMb, semiSpaceMb } = decision.sizing;
+        return respawnWithHeap(`--max-old-space-size=${oldSpaceMb}`, `--max-semi-space-size=${semiSpaceMb}`, 'budget', `  Analysis likely ran out of memory (heap limit set to ${budgetMb}MB by --memory-budget).\n` +
+            `  This repository's working set exceeds the budget. Raise it, or omit --memory-budget\n` +
+            `  to use the auto-sized cap (a budget above physical RAM causes swap-thrash — use with care):\n` +
+            `    gitnexus analyze --memory-budget <MB> [your-args]\n` +
+            `  If this persists, it may be a native crash unrelated to heap size.\n`, nodeOpts, options);
+    }
     // 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
@@ -443,8 +550,7 @@ export async function ensureHeap(options = {}) {
     // a quiet, single-process run.
     if (memoryAutopilotDisabled())
         return false;
-    const nodeOpts = process.env.NODE_OPTIONS || '';
-    if (process.execArgv.some((a) => a.startsWith('--max-old-space-size')))
+    if (parseMaxOldSpaceMb(process.execArgv.join(' ')) !== null)
         return false;
     const ambientHeapMb = parseMaxOldSpaceMb(nodeOpts);
     if (ambientHeapMb !== null) {
@@ -455,12 +561,23 @@ export async function ensureHeap(options = {}) {
     }
     else {
         const v8Heap = v8.getHeapStatistics().heap_size_limit;
-        if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
+        if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9) {
+            process.env[HEAP_LIMIT_SOURCE_ENV] = 'auto';
             return false;
+        }
     }
+    return respawnWithHeap(HEAP_FLAG, SEMI_FLAG, 'auto', `  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`, nodeOpts, options);
+}
+/** Run the analyze child with the given heap flags and map its exit onto this process. */
+async function respawnWithHeap(heapFlag, semiFlag, source, oomGuidance, nodeOpts, options) {
     // --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];
+    const cliFlags = [heapFlag, semiFlag];
     if (!nodeOpts.includes('--stack-size'))
         cliFlags.push(STACK_FLAG);
     // Preserve the parent's node flags (execArgv) — dropping them breaks any
@@ -474,7 +591,8 @@ export async function ensureHeap(options = {}) {
     const childArgs = [...preservedExecArgv, ...cliFlags, ...process.argv.slice(1)];
     const childEnv = {
         ...process.env,
-        NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG} ${SEMI_FLAG}`.trim(),
+        NODE_OPTIONS: `${nodeOpts} ${heapFlag} ${semiFlag}`.trim(),
+        [HEAP_LIMIT_SOURCE_ENV]: source,
     };
     if (shouldBridgeRespawnProgressTty())
         childEnv[RESPAWN_PROGRESS_ENV] = '1';
@@ -485,12 +603,7 @@ export async function ensureHeap(options = {}) {
     }
     if (childExit.status !== 0 || childExit.signal) {
         if (childProcessLikelyOom(childExit)) {
-            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' });
+            cliError(oomGuidance, { recoveryHint: 'heap-oom-respawn' });
         }
         else if (childProcessLikelyNativeAbort(childExit)) {
             cliError(`  Analysis aborted in a native worker or native binding path.\n` +
@@ -513,6 +626,7 @@ export async function ensureHeap(options = {}) {
  * for it in the first place.
  */
 const ANALYZE_CLI_ENV_KEYS = [
+    HEAP_LIMIT_SOURCE_ENV,
     'GITNEXUS_VERBOSE',
     'GITNEXUS_PROFILE_DEFERRED',
     'GITNEXUS_PROFILE_DEFERRED_SLOW_MS',
@@ -563,7 +677,10 @@ const restoreAnalyzeEnv = (snap) => {
  */
 export const shouldGenerateCommunitySkillFiles = (options, pipelineResult) => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
 export const analyzeCommand = async (inputPath, options, runnerIdentityAtBootstrap) => {
-    if (await ensureHeap())
+    // Snapshot before ensureHeap: it records GITNEXUS_HEAP_LIMIT_SOURCE on a
+    // kept process, which must not leak into a later programmatic call.
+    const envSnap = snapshotAnalyzeEnv();
+    if (await ensureHeap({ memoryBudget: options?.memoryBudget }))
         return;
     forceHeapOOMForTestIfEnabled();
     // Install fatal handlers immediately after re-exec resolution so any
@@ -581,7 +698,6 @@ export const analyzeCommand = async (inputPath, options, runnerIdentityAtBootstr
     // 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);
     }
@@ -744,15 +860,18 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
     // previous call leaked.
     let workerPoolSize;
     if (options.workers !== undefined) {
-        const parsedWorkers = Number(options.workers);
-        if (!Number.isInteger(parsedWorkers) || parsedWorkers < 1) {
+        try {
+            workerPoolSize = parseIntegerOption(options.workers, '--workers', { minimum: 1 });
+        }
+        catch (error) {
+            if (!(error instanceof IntegerOptionError))
+                throw error;
             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;
     }
     const processDetectionFromFlags = parseProcessDetectionBudgetStrings({
         maxProcesses: options.maxProcesses,
@@ -768,26 +887,34 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
     // process.exit() leaves the progress bar's hidden cursor uncleared).
     let embeddingsNodeLimit;
     if (typeof options.embeddings === 'string') {
-        const parsed = Number(options.embeddings);
-        if (!Number.isInteger(parsed) || parsed < 0) {
+        try {
+            embeddingsNodeLimit = parseIntegerOption(options.embeddings, '--embeddings', {
+                minimum: 0,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof IntegerOptionError))
+                throw error;
             cliError(`  --embeddings expects a non-negative integer (got "${options.embeddings}"). ` +
                 `Pass 0 to disable the safety cap, or omit the value to keep the default.\n`);
             process.exitCode = 1;
             return;
         }
-        embeddingsNodeLimit = parsed;
     }
     const embeddingsEnabled = !!options.embeddings;
     const setPositiveEnv = (optionName, envName, value) => {
         if (value === undefined)
             return true;
-        const parsed = Number(value);
-        if (!Number.isInteger(parsed) || parsed <= 0) {
-            cliError(`  ${optionName} must be a positive integer.\n`);
+        try {
+            process.env[envName] = String(parseIntegerOption(value, optionName, { minimum: 1 }));
+        }
+        catch (error) {
+            if (!(error instanceof IntegerOptionError))
+                throw error;
+            cliError(`  ${error.message}.\n`);
             process.exitCode = 1;
             return false;
         }
-        process.env[envName] = String(parsed);
         return true;
     };
     if (!setPositiveEnv('--embedding-threads', 'GITNEXUS_EMBEDDING_THREADS', options.embeddingThreads) ||
@@ -955,7 +1082,7 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
     // 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 (`skills` is passed to runFullAnalysis below); the warning
     // is purely about the dropped post-index write step.
     if (options.indexOnly && options.skills) {
         console.log('  Note: --index-only overrides --skills; community skill files will not be written.\n');
@@ -1093,10 +1220,12 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
         const skipAgentsMd = skipAll || options.skipAgentsMd;
         const skipSkills = skipAll || options.skipSkills;
         const runOptions = {
-            // Pipeline re-index — OR'd with --skills because skill generation needs
-            // a fresh pipelineResult, and with --no-parse-cache because bypassing
-            // parser output is meaningful only when the pipeline runs.
-            force: options.force || options.skills || options.parseCache === false,
+            // The user's own --force only. --skills (skill generation needs a fresh
+            // pipelineResult) and --no-parse-cache (bypassing parser output means
+            // anything only when the pipeline runs) each force the rebuild inside
+            // runFullAnalysis under their own named reason (#3137).
+            force: options.force,
+            skills: options.skills,
             useParseCache: options.parseCache !== false,
             repairFts: options.repairFts,
             skipFts: options.skipFts,

package/dist/cli/help-i18n.js

@@ -69,6 +69,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'analyze|--max-file-size <kb>': 'help.option.analyze.maxFileSize',
     'analyze|--worker-timeout <seconds>': 'help.option.analyze.workerTimeout',
     'analyze|--wal-checkpoint-threshold <bytes>': 'help.option.analyze.walCheckpointThreshold',
+    'analyze|--memory-budget <mb>': 'help.option.analyze.memoryBudget',
     'analyze|--workers <n>': 'help.option.analyze.workers',
     'analyze|--max-processes <n>': 'help.option.analyze.maxProcesses',
     'analyze|--max-process-branching <n>': 'help.option.analyze.maxProcessBranching',

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

@@ -229,6 +229,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.memoryBudget': 'Main-thread V8 heap size in MB for analyze (integer >= 200). Re-runs analyze with exactly this heap, overriding the RAM/cgroup auto-sizer and any --max-old-space-size pin; parse workers keep their own heap caps.';
     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.maxProcesses': 'Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Default: dynamic.';
     readonly 'help.option.analyze.maxProcessBranching': 'Process-detection per-node branching cap (positive integer). Default: 4.';

package/dist/cli/i18n/en.js

@@ -231,6 +231,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.memoryBudget': 'Main-thread V8 heap size in MB for analyze (integer >= 200). Re-runs analyze with exactly this heap, overriding the RAM/cgroup auto-sizer and any --max-old-space-size pin; parse workers keep their own heap caps.',
     'help.option.analyze.workers': 'Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.',
     'help.option.analyze.maxProcesses': 'Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Default: dynamic.',
     'help.option.analyze.maxProcessBranching': 'Process-detection per-node branching cap (positive integer). Default: 4.',

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

@@ -230,6 +230,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.memoryBudget': 'Main-thread V8 heap size in MB for analyze (integer >= 200). Re-runs analyze with exactly this heap, overriding the RAM/cgroup auto-sizer and any --max-old-space-size pin; parse workers keep their own heap caps.';
         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.maxProcesses': 'Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Default: dynamic.';
         readonly 'help.option.analyze.maxProcessBranching': 'Process-detection per-node branching cap (positive integer). Default: 4.';
@@ -556,6 +557,7 @@ export declare const cliResources: {
         'help.option.analyze.maxFileSize': string;
         'help.option.analyze.workerTimeout': string;
         'help.option.analyze.walCheckpointThreshold': string;
+        'help.option.analyze.memoryBudget': string;
         'help.option.analyze.workers': string;
         'help.option.analyze.maxProcesses': string;
         'help.option.analyze.maxProcessBranching': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -229,6 +229,7 @@ export declare const zhCN: {
     'help.option.analyze.maxFileSize': string;
     'help.option.analyze.workerTimeout': string;
     'help.option.analyze.walCheckpointThreshold': string;
+    'help.option.analyze.memoryBudget': string;
     'help.option.analyze.workers': string;
     'help.option.analyze.maxProcesses': string;
     'help.option.analyze.maxProcessBranching': string;

package/dist/cli/i18n/zh-CN.js

@@ -229,6 +229,7 @@ export const zhCN = {
     'help.option.analyze.maxFileSize': '跳过大于该值的文件（KB）。默认：512。硬上限：32768（tree-sitter 限制）。',
     'help.option.analyze.workerTimeout': 'Worker 子批次空闲超时，超时后重试/回退。默认：30。',
     'help.option.analyze.walCheckpointThreshold': 'analyze 期间 LadybugDB WAL 自动 checkpoint 阈值（字节，整数 >= -1；默认：67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。',
+    'help.option.analyze.memoryBudget': 'analyze 主线程 V8 堆大小（MB，整数 >= 200）。以该堆大小重新运行 analyze，覆盖按 RAM/cgroup 自动计算的上限及任何 --max-old-space-size 设置；解析 worker 各自保留独立的堆上限。',
     'help.option.analyze.workers': '解析 worker 池大小（>=1）。默认：cores-1，最多 16，按仓库规模自适应。',
     'help.option.analyze.maxProcesses': '流程检测的流程数量上限（正整数）。覆盖动态的 max(20, round(symbols/10)) 公式。默认：动态。',
     'help.option.analyze.maxProcessBranching': '流程检测的单节点分支上限（正整数）。默认：4。',