gitnexus 1.6.13-rc.15 → 1.6.13-rc.17

package/README.md

@@ -245,6 +245,8 @@ gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexu
 gitnexus analyze --skip-skills   # Skip installing standard .claude/skills/gitnexus-* skill files
 gitnexus analyze --skip-git      # Index folders that are not Git repositories
 gitnexus analyze --workers <n>   # Parse worker pool size (>=1; default: cores-1, capped at 16)
+gitnexus analyze --max-processes <n>  # Process-detection process cap (replaces dynamic max(20, round(symbols/10)))
+gitnexus analyze --max-entry-point-candidates <n>  # Ranked entry-point pool (default 200; raise when the warning names it)
 gitnexus analyze --spring-actuator ./actuator  # Enrich with local Spring Boot Actuator JSON snapshots
 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)
@@ -298,7 +300,8 @@ installation. Run a one-shot `gitnexus analyze` when those generated files need
 updating. Stop watch mode with Ctrl+C.
 
 Watch mode accepts `--debounce`, `--workers`, `--worker-timeout`,
-`--max-file-size`, `--branch`, `--pdg`, `--name`, `--allow-duplicate-name`, and
+`--max-file-size`, `--max-processes`, `--max-process-branching`,
+`--max-process-trace-depth`, `--max-entry-point-candidates`, `--branch`, `--pdg`, `--name`, `--allow-duplicate-name`, and
 `--verbose`. Explicit one-shot options such as `--force`, `--repair-fts`,
 embedding flags, `--skills`, `--default-branch`, `--skip-agents-md`,
 `--skip-skills`, `--no-stats`, `--self-commit`, `--index-only`, and `--skip-git`
@@ -764,6 +767,22 @@ npx gitnexus analyze
 
 Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling; invalid values fall back to the 512 KB default with a one-time warning. When an override is active, `analyze` prints the effective threshold in its startup banner (e.g. `GITNEXUS_MAX_FILE_SIZE: effective threshold 2048KB (default 512KB)`).
 
+### Process detection reports missing flows
+
+On a large repository, `analyze` may warn that `[processes] … whole flows are MISSING`. That means ranked entry points or completed flows were sampled away by the analyze-time detection budget — not that the code path is absent, and not the query-time `IMPACT_MAX_CHUNKS` cap.
+
+Defaults stay in place when nothing is set: dynamic `maxProcesses = max(20, round(non-File symbols / 10))`, branching `4`, trace depth `10`, entry-point candidate pool `200`. Raise a knob only when the warning names it:
+
+```bash
+# Usual first move when entryPointCandidatesDropped is the loud counter
+npx gitnexus analyze --max-entry-point-candidates 400
+
+# When ranked entry points were never traced, or flows were dropped at maxProcesses
+npx gitnexus analyze --max-processes 80
+```
+
+Equivalent `.gitnexusrc` keys: `maxProcesses`, `maxProcessBranching`, `maxProcessTraceDepth`, `maxEntryPointCandidates`. Equivalent env vars: `GITNEXUS_MAX_PROCESSES`, `GITNEXUS_MAX_PROCESS_BRANCHING`, `GITNEXUS_MAX_PROCESS_TRACE_DEPTH`, `GITNEXUS_MAX_ENTRY_POINT_CANDIDATES`. Precedence is CLI > `.gitnexusrc` > env > default. `0` is invalid, not unlimited. Changing these knobs re-runs process detection on the next `analyze` without `--force`. Raising them increases CPU and memory; this is not a heap-OOM fix.
+
 ### Analyze reports a worker timeout
 
 Worker parse timeouts are recoverable. GitNexus retries stalled worker jobs with backoff, splits large jobs to isolate slow files, and quarantines a file that repeatedly crashes its worker (respawning the slot so the pool keeps going). If a large repository needs more time per worker job, use either:

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

@@ -27,6 +27,8 @@
  * documented precedence). Conflicting *aliases at the same level* (e.g. both
  * `defaultBranch` and `branch`) are rejected.
  */
+import { sanitizeDetectedBranch } from '../core/git-ref.js';
+export { sanitizeDetectedBranch };
 import type { AnalyzeOptions } from './analyze-options.js';
 export declare const GITNEXUS_RC_FILENAME = ".gitnexusrc";
 /** Final fallback when no branch is configured or detectable. */
@@ -45,12 +47,6 @@ export declare class GitNexusRcError extends Error {
  * `core/git-ref.ts`; this wrapper keeps the CLI / `.gitnexusrc` error type.
  */
 export declare function validateBranchName(value: string, source: string): string;
-/**
- * Best-effort validation for an auto-detected branch (from git). Never throws —
- * returns `undefined` for anything unusable so the resolver falls back to the
- * next precedence tier.
- */
-export declare function sanitizeDetectedBranch(value: string | null | undefined): string | undefined;
 /**
  * Locate, read, parse, validate, and normalize `.gitnexusrc` at `repoRoot`.
  *

package/dist/cli/analyze-config.js

@@ -30,7 +30,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readRepoControlFile } from '../config/repo-control-file.js';
-import { InvalidBranchError, validateBranchName as validateBranchNameCore, } from '../core/git-ref.js';
+import { InvalidBranchError, sanitizeDetectedBranch, validateBranchName as validateBranchNameCore, } from '../core/git-ref.js';
+export { sanitizeDetectedBranch };
 export const GITNEXUS_RC_FILENAME = '.gitnexusrc';
 /** Final fallback when no branch is configured or detectable. */
 export const DEFAULT_BRANCH_FALLBACK = 'main';
@@ -75,6 +76,10 @@ const KEY_SPECS = {
     workerTimeout: { target: 'workerTimeout', kind: 'numeric-string' },
     walCheckpointThreshold: { target: 'walCheckpointThreshold', kind: 'numeric-string' },
     workers: { target: 'workers', kind: 'numeric-string' },
+    maxProcesses: { target: 'maxProcesses', kind: 'numeric-string' },
+    maxProcessBranching: { target: 'maxProcessBranching', kind: 'numeric-string' },
+    maxProcessTraceDepth: { target: 'maxProcessTraceDepth', kind: 'numeric-string' },
+    maxEntryPointCandidates: { target: 'maxEntryPointCandidates', kind: 'numeric-string' },
     embeddingThreads: { target: 'embeddingThreads', kind: 'numeric-string' },
     embeddingBatchSize: { target: 'embeddingBatchSize', kind: 'numeric-string' },
     embeddingSubBatchSize: { target: 'embeddingSubBatchSize', kind: 'numeric-string' },
@@ -139,21 +144,6 @@ export function validateBranchName(value, source) {
         throw err;
     }
 }
-/**
- * Best-effort validation for an auto-detected branch (from git). Never throws —
- * returns `undefined` for anything unusable so the resolver falls back to the
- * next precedence tier.
- */
-export function sanitizeDetectedBranch(value) {
-    if (!value)
-        return undefined;
-    try {
-        return validateBranchName(value, 'detected branch');
-    }
-    catch {
-        return undefined;
-    }
-}
 const normalizeValue = (kind, value, key) => {
     const source = `${GITNEXUS_RC_FILENAME} "${key}"`;
     switch (kind) {

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

@@ -115,6 +115,14 @@ export interface AnalyzeOptions {
     walCheckpointThreshold?: string;
     /** Parse worker pool size (>=1); 0 is rejected (no sequential mode). */
     workers?: string;
+    /** Process-detection process cap. Positive integer string; `0` is invalid. */
+    maxProcesses?: string;
+    /** Process-detection per-node branching cap. Positive integer string. */
+    maxProcessBranching?: string;
+    /** Process-detection DFS depth cap. Positive integer string. */
+    maxProcessTraceDepth?: string;
+    /** Ranked entry-point candidate pool. Positive integer string. */
+    maxEntryPointCandidates?: string;
     embeddingThreads?: string;
     embeddingBatchSize?: string;
     embeddingSubBatchSize?: string;

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 { formatInvalidProcessDetectionOverride, parseProcessDetectionBudgetStrings, } from '../core/ingestion/process-detection-budget.js';
 import { WATCH_FULL_REFRESH_PATH, WatchRefreshQueue, } from './watch-queue.js';
 const DEFAULT_DEBOUNCE_MS = 300;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
@@ -119,6 +120,14 @@ export async function resolveWatchOptions(repoPath, cli, baseline, reportIgnored
     const workerPoolSize = positiveInteger(merged.workers, '--workers');
     const workerTimeoutSeconds = positiveInteger(merged.workerTimeout, 'workerTimeout');
     const maxFileSize = positiveInteger(merged.maxFileSize, 'maxFileSize', MAX_FILE_SIZE_KB);
+    const processDetection = parseProcessDetectionBudgetStrings({
+        maxProcesses: merged.maxProcesses,
+        maxProcessBranching: merged.maxProcessBranching,
+        maxProcessTraceDepth: merged.maxProcessTraceDepth,
+        maxEntryPointCandidates: merged.maxEntryPointCandidates,
+    }, (flag, raw) => {
+        cliWarn(formatInvalidProcessDetectionOverride(flag, raw));
+    });
     setEnvironment('GITNEXUS_MAX_FILE_SIZE', maxFileSize === undefined ? baseline.maxFileSize : String(maxFileSize));
     if (workerTimeoutSeconds !== undefined) {
         process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(workerTimeoutSeconds * 1000);
@@ -134,6 +143,10 @@ export async function resolveWatchOptions(repoPath, cli, baseline, reportIgnored
         registryName: merged.name,
         allowDuplicateName: merged.allowDuplicateName,
         workerPoolSize,
+        maxProcesses: processDetection.maxProcesses,
+        maxProcessBranching: processDetection.maxProcessBranching,
+        maxProcessTraceDepth: processDetection.maxProcessTraceDepth,
+        maxEntryPointCandidates: processDetection.maxEntryPointCandidates,
         fetchWrappers: merged.fetchWrappers,
         skipAgentsMd: true,
         skipSkills: true,

package/dist/cli/analyze.js

@@ -25,6 +25,7 @@ import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateB
 import { runFullAnalysis } from '../core/run-analyze.js';
 import { getRuntimeFingerprint } from '../core/platform/capabilities.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
+import { formatInvalidProcessDetectionOverride, formatProcessDetectionBudgetBanner, parseProcessDetectionBudgetStrings, resolveProcessDetectionBudget, } from '../core/ingestion/process-detection-budget.js';
 import { warnMissingOptionalGrammars, getOptionalGrammarExtensions } from './optional-grammars.js';
 import { glob } from 'glob';
 import fs from 'fs/promises';
@@ -753,6 +754,14 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
         }
         workerPoolSize = parsedWorkers;
     }
+    const processDetectionFromFlags = parseProcessDetectionBudgetStrings({
+        maxProcesses: options.maxProcesses,
+        maxProcessBranching: options.maxProcessBranching,
+        maxProcessTraceDepth: options.maxProcessTraceDepth,
+        maxEntryPointCandidates: options.maxEntryPointCandidates,
+    }, (flag, raw) => {
+        cliWarn(`  ${formatInvalidProcessDetectionOverride(flag, raw)}\n`);
+    });
     // Parse `--embeddings [limit]`: `true` → default cap, string → numeric cap
     // (0 disables the cap entirely). Validated up here so failures match the
     // sibling-validation pattern (exit before bar.start() — otherwise
@@ -987,6 +996,10 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
     if (maxFileSizeBanner) {
         console.log(`${maxFileSizeBanner}\n`);
     }
+    const processDetectionBanner = formatProcessDetectionBudgetBanner(resolveProcessDetectionBudget(processDetectionFromFlags));
+    if (processDetectionBanner) {
+        console.log(`${processDetectionBanner}\n`);
+    }
     // ── CLI progress bar setup ─────────────────────────────────────────
     const barOptions = {
         format: '  {bar} {percentage}% | {phase}',
@@ -1119,6 +1132,10 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
             // env / auto-formula fallback inside the pipeline.
             workerPoolSize,
+            maxProcesses: processDetectionFromFlags.maxProcesses,
+            maxProcessBranching: processDetectionFromFlags.maxProcessBranching,
+            maxProcessTraceDepth: processDetectionFromFlags.maxProcessTraceDepth,
+            maxEntryPointCandidates: processDetectionFromFlags.maxEntryPointCandidates,
             // Extra fetch-wrapper names from `.gitnexusrc` (#1589/#1852 residual);
             // forwarded to the routes phase consumer scan.
             fetchWrappers: options.fetchWrappers,

package/dist/cli/help-i18n.js

@@ -68,6 +68,10 @@ const OPTION_DESCRIPTION_KEYS = {
     'analyze|--worker-timeout <seconds>': 'help.option.analyze.workerTimeout',
     'analyze|--wal-checkpoint-threshold <bytes>': 'help.option.analyze.walCheckpointThreshold',
     'analyze|--workers <n>': 'help.option.analyze.workers',
+    'analyze|--max-processes <n>': 'help.option.analyze.maxProcesses',
+    'analyze|--max-process-branching <n>': 'help.option.analyze.maxProcessBranching',
+    'analyze|--max-process-trace-depth <n>': 'help.option.analyze.maxProcessTraceDepth',
+    'analyze|--max-entry-point-candidates <n>': 'help.option.analyze.maxEntryPointCandidates',
     'analyze|--embedding-threads <n>': 'help.option.analyze.embeddingThreads',
     'analyze|--embedding-batch-size <n>': 'help.option.analyze.embeddingBatchSize',
     'analyze|--embedding-sub-batch-size <n>': 'help.option.analyze.embeddingSubBatchSize',

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

@@ -193,6 +193,10 @@ export declare const en: {
     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 (>=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.';
+    readonly 'help.option.analyze.maxProcessTraceDepth': 'Process-detection DFS depth cap (positive integer). Default: 10.';
+    readonly 'help.option.analyze.maxEntryPointCandidates': 'Ranked entry-point candidate pool (positive integer). Default: 200. Raise when the warning names this knob; doubling is the usual first raise.';
     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';
@@ -278,5 +282,5 @@ export declare const en: {
     readonly 'help.option.group.contracts.repo': 'Filter by repo';
     readonly 'help.option.group.contracts.unmatched': 'Show only unmatched contracts';
     readonly 'help.identityCache.environment': '\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.';
-    readonly 'help.analyze.environment': '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).';
+    readonly 'help.analyze.environment': '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n  GITNEXUS_MAX_PROCESSES=N  Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Distinct from query-time IMPACT_MAX_CHUNKS.\n  GITNEXUS_MAX_PROCESS_BRANCHING=N  Process-detection per-node branching cap. Default 4.\n  GITNEXUS_MAX_PROCESS_TRACE_DEPTH=N  Process-detection DFS depth cap. Default 10.\n  GITNEXUS_MAX_ENTRY_POINT_CANDIDATES=N  Ranked entry-point candidate pool. Default 200. Raise when the warning names this knob; doubling is the usual first raise.\n\nCLI flags take precedence over `.gitnexusrc`, which takes precedence over env vars, which take precedence over built-in defaults.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).';
 };

package/dist/cli/i18n/en.js

@@ -195,6 +195,10 @@ export const en = {
     '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 (>=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.',
+    'help.option.analyze.maxProcessTraceDepth': 'Process-detection DFS depth cap (positive integer). Default: 10.',
+    'help.option.analyze.maxEntryPointCandidates': 'Ranked entry-point candidate pool (positive integer). Default: 200. Raise when the warning names this knob; doubling is the usual first raise.',
     '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',
@@ -280,5 +284,5 @@ export const en = {
     'help.option.group.contracts.repo': 'Filter by repo',
     'help.option.group.contracts.unmatched': 'Show only unmatched contracts',
     'help.identityCache.environment': '\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.',
-    'help.analyze.environment': '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
+    'help.analyze.environment': '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n  GITNEXUS_MAX_PROCESSES=N  Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Distinct from query-time IMPACT_MAX_CHUNKS.\n  GITNEXUS_MAX_PROCESS_BRANCHING=N  Process-detection per-node branching cap. Default 4.\n  GITNEXUS_MAX_PROCESS_TRACE_DEPTH=N  Process-detection DFS depth cap. Default 10.\n  GITNEXUS_MAX_ENTRY_POINT_CANDIDATES=N  Ranked entry-point candidate pool. Default 200. Raise when the warning names this knob; doubling is the usual first raise.\n\nCLI flags take precedence over `.gitnexusrc`, which takes precedence over env vars, which take precedence over built-in defaults.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
 };

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

@@ -194,6 +194,10 @@ export declare const cliResources: {
         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 (>=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.';
+        readonly 'help.option.analyze.maxProcessTraceDepth': 'Process-detection DFS depth cap (positive integer). Default: 10.';
+        readonly 'help.option.analyze.maxEntryPointCandidates': 'Ranked entry-point candidate pool (positive integer). Default: 200. Raise when the warning names this knob; doubling is the usual first raise.';
         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';
@@ -279,7 +283,7 @@ export declare const cliResources: {
         readonly 'help.option.group.contracts.repo': 'Filter by repo';
         readonly 'help.option.group.contracts.unmatched': 'Show only unmatched contracts';
         readonly 'help.identityCache.environment': '\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.';
-        readonly 'help.analyze.environment': '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).';
+        readonly 'help.analyze.environment': '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n  GITNEXUS_MAX_PROCESSES=N  Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Distinct from query-time IMPACT_MAX_CHUNKS.\n  GITNEXUS_MAX_PROCESS_BRANCHING=N  Process-detection per-node branching cap. Default 4.\n  GITNEXUS_MAX_PROCESS_TRACE_DEPTH=N  Process-detection DFS depth cap. Default 10.\n  GITNEXUS_MAX_ENTRY_POINT_CANDIDATES=N  Ranked entry-point candidate pool. Default 200. Raise when the warning names this knob; doubling is the usual first raise.\n\nCLI flags take precedence over `.gitnexusrc`, which takes precedence over env vars, which take precedence over built-in defaults.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).';
     };
     readonly 'zh-CN': {
         'common.notIndexed': string;
@@ -476,6 +480,10 @@ export declare const cliResources: {
         'help.option.analyze.workerTimeout': string;
         'help.option.analyze.walCheckpointThreshold': string;
         'help.option.analyze.workers': string;
+        'help.option.analyze.maxProcesses': string;
+        'help.option.analyze.maxProcessBranching': string;
+        'help.option.analyze.maxProcessTraceDepth': string;
+        'help.option.analyze.maxEntryPointCandidates': string;
         'help.option.analyze.embeddingThreads': string;
         'help.option.analyze.embeddingBatchSize': string;
         'help.option.analyze.embeddingSubBatchSize': string;

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

@@ -193,6 +193,10 @@ export declare const zhCN: {
     'help.option.analyze.workerTimeout': string;
     'help.option.analyze.walCheckpointThreshold': string;
     'help.option.analyze.workers': string;
+    'help.option.analyze.maxProcesses': string;
+    'help.option.analyze.maxProcessBranching': string;
+    'help.option.analyze.maxProcessTraceDepth': string;
+    'help.option.analyze.maxEntryPointCandidates': string;
     'help.option.analyze.embeddingThreads': string;
     'help.option.analyze.embeddingBatchSize': string;
     'help.option.analyze.embeddingSubBatchSize': string;

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

@@ -193,6 +193,10 @@ export const zhCN = {
     '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.workers': '解析 worker 池大小（>=1）。默认：cores-1，最多 16，按仓库规模自适应。',
+    'help.option.analyze.maxProcesses': '流程检测的流程数量上限（正整数）。覆盖动态的 max(20, round(symbols/10)) 公式。默认：动态。',
+    'help.option.analyze.maxProcessBranching': '流程检测的单节点分支上限（正整数）。默认：4。',
+    'help.option.analyze.maxProcessTraceDepth': '流程检测的 DFS 深度上限（正整数）。默认：10。',
+    'help.option.analyze.maxEntryPointCandidates': '排序后的入口点候选池（正整数）。默认：200。仅在警告点名该上限时提高；那时通常先翻倍。',
     'help.option.analyze.embeddingThreads': '限制本地 ONNX 嵌入 CPU 线程数',
     'help.option.analyze.embeddingBatchSize': '每个嵌入批次的节点数',
     'help.option.analyze.embeddingSubBatchSize': '每次嵌入模型调用的分块数',
@@ -278,5 +282,5 @@ export const zhCN = {
     'help.option.group.contracts.repo': '按仓库过滤',
     'help.option.group.contracts.unmatched': '仅显示未匹配契约',
     'help.identityCache.environment': '\n分析器身份缓存：\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    由操作员明确信任的持久缓存，用于跨进程快速查询状态。目录必须预先存在、位于 GitNexus 包/构建根目录之外，且路径中不得包含符号链接或 junction。缺少 POSIX 所有权 API 的平台默认保持故障关闭。',
-    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_STORAGE_PATH=/absolute/index  完整外部索引目录。保留既有配置语义；与 GITNEXUS_STORAGE_ROOT 同时设置时优先使用。\n  GITNEXUS_STORAGE_ROOT=/absolute/root  外部索引根目录；每个仓库使用独立的 <仓库名>-<规范路径哈希>/ 子目录。\n  GITNEXUS_CONTENT_RETENTION=full  源码文本保留策略：full、symbol 或 none。默认 full。\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker 空闲超时（毫秒）。默认 30000。\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker 作业字节预算。默认 8388608。\n  GITNEXUS_WORKER_POOL_SIZE=N  解析 worker 数量覆盖值。默认 cores-1，最多 16。\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  并发进行中的解析分块数。默认 2。\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  每个 slot 丢弃前允许的最大替换进程数。默认 3。\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  线程池关闭时等待仍在原生代码中的已退役 worker 的最长时间（到达安全点后再终止，避免进程级 abort）。默认 30000。\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  C++ 捕获提取的每文件墙钟预算；超出后该文件保留部分捕获并输出警告。默认 20000。\n  GITNEXUS_EMBEDDING_THREADS=N  限制 --embeddings 的本地 ONNX CPU 线程数。\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  将单次 HTTP 嵌入超时纳入 GITNEXUS_EMBEDDING_MAX_ATTEMPTS 重试（默认关闭，超时仍为终止错误）。\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  exact-scan 回退的最大嵌入分块数。默认 10000。\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  语义/向量搜索接受的最大余弦距离（0 < N <= 2；超出则钳制为 2）。MCP 默认 0.6，其他路径默认 0.5。\n\n当参数和对应环境变量同时提供时，参数优先。\n\n提示：`.gitnexusignore` 支持 `.gitignore` 风格的取反。比如添加\n     `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
+    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_STORAGE_PATH=/absolute/index  完整外部索引目录。保留既有配置语义；与 GITNEXUS_STORAGE_ROOT 同时设置时优先使用。\n  GITNEXUS_STORAGE_ROOT=/absolute/root  外部索引根目录；每个仓库使用独立的 <仓库名>-<规范路径哈希>/ 子目录。\n  GITNEXUS_CONTENT_RETENTION=full  源码文本保留策略：full、symbol 或 none。默认 full。\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker 空闲超时（毫秒）。默认 30000。\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker 作业字节预算。默认 8388608。\n  GITNEXUS_WORKER_POOL_SIZE=N  解析 worker 数量覆盖值。默认 cores-1，最多 16。\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  并发进行中的解析分块数。默认 2。\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  每个 slot 丢弃前允许的最大替换进程数。默认 3。\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  线程池关闭时等待仍在原生代码中的已退役 worker 的最长时间（到达安全点后再终止，避免进程级 abort）。默认 30000。\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  C++ 捕获提取的每文件墙钟预算；超出后该文件保留部分捕获并输出警告。默认 20000。\n  GITNEXUS_EMBEDDING_THREADS=N  限制 --embeddings 的本地 ONNX CPU 线程数。\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  将单次 HTTP 嵌入超时纳入 GITNEXUS_EMBEDDING_MAX_ATTEMPTS 重试（默认关闭，超时仍为终止错误）。\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  exact-scan 回退的最大嵌入分块数。默认 10000。\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  语义/向量搜索接受的最大余弦距离（0 < N <= 2；超出则钳制为 2）。MCP 默认 0.6，其他路径默认 0.5。\n  GITNEXUS_MAX_PROCESSES=N  流程检测的流程数量上限（正整数）。覆盖动态的 max(20, round(symbols/10)) 公式。与查询时的 IMPACT_MAX_CHUNKS 无关。\n  GITNEXUS_MAX_PROCESS_BRANCHING=N  流程检测的单节点分支上限。默认 4。\n  GITNEXUS_MAX_PROCESS_TRACE_DEPTH=N  流程检测的 DFS 深度上限。默认 10。\n  GITNEXUS_MAX_ENTRY_POINT_CANDIDATES=N  排序后的入口点候选池。默认 200。仅在警告点名该上限时提高；那时通常先翻倍。\n\nCLI 参数优先于 `.gitnexusrc`，后者优先于环境变量，环境变量优先于内置默认值。\n\n提示：`.gitnexusignore` 支持 `.gitignore` 风格的取反。比如添加\n     `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
 };

package/dist/cli/index.js

@@ -85,6 +85,10 @@ program
     .option('--wal-checkpoint-threshold <bytes>', 'LadybugDB WAL auto-checkpoint threshold in bytes during analyze ' +
     '(integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).')
     .option('--workers <n>', 'Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.')
+    .option('--max-processes <n>', 'Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Default: dynamic.')
+    .option('--max-process-branching <n>', 'Process-detection per-node branching cap (positive integer). Default: 4.')
+    .option('--max-process-trace-depth <n>', 'Process-detection DFS depth cap (positive integer). Default: 10.')
+    .option('--max-entry-point-candidates <n>', 'Ranked entry-point candidate pool (positive integer). Default: 200. Raise when the warning names this knob; doubling is the usual first raise.')
     .option('--spring-actuator <path>', 'Import local Spring Boot Actuator JSON snapshots (mappings, beans, conditions, ' +
     'configprops, env). Explicit opt-in; disabled by default.')
     .option('--asyncapi-spec <path>', 'Read AsyncAPI 3.x documents from this directory or file and resolve broker ' +

package/dist/core/git-ref.d.ts

@@ -1,10 +1,10 @@
 /**
  * Git ref-name validation used by both the CLI and the HTTP analyze route.
  *
- * Lives in `core/` so `server/api.ts` does not import `cli/analyze-config`
- * (that import closed a cli → server → cli cycle: `cli/serve.ts` already
- * imports `createServer`). The CLI keeps a thin wrapper that rethrows
- * {@link InvalidBranchError} as `GitNexusRcError`.
+ * Lives in `core/` so `server/api.ts` and `run-analyze.ts` do not import
+ * `cli/analyze-config` (that import closed a cli → server → cli cycle:
+ * `cli/serve.ts` already imports `createServer`). The CLI keeps a thin
+ * wrapper that rethrows {@link InvalidBranchError} as `GitNexusRcError`.
  */
 /**
  * Thrown when a user-supplied branch name fails {@link validateBranchName}.
@@ -20,3 +20,21 @@ export declare class InvalidBranchError extends Error {
  * branches use (`feature/foo-bar`, `release/1.2`, `develop`).
  */
 export declare function validateBranchName(value: string, source: string): string;
+/**
+ * Best-effort validation for an auto-detected branch (from git). Returns the
+ * trimmed name, or `undefined` for anything unusable so callers fall back to
+ * the next precedence tier or leave the index unlabeled. Swallows
+ * {@link InvalidBranchError} only; unexpected errors are rethrown.
+ */
+export declare function sanitizeDetectedBranch(value: string | null | undefined): string | undefined;
+/**
+ * Render a rejected checkout name for `onLog`. Hidden / bidi / control code
+ * points become `\uXXXX` so a git-legal U+202E name cannot reverse the
+ * warning in a terminal. C1 controls (U+0080–U+009F, including NEL U+0085)
+ * and remaining Unicode whitespace (`/\s/` — NBSP, U+2028/U+2029, ideographic
+ * space, etc.) are not all in {@link isHiddenOrControl}; escape them the same
+ * way so the ASCII escape survives `stripControlCharacters` and the warning
+ * stays one line. ASCII `"` is escaped; other characters (including backticks)
+ * stay visible.
+ */
+export declare function formatRejectedBranchForLog(value: string): string;

package/dist/core/git-ref.js

@@ -1,10 +1,10 @@
 /**
  * Git ref-name validation used by both the CLI and the HTTP analyze route.
  *
- * Lives in `core/` so `server/api.ts` does not import `cli/analyze-config`
- * (that import closed a cli → server → cli cycle: `cli/serve.ts` already
- * imports `createServer`). The CLI keeps a thin wrapper that rethrows
- * {@link InvalidBranchError} as `GitNexusRcError`.
+ * Lives in `core/` so `server/api.ts` and `run-analyze.ts` do not import
+ * `cli/analyze-config` (that import closed a cli → server → cli cycle:
+ * `cli/serve.ts` already imports `createServer`). The CLI keeps a thin
+ * wrapper that rethrows {@link InvalidBranchError} as `GitNexusRcError`.
  */
 /** Git refs longer than this are almost certainly a mistake / injection attempt. */
 const BRANCH_MAX_LENGTH = 255;
@@ -112,3 +112,48 @@ export function validateBranchName(value, source) {
     }
     return trimmed;
 }
+/**
+ * Best-effort validation for an auto-detected branch (from git). Returns the
+ * trimmed name, or `undefined` for anything unusable so callers fall back to
+ * the next precedence tier or leave the index unlabeled. Swallows
+ * {@link InvalidBranchError} only; unexpected errors are rethrown.
+ */
+export function sanitizeDetectedBranch(value) {
+    if (!value)
+        return undefined;
+    try {
+        return validateBranchName(value, 'detected branch');
+    }
+    catch (err) {
+        if (err instanceof InvalidBranchError)
+            return undefined;
+        throw err;
+    }
+}
+/**
+ * Render a rejected checkout name for `onLog`. Hidden / bidi / control code
+ * points become `\uXXXX` so a git-legal U+202E name cannot reverse the
+ * warning in a terminal. C1 controls (U+0080–U+009F, including NEL U+0085)
+ * and remaining Unicode whitespace (`/\s/` — NBSP, U+2028/U+2029, ideographic
+ * space, etc.) are not all in {@link isHiddenOrControl}; escape them the same
+ * way so the ASCII escape survives `stripControlCharacters` and the warning
+ * stays one line. ASCII `"` is escaped; other characters (including backticks)
+ * stay visible.
+ */
+export function formatRejectedBranchForLog(value) {
+    const shouldEscapeRejectedBranchChar = (cp, ch) => isHiddenOrControl(cp) || (cp >= 0x80 && cp <= 0x9f) || /\s/.test(ch);
+    let out = '';
+    for (const ch of value) {
+        const cp = ch.codePointAt(0);
+        if (cp !== undefined && shouldEscapeRejectedBranchChar(cp, ch)) {
+            out += `\\u${cp.toString(16).padStart(4, '0')}`;
+            continue;
+        }
+        if (ch === '"') {
+            out += '\\"';
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}

package/dist/core/ingestion/pipeline-phases/processes.js

@@ -12,6 +12,7 @@
  */
 import { getPhaseOutput } from './types.js';
 import { processProcesses } from '../process-processor.js';
+import { buildProcessDetectionPhaseConfig, formatWholeFlowsMissingRemedies, processDetectionEffectiveLimits, resolveProcessDetectionBudget, } from '../process-detection-budget.js';
 import { generateId } from '../../../lib/utils.js';
 import { routeNodeKey } from '../route-extractors/route-path.js';
 import { isDev } from '../utils/env.js';
@@ -60,12 +61,24 @@ export const processesPhase = {
             message: 'Detecting execution flows...',
             stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
         });
+        const resolvedBudget = resolveProcessDetectionBudget({
+            maxProcesses: ctx.options?.maxProcesses,
+            maxProcessBranching: ctx.options?.maxProcessBranching,
+            maxProcessTraceDepth: ctx.options?.maxProcessTraceDepth,
+            maxEntryPointCandidates: ctx.options?.maxEntryPointCandidates,
+        }, 
+        // Env is resolved in `runFullAnalysis` and threaded on PipelineOptions.
+        // The phase reads only those fields so unit tests stay isolated from
+        // the host environment.
+        {});
         let symbolCount = 0;
-        ctx.graph.forEachNode((n) => {
-            if (n.label !== 'File')
-                symbolCount++;
-        });
-        const dynamicMaxProcesses = computeDynamicMaxProcesses(symbolCount);
+        if (resolvedBudget.maxProcesses === undefined) {
+            ctx.graph.forEachNode((n) => {
+                if (n.label !== 'File')
+                    symbolCount++;
+            });
+        }
+        const detectionConfig = buildProcessDetectionPhaseConfig(resolvedBudget, symbolCount, computeDynamicMaxProcesses);
         // R3-6: where the program reaches outward. Already collected by the parse
         // phase for FILE-level FETCHES/QUERIES edges; reused here at function
         // granularity so a trace can end somewhere meaningful instead of only at a
@@ -100,7 +113,7 @@ export const processesPhase = {
                 message,
                 stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
             });
-        }, { maxProcesses: dynamicMaxProcesses, minSteps: 3 }, outwardActionSites);
+        }, detectionConfig, outwardActionSites);
         if (isDev) {
             logger.info(`🔄 Process detection: ${processResult.stats.totalProcesses} processes found (${processResult.stats.crossCommunityCount} cross-community)`);
         }
@@ -114,8 +127,8 @@ export const processesPhase = {
         // "unexplored entry points mean whole flows are missing, while a
         // depth-capped trace means a flow is present but shorter than it really is"
         // — and it is what keeps the line worth reading. Warning on every counter
-        // meant warning on every run: this phase overrides only `maxProcesses`, so
-        // at the shipped defaults (`maxBranching: 4`, `maxTraceDepth: 10`,
+        // meant warning on every run: at the shipped defaults (`maxBranching: 4`,
+        // `maxTraceDepth: 10`,
         // per-entry trace budget 12) `calleesDropped` fires for any function with
         // five callees, `tracesDepthCapped` for any chain deeper than ten, and
         // `walksCutByBudget` for any entry point with twelve paths under it. All
@@ -140,6 +153,8 @@ export const processesPhase = {
         const flowsMissing = truncation.entryPointCandidatesDropped > 0 ||
             truncation.entryPointsUnexplored > 0 ||
             truncation.processesDropped > 0;
+        const effectiveLimits = processDetectionEffectiveLimits(detectionConfig.maxProcesses, resolvedBudget);
+        const remedies = formatWholeFlowsMissingRemedies(truncation, effectiveLimits, entryPointCandidates);
         const shape = `${truncation.entryPointCandidatesDropped} of ${entryPointCandidates} candidate entry point(s) never ranked in, ` +
             `${truncation.entryPointsUnexplored} ranked entry point(s) never traced, ` +
             `${truncation.processesDropped} deduplicated flow(s) dropped at maxProcesses, ` +
@@ -147,11 +162,11 @@ export const processesPhase = {
             `${truncation.calleesDropped} callee(s) skipped at maxBranching, ` +
             `${truncation.walksCutByBudget} walk(s) cut by the per-entry trace budget.`;
         if (flowsMissing) {
-            logger.warn({ truncation }, `[processes] ${processResult.stats.totalProcesses} flows reported, but whole flows are MISSING: ` +
-                `${shape} An absent flow does NOT mean the code path does not exist.`);
+            logger.warn({ truncation, effectiveLimits }, `[processes] ${processResult.stats.totalProcesses} flows reported, but whole flows are MISSING: ` +
+                `${shape}${remedies} An absent flow does NOT mean the code path does not exist.`);
         }
         else if (truncation.truncated) {
-            logger.debug({ truncation }, `[processes] ${processResult.stats.totalProcesses} flows reported; every flow found is present, ` +
+            logger.debug({ truncation, effectiveLimits }, `[processes] ${processResult.stats.totalProcesses} flows reported; every flow found is present, ` +
                 `but some are shorter than the code path they describe: ${shape}`);
         }
         processResult.processes.forEach((proc) => {

package/dist/core/ingestion/pipeline.d.ts

@@ -204,6 +204,15 @@ export interface PipelineOptions {
      * analyze invocations.
      */
     workerPoolSize?: number;
+    /**
+     * Process-detection budget (#3313). Explicit `maxProcesses` replaces the
+     * dynamic `symbols / 10` formula; the other three replace compiled defaults.
+     * Unset fields keep shipped behavior. `0` is rejected upstream — not unlimited.
+     */
+    maxProcesses?: number;
+    maxProcessBranching?: number;
+    maxProcessTraceDepth?: number;
+    maxEntryPointCandidates?: number;
     /**
      * Number of chunks whose file contents may be read into memory in
      * parallel while the worker pool is busy dispatching the current

package/dist/core/ingestion/pipeline.js

@@ -136,8 +136,8 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
     const pdgEmitManifest = scopeResolutionOutput.pdgEmitManifest;
     const propertyInference = scopeResolutionOutput.propertyInference;
     // Presence check, not `!skipGraphPhases`: phases can now be filtered out by
-    // any `enabledWhen` predicate (streamGraphEmit disables communities/processes
-    // too), and `getPhaseOutput` THROWS on a phase that was never resolved. Keying
+    // any `enabledWhen` predicate (`skipGraphPhases` drops communities/processes),
+    // and `getPhaseOutput` THROWS on a phase that was never resolved. Keying
     // off the options flag alone made every filtered-out combination crash here
     // rather than return undefined results.
     if (results.has('communities') && results.has('processes')) {