gitnexus 1.6.13-rc.16 → 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.js

@@ -76,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' },

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/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')) {

package/dist/core/ingestion/process-detection-budget.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Analyze-time process-detection budget (#3313).
+ *
+ * Four knobs control how many execution flows `processProcesses` keeps:
+ * process count, per-node branching, trace depth, and the ranked entry-point
+ * pool. Precedence is CLI / explicit `AnalyzeOptions` > `.gitnexusrc` (already
+ * merged into those fields) > `GITNEXUS_*` env > built-in defaults. Unset
+ * `maxProcesses` keeps the dynamic `symbols / 10` formula. `0` is invalid, not
+ * unlimited.
+ */
+import type { ProcessDetectionConfig, ProcessTruncationStats } from './process-processor.js';
+export declare const PROCESS_DETECTION_BUDGET_DEFAULTS: {
+    readonly maxProcessBranching: 4;
+    readonly maxProcessTraceDepth: 10;
+    readonly maxEntryPointCandidates: 200;
+    readonly minSteps: 3;
+};
+export declare const PROCESS_DETECTION_ENV: {
+    readonly maxProcesses: 'GITNEXUS_MAX_PROCESSES';
+    readonly maxProcessBranching: 'GITNEXUS_MAX_PROCESS_BRANCHING';
+    readonly maxProcessTraceDepth: 'GITNEXUS_MAX_PROCESS_TRACE_DEPTH';
+    readonly maxEntryPointCandidates: 'GITNEXUS_MAX_ENTRY_POINT_CANDIDATES';
+};
+export declare const PROCESS_DETECTION_CLI_FLAGS: {
+    readonly maxProcesses: '--max-processes';
+    readonly maxProcessBranching: '--max-process-branching';
+    readonly maxProcessTraceDepth: '--max-process-trace-depth';
+    readonly maxEntryPointCandidates: '--max-entry-point-candidates';
+};
+declare const BUDGET_KEYS: readonly ['maxProcesses', 'maxProcessBranching', 'maxProcessTraceDepth', 'maxEntryPointCandidates'];
+export type ProcessDetectionBudgetKey = (typeof BUDGET_KEYS)[number];
+export type ProcessDetectionBudgetFields = {
+    maxProcesses?: number;
+    maxProcessBranching?: number;
+    maxProcessTraceDepth?: number;
+    maxEntryPointCandidates?: number;
+};
+export type ProcessDetectionBudgetStrings = {
+    maxProcesses?: string;
+    maxProcessBranching?: string;
+    maxProcessTraceDepth?: string;
+    maxEntryPointCandidates?: string;
+};
+export type ProcessDetectionStamp = {
+    /** Explicit override, or `null` when this run used the dynamic formula. */
+    maxProcesses: number | null;
+    maxProcessBranching: number;
+    maxProcessTraceDepth: number;
+    maxEntryPointCandidates: number;
+    /**
+     * In-place FTS park after a derived-layer rewrite (#3322). Missing stamp +
+     * defaults is a match, so recovery must persist a complete stamp that still
+     * mismatches until a successful analyze certifies the live Community/Process
+     * rows. Success writes omit this flag.
+     */
+    uncertified?: true;
+};
+export type ResolvedProcessDetectionBudget = {
+    /** Set only when an explicit override won. */
+    maxProcesses?: number;
+    maxProcessBranching: number;
+    maxProcessTraceDepth: number;
+    maxEntryPointCandidates: number;
+    overridden: {
+        maxProcesses: boolean;
+        maxProcessBranching: boolean;
+        maxProcessTraceDepth: boolean;
+        maxEntryPointCandidates: boolean;
+    };
+};
+export type ProcessDetectionEffectiveLimits = {
+    maxProcesses: number;
+    maxProcessBranching: number;
+    maxProcessTraceDepth: number;
+    maxEntryPointCandidates: number;
+    /**
+     * Pre-entry gate: `processProcesses` does not start the next entry once
+     * collected traces already reach `maxProcesses * 2`. One started entry can
+     * still append every trace `traceFromEntryPoint` returns.
+     */
+    maxProcessTraces: number;
+};
+export type InvalidBudgetHandler = (knob: string, raw: string) => void;
+/** Operator copy when a CLI/rc/env token is rejected. Next precedence still applies. */
+export declare const formatInvalidProcessDetectionOverride: (knob: string, raw: string) => string;
+export declare const parsePositiveIntegerOverride: (raw: string | number | undefined | null, onInvalid?: (raw: string) => void) => number | undefined;
+export declare const parseProcessDetectionBudgetStrings: (raw: ProcessDetectionBudgetStrings, onInvalid?: InvalidBudgetHandler) => ProcessDetectionBudgetFields;
+export declare const resolveProcessDetectionBudget: (options?: ProcessDetectionBudgetFields, env?: NodeJS.ProcessEnv, onInvalid?: InvalidBudgetHandler) => ResolvedProcessDetectionBudget;
+export declare const hasProcessDetectionOverride: (resolved: ResolvedProcessDetectionBudget) => boolean;
+export declare const toProcessDetectionStamp: (resolved: ResolvedProcessDetectionBudget) => ProcessDetectionStamp;
+/** Complete stamp that always mismatches until the next successful analyze. */
+export declare const uncertifyProcessDetectionStamp: (recorded: ProcessDetectionStamp | undefined) => ProcessDetectionStamp;
+export declare const processDetectionBudgetMismatch: (recorded: ProcessDetectionStamp | undefined, resolved: ResolvedProcessDetectionBudget) => boolean;
+export declare const buildProcessDetectionPhaseConfig: (resolved: ResolvedProcessDetectionBudget, symbolCount: number, computeDynamicMaxProcesses: (n: number) => number) => Pick<ProcessDetectionConfig, 'maxProcesses' | 'maxBranching' | 'maxTraceDepth' | 'maxEntryPointCandidates' | 'minSteps'>;
+export declare const processDetectionEffectiveLimits: (maxProcesses: number, resolved: ResolvedProcessDetectionBudget) => ProcessDetectionEffectiveLimits;
+export declare const formatWholeFlowsMissingRemedies: (truncation: Pick<ProcessTruncationStats, 'entryPointCandidatesDropped' | 'entryPointsUnexplored' | 'processesDropped'>, limits: ProcessDetectionEffectiveLimits, observedEntryPointCandidates: number) => string;
+export declare const formatProcessDetectionBudgetBanner: (resolved: ResolvedProcessDetectionBudget) => string | null;
+export {};

package/dist/core/ingestion/process-detection-budget.js

@@ -0,0 +1,171 @@
+/**
+ * Analyze-time process-detection budget (#3313).
+ *
+ * Four knobs control how many execution flows `processProcesses` keeps:
+ * process count, per-node branching, trace depth, and the ranked entry-point
+ * pool. Precedence is CLI / explicit `AnalyzeOptions` > `.gitnexusrc` (already
+ * merged into those fields) > `GITNEXUS_*` env > built-in defaults. Unset
+ * `maxProcesses` keeps the dynamic `symbols / 10` formula. `0` is invalid, not
+ * unlimited.
+ */
+import { parsePositiveIntEnv } from './utils/env.js';
+export const PROCESS_DETECTION_BUDGET_DEFAULTS = {
+    maxProcessBranching: 4,
+    maxProcessTraceDepth: 10,
+    maxEntryPointCandidates: 200,
+    minSteps: 3,
+};
+export const PROCESS_DETECTION_ENV = {
+    maxProcesses: 'GITNEXUS_MAX_PROCESSES',
+    maxProcessBranching: 'GITNEXUS_MAX_PROCESS_BRANCHING',
+    maxProcessTraceDepth: 'GITNEXUS_MAX_PROCESS_TRACE_DEPTH',
+    maxEntryPointCandidates: 'GITNEXUS_MAX_ENTRY_POINT_CANDIDATES',
+};
+export const PROCESS_DETECTION_CLI_FLAGS = {
+    maxProcesses: '--max-processes',
+    maxProcessBranching: '--max-process-branching',
+    maxProcessTraceDepth: '--max-process-trace-depth',
+    maxEntryPointCandidates: '--max-entry-point-candidates',
+};
+const BUDGET_KEYS = [
+    'maxProcesses',
+    'maxProcessBranching',
+    'maxProcessTraceDepth',
+    'maxEntryPointCandidates',
+];
+/** Operator copy when a CLI/rc/env token is rejected. Next precedence still applies. */
+export const formatInvalidProcessDetectionOverride = (knob, raw) => {
+    const next = knob.startsWith('GITNEXUS_')
+        ? 'the built-in default'
+        : 'the next source (env, then the built-in default)';
+    return `${knob} must be a positive integer (got ${JSON.stringify(raw)}); ignoring it so ${next} applies.`;
+};
+export const parsePositiveIntegerOverride = (raw, onInvalid) => {
+    if (raw === undefined || raw === null)
+        return undefined;
+    const text = typeof raw === 'number' ? String(raw) : raw;
+    const parsed = parsePositiveIntEnv(text);
+    if (parsed === undefined)
+        onInvalid?.(typeof raw === 'number' ? text : text.trim());
+    return parsed;
+};
+export const parseProcessDetectionBudgetStrings = (raw, onInvalid) => {
+    const out = {};
+    for (const key of BUDGET_KEYS) {
+        if (raw[key] === undefined)
+            continue;
+        const parsed = parsePositiveIntegerOverride(raw[key], (invalid) => onInvalid?.(PROCESS_DETECTION_CLI_FLAGS[key], invalid));
+        if (parsed !== undefined)
+            out[key] = parsed;
+    }
+    return out;
+};
+const readOverride = (options, env, key, onInvalid) => {
+    const fromOptions = options[key];
+    if (fromOptions !== undefined) {
+        const parsed = parsePositiveIntegerOverride(fromOptions, (invalid) => onInvalid?.(PROCESS_DETECTION_CLI_FLAGS[key], invalid));
+        if (parsed !== undefined)
+            return parsed;
+    }
+    const envName = PROCESS_DETECTION_ENV[key];
+    const fromEnv = env[envName];
+    if (fromEnv === undefined)
+        return undefined;
+    return parsePositiveIntegerOverride(fromEnv, (invalid) => onInvalid?.(envName, invalid));
+};
+export const resolveProcessDetectionBudget = (options = {}, env = process.env, onInvalid) => {
+    const maxProcesses = readOverride(options, env, 'maxProcesses', onInvalid);
+    const branching = readOverride(options, env, 'maxProcessBranching', onInvalid);
+    const depth = readOverride(options, env, 'maxProcessTraceDepth', onInvalid);
+    const entryPoints = readOverride(options, env, 'maxEntryPointCandidates', onInvalid);
+    return {
+        ...(maxProcesses === undefined ? {} : { maxProcesses }),
+        maxProcessBranching: branching ?? PROCESS_DETECTION_BUDGET_DEFAULTS.maxProcessBranching,
+        maxProcessTraceDepth: depth ?? PROCESS_DETECTION_BUDGET_DEFAULTS.maxProcessTraceDepth,
+        maxEntryPointCandidates: entryPoints ?? PROCESS_DETECTION_BUDGET_DEFAULTS.maxEntryPointCandidates,
+        overridden: {
+            maxProcesses: maxProcesses !== undefined,
+            maxProcessBranching: branching !== undefined,
+            maxProcessTraceDepth: depth !== undefined,
+            maxEntryPointCandidates: entryPoints !== undefined,
+        },
+    };
+};
+export const hasProcessDetectionOverride = (resolved) => resolved.overridden.maxProcesses ||
+    resolved.overridden.maxProcessBranching ||
+    resolved.overridden.maxProcessTraceDepth ||
+    resolved.overridden.maxEntryPointCandidates;
+export const toProcessDetectionStamp = (resolved) => ({
+    maxProcesses: resolved.maxProcesses ?? null,
+    maxProcessBranching: resolved.maxProcessBranching,
+    maxProcessTraceDepth: resolved.maxProcessTraceDepth,
+    maxEntryPointCandidates: resolved.maxEntryPointCandidates,
+});
+/** Complete stamp that always mismatches until the next successful analyze. */
+export const uncertifyProcessDetectionStamp = (recorded) => ({
+    maxProcesses: recorded?.maxProcesses ?? null,
+    maxProcessBranching: recorded?.maxProcessBranching ?? PROCESS_DETECTION_BUDGET_DEFAULTS.maxProcessBranching,
+    maxProcessTraceDepth: recorded?.maxProcessTraceDepth ?? PROCESS_DETECTION_BUDGET_DEFAULTS.maxProcessTraceDepth,
+    maxEntryPointCandidates: recorded?.maxEntryPointCandidates ?? PROCESS_DETECTION_BUDGET_DEFAULTS.maxEntryPointCandidates,
+    uncertified: true,
+});
+const isCompleteStamp = (recorded) => recorded !== undefined &&
+    (recorded.maxProcesses === null ||
+        (typeof recorded.maxProcesses === 'number' && Number.isInteger(recorded.maxProcesses))) &&
+    Number.isInteger(recorded.maxProcessBranching) &&
+    Number.isInteger(recorded.maxProcessTraceDepth) &&
+    Number.isInteger(recorded.maxEntryPointCandidates);
+export const processDetectionBudgetMismatch = (recorded, resolved) => {
+    if (recorded?.uncertified === true)
+        return true;
+    if (!isCompleteStamp(recorded)) {
+        // Legacy meta: same defaults as today's shipped behavior stay a match so
+        // an upgrade backfills the stamp instead of re-detecting. Any explicit
+        // override is a mismatch — otherwise a budget-only raise on a pre-#3313
+        // index would preserve the sampled Community/Process layer.
+        return hasProcessDetectionOverride(resolved);
+    }
+    const stamp = toProcessDetectionStamp(resolved);
+    return (recorded.maxProcesses !== stamp.maxProcesses ||
+        recorded.maxProcessBranching !== stamp.maxProcessBranching ||
+        recorded.maxProcessTraceDepth !== stamp.maxProcessTraceDepth ||
+        recorded.maxEntryPointCandidates !== stamp.maxEntryPointCandidates);
+};
+export const buildProcessDetectionPhaseConfig = (resolved, symbolCount, computeDynamicMaxProcesses) => ({
+    maxProcesses: resolved.maxProcesses ?? computeDynamicMaxProcesses(symbolCount),
+    maxBranching: resolved.maxProcessBranching,
+    maxTraceDepth: resolved.maxProcessTraceDepth,
+    maxEntryPointCandidates: resolved.maxEntryPointCandidates,
+    minSteps: PROCESS_DETECTION_BUDGET_DEFAULTS.minSteps,
+});
+export const processDetectionEffectiveLimits = (maxProcesses, resolved) => ({
+    maxProcesses,
+    maxProcessBranching: resolved.maxProcessBranching,
+    maxProcessTraceDepth: resolved.maxProcessTraceDepth,
+    maxEntryPointCandidates: resolved.maxEntryPointCandidates,
+    maxProcessTraces: maxProcesses * 2,
+});
+export const formatWholeFlowsMissingRemedies = (truncation, limits, observedEntryPointCandidates) => {
+    const parts = [];
+    if (truncation.entryPointCandidatesDropped > 0) {
+        parts.push(`${PROCESS_DETECTION_CLI_FLAGS.maxEntryPointCandidates} ` +
+            `(this run ranked ${observedEntryPointCandidates} candidate(s))`);
+    }
+    if (truncation.entryPointsUnexplored > 0 || truncation.processesDropped > 0) {
+        parts.push(`${PROCESS_DETECTION_CLI_FLAGS.maxProcesses} ` +
+            `(this run used ${limits.maxProcesses}; next entry is skipped once ` +
+            `collected traces reach ${limits.maxProcessTraces})`);
+    }
+    return parts.length === 0 ? '' : ` Raise ${parts.join('; ')}.`;
+};
+export const formatProcessDetectionBudgetBanner = (resolved) => {
+    if (!hasProcessDetectionOverride(resolved))
+        return null;
+    const maxProcesses = resolved.overridden.maxProcesses
+        ? String(resolved.maxProcesses)
+        : 'dynamic (max(20, round(symbols/10)))';
+    return (`  Process-detection budget: maxProcesses=${maxProcesses}, ` +
+        `maxProcessBranching=${resolved.maxProcessBranching}, ` +
+        `maxProcessTraceDepth=${resolved.maxProcessTraceDepth}, ` +
+        `maxEntryPointCandidates=${resolved.maxEntryPointCandidates}`);
+};

package/dist/core/ingestion/process-processor.d.ts

@@ -16,7 +16,9 @@ export interface ProcessDetectionConfig {
     maxBranching: number;
     maxProcesses: number;
     minSteps: number;
+    maxEntryPointCandidates: number;
 }
+export declare const DEFAULT_CONFIG: ProcessDetectionConfig;
 export interface ProcessNode {
     id: string;
     label: string;
@@ -63,7 +65,7 @@ export interface ProcessTruncationStats {
     truncated: boolean;
     /**
      * Scoring candidates that never reached the trace loop because
-     * `findEntryPoints` keeps only the top `ENTRY_POINT_CANDIDATE_LIMIT`.
+     * `findEntryPoints` keeps only the top `maxEntryPointCandidates`.
      * Counted BEFORE the slice, so it sees what `entryPointsFound` cannot.
      */
     entryPointCandidatesDropped: number;

package/dist/core/ingestion/process-processor.js

@@ -13,12 +13,14 @@ import { isHeuristicEdgeReason } from '../graph/edge-reasons.js';
 import { calculateEntryPointScore, isTestFile } from './entry-point-scoring.js';
 import { SupportedLanguages } from '../../_shared/index.js';
 import { isDev } from './utils/env.js';
+import { PROCESS_DETECTION_BUDGET_DEFAULTS } from './process-detection-budget.js';
 import { logger } from '../logger.js';
-const DEFAULT_CONFIG = {
-    maxTraceDepth: 10,
-    maxBranching: 4,
+export const DEFAULT_CONFIG = {
+    maxTraceDepth: PROCESS_DETECTION_BUDGET_DEFAULTS.maxProcessTraceDepth,
+    maxBranching: PROCESS_DETECTION_BUDGET_DEFAULTS.maxProcessBranching,
     maxProcesses: 75,
-    minSteps: 3, // 3+ steps = genuine multi-hop flow (2-step is just "A calls B")
+    minSteps: PROCESS_DETECTION_BUDGET_DEFAULTS.minSteps, // 3+ steps = genuine multi-hop flow (2-step is just "A calls B")
+    maxEntryPointCandidates: PROCESS_DETECTION_BUDGET_DEFAULTS.maxEntryPointCandidates,
 };
 /** Zeroed counters, mutated in place by the walk. */
 const emptyTruncation = () => ({
@@ -58,10 +60,10 @@ outwardActionSites = []) => {
     for (const n of knowledgeGraph.iterNodes())
         nodeMap.set(n.id, n);
     // Declared before Step 1 because `findEntryPoints` has a ceiling of its own
-    // (see `ENTRY_POINT_CANDIDATE_LIMIT`) and reports it through the same record.
+    // (`cfg.maxEntryPointCandidates`, default 200) and reports it through the same record.
     const truncation = emptyTruncation();
     // Step 1: Find entry points (functions that call others but have few callers)
-    const entryPoints = findEntryPoints(knowledgeGraph, reverseCallsEdges, callsEdges, truncation);
+    const entryPoints = findEntryPoints(knowledgeGraph, reverseCallsEdges, callsEdges, truncation, cfg.maxEntryPointCandidates);
     onProgress?.(`Found ${entryPoints.length} entry points, tracing flows...`, 20);
     onProgress?.(`Found ${entryPoints.length} entry points, tracing flows...`, 20);
     // Step 2: Trace processes from each entry point
@@ -81,7 +83,7 @@ outwardActionSites = []) => {
     // the remainder are not "no flows found" — they were never looked at.
     //
     // Counted over the list `findEntryPoints` RETURNS, which is already capped at
-    // `ENTRY_POINT_CANDIDATE_LIMIT`; candidates beyond that cap are invisible here
+    // `maxEntryPointCandidates`; candidates beyond that cap are invisible here
     // by construction and are reported separately as
     // `entryPointCandidatesDropped`.
     truncation.entryPointsUnexplored = entryPoints.length - tracedEntryPoints;
@@ -327,12 +329,6 @@ const buildReverseCallsGraph = (graph) => {
     });
     return adj;
 };
-/**
- * How many ranked candidates survive to be traced. Everything below this line
- * is discarded — see `ProcessTruncationStats.entryPointCandidatesDropped`, the
- * counter that exists because this cap spent a release being invisible.
- */
-const ENTRY_POINT_CANDIDATE_LIMIT = 200;
 /**
  * Find functions/methods that are good entry points for tracing.
  *
@@ -341,7 +337,9 @@ const ENTRY_POINT_CANDIDATE_LIMIT = 200;
  * 2. Export status (exported/public functions rank higher)
  * 3. Name patterns (handle*, on*, *Controller, etc.)
  *
- * Test files are excluded entirely.
+ * Test files are excluded entirely. How many ranked candidates survive to be
+ * traced is `maxEntryPointCandidates` (default 200) — see
+ * `ProcessTruncationStats.entryPointCandidatesDropped`.
  */
 const findEntryPoints = (graph, reverseCallsEdges, callsEdges, 
 /**
@@ -351,7 +349,7 @@ const findEntryPoints = (graph, reverseCallsEdges, callsEdges,
  * unchanged, and a caller that does not care about completeness does not have
  * to unwrap a counter to ask for entry points.
  */
-truncation) => {
+truncation, maxEntryPointCandidates = DEFAULT_CONFIG.maxEntryPointCandidates) => {
     const symbolTypes = new Set(['Function', 'Method']);
     const entryPointCandidates = [];
     for (const node of graph.iterNodes()) {
@@ -397,14 +395,14 @@ truncation) => {
     }
     // Limit to prevent explosion — and SAY SO. This is the ceiling that decides
     // how much of a repository process detection ever looks at: on anything with
-    // more than 200 scoring candidates the reported flows are a sample of the
-    // top-ranked ones, and every downstream count (`entryPointsFound`,
-    // `entryPointsUnexplored`) is computed over the survivors, so none of them can
-    // see what was cut here.
-    if (truncation !== undefined && sorted.length > ENTRY_POINT_CANDIDATE_LIMIT) {
-        truncation.entryPointCandidatesDropped = sorted.length - ENTRY_POINT_CANDIDATE_LIMIT;
+    // more scoring candidates than `maxEntryPointCandidates` the reported flows
+    // are a sample of the top-ranked ones, and every downstream count
+    // (`entryPointsFound`, `entryPointsUnexplored`) is computed over the
+    // survivors, so none of them can see what was cut here.
+    if (truncation !== undefined && sorted.length > maxEntryPointCandidates) {
+        truncation.entryPointCandidatesDropped = sorted.length - maxEntryPointCandidates;
     }
-    return sorted.slice(0, ENTRY_POINT_CANDIDATE_LIMIT).map((c) => c.id);
+    return sorted.slice(0, maxEntryPointCandidates).map((c) => c.id);
 };
 // ============================================================================
 // HELPER: Trace from entry point (DFS)
@@ -618,7 +616,7 @@ const compareOrderKeys = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
  * joined strings, so an O(n log n) sort performs O(n log n) joins of
  * O(depth x id-length) characters each.
  *
- * `n` is bounded here (`ENTRY_POINT_CANDIDATE_LIMIT` entry points x the
+ * `n` is bounded here (`maxEntryPointCandidates` entry points x the
  * per-entry trace budget), so the cost is small and once-per-analyze: measured
  * at the ceiling, 23,851 comparisons performed 70,524 joins, and end-to-end
  * `processProcesses` at 80,000 functions / 640k CALLS went 456 -> 555 ms. It is

package/dist/core/run-analyze.d.ts

@@ -113,8 +113,9 @@ export interface AnalyzeOptions {
     pdgEmitChunkSize?: number;
     /** Streamed structural graph emit (#2680). Honored only on a full rebuild
      *  (`force === true`). May also be enabled via `GITNEXUS_STREAM_GRAPH_EMIT`.
-     *  Trades community detection, process extraction and PDG taint summaries for
-     *  a ~2.9x reduction of in-memory graph heap. */
+     *  The sink answers a complete relationship read, so community detection,
+     *  process extraction, and PDG taint summaries still run; streaming reduces
+     *  in-memory graph heap (~2.9x) by keeping those edges on disk. */
     streamGraphEmit?: boolean;
     /**
      * Default branch threaded into generated AGENTS.md / CLAUDE.md so the
@@ -156,6 +157,16 @@ export interface AnalyzeOptions {
      * removed); `undefined` defers to the env / auto-formula fallback.
      */
     workerPoolSize?: number;
+    /**
+     * Process-detection budget overrides (#3313). Threaded to
+     * `PipelineOptions` without mutating `process.env`. Unset fields fall
+     * back to `GITNEXUS_*` env, then shipped defaults / the dynamic
+     * `maxProcesses` formula.
+     */
+    maxProcesses?: number;
+    maxProcessBranching?: number;
+    maxProcessTraceDepth?: number;
+    maxEntryPointCandidates?: number;
     /**
      * Extra fetch-wrapper function names to treat as HTTP consumers, forwarded to
      * `PipelineOptions.fetchWrappers` (#1589/#1852 residual). Sourced from the CLI

package/dist/core/run-analyze.js

@@ -53,6 +53,7 @@ import { collectSpringConfigConsumerDriftFiles, } from './incremental/spring-con
 import { shadowCandidatesFor } from './incremental/shadow-candidates.js';
 import { shouldEscalateIncrementalWrite } from './incremental/escalation-gate.js';
 import { ftsTablesAmong, incrementalFtsTablesFromGraph, nodeTablesForIncrementalDelete, shouldPreservePersistedDerivedGraph, } from './incremental/derived-writeback.js';
+import { formatInvalidProcessDetectionOverride, processDetectionBudgetMismatch, resolveProcessDetectionBudget, toProcessDetectionStamp, uncertifyProcessDetectionStamp, } from './ingestion/process-detection-budget.js';
 import { NODE_TABLES } from './lbug/schema.js';
 import { loadParseCache, saveParseCache, pruneCache, PARSE_CACHE_VERSION, createColdParseRebuildDir, emptyParseCache, forgetCreatedParseCacheDir, } from '../storage/parse-cache.js';
 import { mergeStagedDurableParsedFileStore } from '../storage/parsedfile-store.js';
@@ -1370,12 +1371,28 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         log('Parser cache bypass requested; forcing a full rebuild so unchanged files are re-parsed.');
         options = { ...options, force: true };
     }
+    // Process-detection budget (#3313). Resolve CLI/options then env here so
+    // MCP/server jobs honor GITNEXUS_* without a CLI merge. Compare against
+    // the persisted stamp BEFORE the already-up-to-date fast path: a clean
+    // same-commit raise must re-detect flows rather than return the sampled
+    // index. Does NOT set force — incremental empty-diff + skip derived
+    // preserve is enough.
+    const processDetectionBudget = resolveProcessDetectionBudget({
+        maxProcesses: options.maxProcesses,
+        maxProcessBranching: options.maxProcessBranching,
+        maxProcessTraceDepth: options.maxProcessTraceDepth,
+        maxEntryPointCandidates: options.maxEntryPointCandidates,
+    }, process.env, (knob, raw) => {
+        log(formatInvalidProcessDetectionOverride(knob, raw));
+    });
+    const processDetectionMismatch = processDetectionBudgetMismatch(existingMeta?.processDetection, processDetectionBudget);
     // ── Early-return: already up to date ──────────────────────────────
     if (existingMeta &&
         !existingMeta.embeddingCheckpoint &&
         !options.force &&
         existingMeta.lastCommit === currentCommit &&
-        !ftsModeChanged) {
+        !ftsModeChanged &&
+        !processDetectionMismatch) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
             // For git repos, even if HEAD matches lastCommit, the working tree
@@ -1420,6 +1437,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             // later read on a host where it loads — which is a legitimate, common
             // state, and the invariant `analyzer-identity-cli.test.ts` pins.
             if (!dirty && !healUnregistered) {
+                const processDetectionStamp = existingMeta.processDetection ?? toProcessDetectionStamp(processDetectionBudget);
                 if (options.registryName) {
                     await registerRepo(repoPath, existingMeta, {
                         name: options.registryName,
@@ -1465,7 +1483,11 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     // documented Docker :ro workflow (#1549) — degrades to a warning.
                     try {
                         await adoptFlatBranchLabel(repoPath, branchLabel, storagePath);
-                        await saveMeta(metaDir, { ...existingMeta, branch: branchLabel });
+                        await saveMeta(metaDir, {
+                            ...existingMeta,
+                            branch: branchLabel,
+                            processDetection: processDetectionStamp,
+                        });
                     }
                     catch (err) {
                         // EACCES/EPERM also arise from ownership problems and transient
@@ -1478,12 +1500,26 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     // Discriminator-only restamp (flag↔env). `existingMeta` already
                     // carries the folded skipReason; persist it without a write plan.
                     try {
-                        await saveMeta(metaDir, existingMeta);
+                        await saveMeta(metaDir, {
+                            ...existingMeta,
+                            processDetection: processDetectionStamp,
+                        });
                     }
                     catch (err) {
                         log(`Warning: could not restamp the FTS skip reason (${formatMetaWriteFailureReason(err)}); will retry on the next run.`);
                     }
                 }
+                else if (!existingMeta.processDetection) {
+                    try {
+                        await saveMeta(metaDir, {
+                            ...existingMeta,
+                            processDetection: processDetectionStamp,
+                        });
+                    }
+                    catch (err) {
+                        log(`Warning: could not backfill the process-detection stamp (${formatMetaWriteFailureReason(err)}); will retry on the next run.`);
+                    }
+                }
                 await ensureGitNexusIgnored(repoPath, storagePath);
                 return {
                     // `resolveRepoIdentityRoot` collapses worktree roots to the
@@ -1645,6 +1681,16 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         }, {
             parseCache,
             workerPoolSize: options.workerPoolSize,
+            maxProcesses: processDetectionBudget.maxProcesses,
+            maxProcessBranching: processDetectionBudget.overridden.maxProcessBranching
+                ? processDetectionBudget.maxProcessBranching
+                : undefined,
+            maxProcessTraceDepth: processDetectionBudget.overridden.maxProcessTraceDepth
+                ? processDetectionBudget.maxProcessTraceDepth
+                : undefined,
+            maxEntryPointCandidates: processDetectionBudget.overridden.maxEntryPointCandidates
+                ? processDetectionBudget.maxEntryPointCandidates
+                : undefined,
             // CFG/PDG opt-in (#2081 M1). PipelineOptions.pdg fans out to the worker
             // build gate (workerData.pdg) and the scope-resolution emit gate.
             pdg: options.pdg === true,
@@ -1762,7 +1808,8 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
     const preserveDerivedLayer = skipDerivedGraphPhases &&
         isIncremental &&
         !!hashDiff &&
-        shouldPreservePersistedDerivedGraph(hashDiff);
+        shouldPreservePersistedDerivedGraph(hashDiff) &&
+        !processDetectionMismatch;
     if (skipDerivedGraphPhases && !preserveDerivedLayer) {
         progress('communities', 58, 'Detecting code communities and flows...');
         await pipelineResult.runDeferredDerivedPhases?.();
@@ -1836,17 +1883,21 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             `(skipping wipe + ${allFilePaths.length - hashDiff.toWrite.length} unchanged file rows preserved)`);
         // Set the dirty flag BEFORE any destructive DB mutation. Cleared on
         // success at the meta-save step. Scoped to this branch's meta.json.
-        const now = Date.now();
-        await saveMeta(metaDir, {
-            ...existingMeta,
-            incrementalInProgress: {
-                startedAt: now,
-                updatedAt: now,
-                phase: 'pre-write',
-                toWriteCount: hashDiff.toWrite.length,
-                directWriteCount: hashDiff.toWrite.length,
-            },
-        });
+        // POSIX atomic incremental mutates the copy, so a live dirty stamp would
+        // force-rebuild a healthy index after a crash before swap.
+        if (!atomicIncremental) {
+            const now = Date.now();
+            await saveMeta(metaDir, {
+                ...existingMeta,
+                incrementalInProgress: {
+                    startedAt: now,
+                    updatedAt: now,
+                    phase: 'pre-write',
+                    toWriteCount: hashDiff.toWrite.length,
+                    directWriteCount: hashDiff.toWrite.length,
+                },
+            });
+        }
         if (atomicIncremental) {
             // Stage the live index into the temp so the in-place delete/writeback
             // below mutates the COPY, and the end-of-run swap publishes it atomically.
@@ -2672,6 +2723,11 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 lastCommit: '',
                 indexedAt: new Date().toISOString(),
             };
+            // #3322: persist uncertified *before* CREATE_FTS_INDEX. Park keeps this
+            // stamp; it must not invent one on every FTS-only crash. Missing stamp +
+            // shipped defaults is a match, so a budget-mismatch derived rewrite that
+            // dies in FTS would otherwise recertify the rewritten Community/Process
+            // rows on a flagless retry.
             await saveMeta(metaDir, {
                 ...base,
                 incrementalInProgress: buildFtsDirtyStamp({
@@ -2679,6 +2735,11 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     writePlan: 'in-place',
                     checkpointSucceeded: boundaryCheckpointSucceeded,
                 }),
+                ...(processDetectionMismatch
+                    ? {
+                        processDetection: uncertifyProcessDetectionStamp(base.processDetection),
+                    }
+                    : {}),
             });
         }
         // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
@@ -3550,6 +3611,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             // stamp after an on→off flip; the next pdgModeMismatch then compares
             // off==off and incremental eligibility is restored.
             pdg: resolvePdgConfig(options),
+            processDetection: toProcessDetectionStamp(processDetectionBudget),
         };
         // Re-resolve at the commit boundary. Long analyses can overlap an npm
         // upgrade, rebuilt dist tree, or native dependency replacement; stamping

package/dist/storage/repo-meta.d.ts

@@ -607,6 +607,22 @@ export interface RepoMeta {
          */
         hasCallSummary?: boolean;
     };
+    /**
+     * The process-detection budget this index's Community/Process rows were
+     * built under (#3313). Compared on the next analyze so a budget-only
+     * config change re-detects flows without `--force`. `maxProcesses: null`
+     * means the dynamic `symbols / 10` formula. Absent on pre-#3313 metas:
+     * that absence matches default/dynamic knobs (backfill) and mismatches
+     * any explicit override.
+     */
+    processDetection?: {
+        maxProcesses: number | null;
+        maxProcessBranching: number;
+        maxProcessTraceDepth: number;
+        maxEntryPointCandidates: number;
+        /** Live Community/Process rows are not certified under this stamp (#3322). */
+        uncertified?: true;
+    };
 }
 /**
  * Resolve the configured storage path for a repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.16",
+  "version": "1.6.13-rc.17",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",