gitnexus 1.6.6-rc.103 → 1.6.6-rc.104

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

@@ -28,7 +28,7 @@ import { generateId } from '../../lib/utils.js';
 import { getLanguageFromFilename, SupportedLanguages } from '../../_shared/index.js';
 import { isRegistryPrimary } from './registry-primary-flag.js';
 import { isVerboseIngestionEnabled } from './utils/verbose.js';
-import { deferredCallFileSlowMs, deferredCallLogEveryN, getDeferredProfileDroppedCount, isDeferredResolutionProfileEnabled, logDeferredProfile, profileElapsedMs, resetDeferredProfileDroppedCount, startTimer, } from './utils/deferred-resolution-profile.js';
+import { ALWAYS_ON_SLOW_FILE_WARN_THROTTLE_MS, alwaysOnSlowFileWarnMs, deferredCallFileSlowMs, deferredCallLogEveryN, getDeferredProfileDroppedCount, isDeferredResolutionProfileEnabled, logDeferredProfile, profileElapsedMs, resetDeferredProfileDroppedCount, startTimer, } from './utils/deferred-resolution-profile.js';
 import { yieldToEventLoop } from './utils/event-loop.js';
 import { parseSourceSafe } from '../tree-sitter/safe-parse.js';
 import { CLASS_CONTAINER_TYPES, FUNCTION_NODE_TYPES, findEnclosingClassInfo, genericFuncName, inferFunctionLabel, } from './utils/ast-helpers.js';
@@ -2303,6 +2303,14 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
     const slowFileMs = profileCalls ? deferredCallFileSlowMs() : 0;
     const logEveryN = profileCalls ? deferredCallLogEveryN() : 0;
     let skippedRegistryPrimaryFiles = 0;
+    // Always-on slow-file watchdog (#1741). Independent of the verbose/profile
+    // gate above: even a plain `analyze` run surfaces ONE actionable warning
+    // when a single file's call resolution is pathologically slow — turning the
+    // silent "stuck at Resolving calls (N/M)" symptom into a named culprit.
+    // Throttled so a genuinely slow repo can't produce a warn storm.
+    const alwaysSlowFileMs = alwaysOnSlowFileWarnMs();
+    let lastSlowFileWarnAt = 0;
+    let suppressedSlowFileWarnings = 0;
     // Fresh dropped-log counter per analyze run — the module-private counter
     // in deferred-resolution-profile.ts is process-lived, so without a reset
     // here it would accumulate across consecutive analyze invocations in the
@@ -2314,12 +2322,16 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
     // denominator stays stable as the loop iterates. Otherwise `${totalFiles -
     // skippedRegistryPrimaryFiles}` drifts upward — files iterated before later
     // registry-primary skips have been seen carry an inflated denominator, and
-    // the ratio only self-corrects after every file has been classified. Pre-
-    // count runs only on the enabled path so the disabled path stays free of
-    // the extra Map iteration. Defaults to 0 on the disabled path; the live log
-    // gate is also disabled there, so the value is never read.
+    // the ratio only self-corrects after every file has been classified.
+    //
+    // Runs whenever its result will actually be read: on the profile path (the
+    // live deferred-profile log) OR when the always-on slow-file watchdog is
+    // active (#1741) — the watchdog's warning prints `${resolvedFiles}/${resolvedTotal}`
+    // unconditionally, so leaving resolvedTotal at 0 on a plain run produced a
+    // bogus "Resolved N/0 files" denominator on exactly the unprofiled runs the
+    // watchdog exists for. When both gates are off, skip the extra Map pass.
     let resolvedTotal = 0;
-    if (profileCalls) {
+    if (profileCalls || alwaysSlowFileMs > 0) {
         for (const filePath of byFile.keys()) {
             const lang = getLanguageFromFilename(filePath);
             if (!lang || !isRegistryPrimary(lang))
@@ -2341,6 +2353,9 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
         }
         resolvedFiles++;
         const tFile = startTimer(profileCalls);
+        // Always-on timer (cheap: one hrtime read) feeding the slow-file watchdog
+        // below. Distinct from `tFile`, which is null unless profiling is on.
+        const tFileAlways = alwaysSlowFileMs > 0 ? process.hrtime.bigint() : null;
         if (profileCalls && (resolvedFiles === 1 || resolvedFiles % logEveryN === 0)) {
             logDeferredProfile(`calls ${resolvedFiles}/${resolvedTotal} file=${filePath} sites=${calls.length}`);
         }
@@ -2455,6 +2470,27 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
                 logDeferredProfile(`slow file ${elapsed.toFixed(0)}ms path=${filePath} calls=${calls.length} lang=${fileLanguage ?? 'unknown'}`);
             }
         }
+        // Always-on slow-file watchdog (#1741) — fires regardless of verbose.
+        if (tFileAlways !== null) {
+            const elapsedAlways = profileElapsedMs(tFileAlways);
+            if (elapsedAlways >= alwaysSlowFileMs) {
+                const now = Date.now();
+                if (now - lastSlowFileWarnAt >= ALWAYS_ON_SLOW_FILE_WARN_THROTTLE_MS) {
+                    lastSlowFileWarnAt = now;
+                    const suppressedNote = suppressedSlowFileWarnings > 0
+                        ? ` (+${suppressedSlowFileWarnings} more slow files since the last warning)`
+                        : '';
+                    logger.warn(`⏳ Call resolution for ${filePath} took ${(elapsedAlways / 1000).toFixed(1)}s ` +
+                        `(${calls.length} call sites, ${fileLanguage ?? 'unknown'}). The run is not frozen — ` +
+                        `this file is unusually expensive to resolve. Resolved ${resolvedFiles}/${resolvedTotal} ` +
+                        `files so far.${suppressedNote} Pass -v for per-file deferred-resolution timing.`);
+                    suppressedSlowFileWarnings = 0;
+                }
+                else {
+                    suppressedSlowFileWarnings++;
+                }
+            }
+        }
     }
     if (profileCalls) {
         logDeferredProfile(`processCallsFromExtracted done: ${totalFiles} files, ${extractedCalls.length} call sites, skipped registry-primary files=${skippedRegistryPrimaryFiles}`);

package/dist/core/ingestion/pipeline-phases/parse-impl.d.ts

@@ -24,6 +24,29 @@ type ScannedFile = {
     size: number;
 };
 type ProgressFn = (progress: PipelineProgress) => void;
+/**
+ * Handle a worker-pool startup failure by FAILING FAST with the captured cause
+ * (#1741). The pool self-heals *transient* worker crashes on its own — a
+ * bounded, jittered startup restart loop (see worker-pool.ts) — so this is
+ * reached only when that self-heal is EXHAUSTED, or a deterministic crash-loop
+ * was detected, or the pool could not even be constructed. In every such case
+ * the workers genuinely cannot start.
+ *
+ * Rather than silently degrade to the ~10× slower sequential parser — which
+ * masked a worker-startup regression as a 2-hour "stuck" run in #1741 (rc99:
+ * the failure was a dropped `logger.warn` and an unbounded sequential grind) —
+ * GitNexus surfaces the real crash and aborts. An operator who genuinely wants
+ * sequential parsing asks for it explicitly with `--workers 0`.
+ *
+ * The decision is automatic: NO `--allow-sequential-fallback` or pool-sizing
+ * flag participates. The pool's own crash classification (`crashClass` on
+ * WorkerPoolInitializationError) only sharpens the message.
+ *
+ * @throws always — an actionable Error carrying the captured worker crash.
+ * @internal Exported for unit tests; production callers are the parse loop's
+ *           two worker-startup catch sites below.
+ */
+export declare function handleWorkerStartupFailure(err: Error): never;
 /**
  * Chunked parse + resolve loop.
  *

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -25,7 +25,7 @@ import { getLanguageFromFilename } from '../../../_shared/index.js';
 import { isRegistryPrimary } from '../registry-primary-flag.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isLanguageAvailable } from '../../tree-sitter/parser-loader.js';
-import { createWorkerPool, WorkerPoolInitializationError } from '../workers/worker-pool.js';
+import { createWorkerPool, workerPoolDisabledByEnv, WorkerPoolInitializationError, } from '../workers/worker-pool.js';
 import { extractFetchCallsFromFiles } from '../call-processor.js';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -66,6 +66,64 @@ function resolveChunkByteBudget(options) {
         return env;
     return DEFAULT_CHUNK_BYTE_BUDGET;
 }
+/**
+ * Handle a worker-pool startup failure by FAILING FAST with the captured cause
+ * (#1741). The pool self-heals *transient* worker crashes on its own — a
+ * bounded, jittered startup restart loop (see worker-pool.ts) — so this is
+ * reached only when that self-heal is EXHAUSTED, or a deterministic crash-loop
+ * was detected, or the pool could not even be constructed. In every such case
+ * the workers genuinely cannot start.
+ *
+ * Rather than silently degrade to the ~10× slower sequential parser — which
+ * masked a worker-startup regression as a 2-hour "stuck" run in #1741 (rc99:
+ * the failure was a dropped `logger.warn` and an unbounded sequential grind) —
+ * GitNexus surfaces the real crash and aborts. An operator who genuinely wants
+ * sequential parsing asks for it explicitly with `--workers 0`.
+ *
+ * The decision is automatic: NO `--allow-sequential-fallback` or pool-sizing
+ * flag participates. The pool's own crash classification (`crashClass` on
+ * WorkerPoolInitializationError) only sharpens the message.
+ *
+ * @throws always — an actionable Error carrying the captured worker crash.
+ * @internal Exported for unit tests; production callers are the parse loop's
+ *           two worker-startup catch sites below.
+ */
+export function handleWorkerStartupFailure(err) {
+    const isInit = err instanceof WorkerPoolInitializationError;
+    const readinessFailures = isInit ? err.readinessFailures : [];
+    const crashClass = isInit ? err.crashClass : undefined;
+    // Surface the real cause verbatim: readiness failures for an init crash, or
+    // the construction error message (e.g. "Worker script not found: …") when the
+    // pool never got to spawn workers.
+    const failureDetail = readinessFailures.length > 0
+        ? ` Underlying worker failure(s): ${readinessFailures.join(' | ')}`
+        : isInit
+            ? ''
+            : ` Underlying error: ${err.message}`;
+    // Always surface the real crash — never let a startup failure pass silently.
+    logger.error({ err: err.message, readinessFailures, crashClass }, 'Worker pool failed to start — workers could not start (bounded self-heal exhausted).');
+    const cause = crashClass === 'deterministic-startup'
+        ? `every worker crashed identically during startup (a deterministic ` +
+            `crash-loop — retrying cannot help), so the pool has no usable workers.`
+        : isInit
+            ? `workers exhausted the bounded startup retry budget without reporting ` +
+                `ready, so the pool has no usable workers.`
+            : `the worker pool could not be constructed.`;
+    // Class-aware fix hint: a missing/broken native binding is the likely cause
+    // when workers crashed during init, but it is the WRONG guess for a pool that
+    // never constructed (commonly a missing build / unresolvable worker path).
+    const fixHint = isInit
+        ? `Fix the worker startup failure shown above (often a missing/broken native ` +
+            `binding or a top-of-script import error in parse-worker).`
+        : `Fix the worker pool construction error shown above (commonly a missing ` +
+            `build, so dist/ has no parse-worker, or an unresolvable worker path).`;
+    throw new Error(`Worker pool failed to start: ${cause}${failureDetail}\n\n` +
+        `GitNexus will NOT silently fall back to the (much slower) sequential ` +
+        `parser and hide this crash — that masked a worker-startup regression as ` +
+        `a 2-hour "stuck" run in #1741. Options:\n` +
+        `  • ${fixHint}\n` +
+        `  • Re-run with --workers 0 to parse sequentially without the worker pool.`);
+}
 /**
  * Chunked parse + resolve loop.
  *
@@ -168,13 +226,26 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     // intentionally NOT created before parse-cache lookup: a warm-cache
     // all-hit run should replay cached worker output without loading
     // parse-worker.js or any tree-sitter/N-API native bindings.
+    // `--workers 0` (workerPoolSize === 0) and `GITNEXUS_WORKER_POOL_SIZE=0` both
+    // mean "no pool, parse sequentially". The env channel is consulted ONLY when
+    // no explicit `--workers <N>` was given, so an explicit positive size always
+    // wins over an ambient env=0 (#1741). Without this, env=0 built a size-0 pool
+    // that failed fast with a fabricated "retry budget exhausted" crash.
+    const envDisablesWorkers = options?.workerPoolSize === undefined && workerPoolDisabledByEnv();
+    const meetsWorkerThreshold = totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS;
+    // Log only when env=0 actually skips a pool we'd otherwise have used, so the
+    // undocumented (possibly accidental) env=0 case is observable instead of a
+    // silent degrade — small repos go sequential anyway and need no notice.
+    if (envDisablesWorkers && meetsWorkerThreshold) {
+        logger.warn('GITNEXUS_WORKER_POOL_SIZE=0 → parsing sequentially; unset it or pass --workers <N> to use the worker pool.');
+    }
     const shouldUseWorkers = !options?.skipWorkers &&
         options?.workerPoolSize !== 0 &&
-        (totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS);
+        !envDisablesWorkers &&
+        meetsWorkerThreshold;
     let workerPool;
-    let workerPoolDisabled = false;
     const getOrCreateWorkerPool = () => {
-        if (!shouldUseWorkers || workerPoolDisabled)
+        if (!shouldUseWorkers)
             return undefined;
         if (workerPool)
             return workerPool;
@@ -199,9 +270,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             return workerPool;
         }
         catch (err) {
-            workerPoolDisabled = true;
-            logger.warn({ err: err.message }, 'Worker pool creation failed, using sequential fallback:');
-            return undefined;
+            // Pool *construction* failed (e.g. the worker script is missing — a
+            // broken install). Fail fast with the cause rather than silently
+            // degrading to the slow sequential parser (#1741); `--workers 0` is the
+            // explicit opt-out for anyone who genuinely wants sequential parsing.
+            handleWorkerStartupFailure(err);
         }
     };
     let filesParsedSoFar = 0;
@@ -400,16 +473,15 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 catch (err) {
                     if (!(err instanceof WorkerPoolInitializationError))
                         throw err;
-                    logger.warn({
-                        err: err.message,
-                        readinessFailures: err.readinessFailures,
-                    }, 'Worker pool initialization failed, using sequential fallback:');
+                    // Every worker crashed during startup and the pool's bounded
+                    // self-heal (jittered restart, deterministic crash-loop detection —
+                    // see worker-pool.ts) was exhausted. Fail fast with the captured
+                    // cause rather than silently degrading to the ~10× slower sequential
+                    // parser, which masked this exact regression as a 2-hour "stuck" run
+                    // in #1741. The failed (zero-worker) pool is torn down by the outer
+                    // finally. `--workers 0` is the explicit opt-in to sequential.
                     rawResults.length = 0;
-                    workerPoolDisabled = true;
-                    const failedPool = workerPool;
-                    workerPool = undefined;
-                    await failedPool?.terminate().catch(() => undefined);
-                    chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, progressForChunk, undefined, undefined);
+                    handleWorkerStartupFailure(err); // always throws
                 }
                 // Persist the raw results for this chunk hash. Sequential path
                 // doesn't populate rawResults (it writes directly to graph), so

package/dist/core/ingestion/utils/deferred-resolution-profile.d.ts

@@ -10,12 +10,22 @@
  * because the UI progress bar updates every 100 files and intermediate
  * stages emit little to the log.
  */
+/** Min wall-clock gap between always-on slow-file warnings (throttle). */
+export declare const ALWAYS_ON_SLOW_FILE_WARN_THROTTLE_MS = 30000;
 /** True when deferred-stage timing / progress logs should emit. */
 export declare const isDeferredResolutionProfileEnabled: () => boolean;
 /** Log a call-resolution progress line every N files (finer when verbose). */
 export declare const deferredCallLogEveryN: () => number;
 /** Per-file call-resolution log threshold (ms). Lower default when verbose. */
 export declare const deferredCallFileSlowMs: () => number;
+/**
+ * Always-on per-file slow threshold (ms) for the `logger.warn` watchdog in
+ * `processCallsFromExtracted`. Unlike {@link deferredCallFileSlowMs} this is
+ * NOT gated on verbose/profile — it fires on every run. `0` (or a negative /
+ * non-finite override) disables the watchdog entirely. Override via
+ * `GITNEXUS_SLOW_FILE_WARN_MS`.
+ */
+export declare const alwaysOnSlowFileWarnMs: () => number;
 export declare const profileNow: () => bigint;
 export declare const profileElapsedMs: (start: bigint) => number;
 /**

package/dist/core/ingestion/utils/deferred-resolution-profile.js

@@ -19,6 +19,19 @@ const LOG_EVERY_N_VERBOSE = 10;
 const LOG_EVERY_N_PROFILE = 100;
 const DEFAULT_SLOW_MS_VERBOSE = 3_000;
 const DEFAULT_SLOW_MS = 5_000;
+/**
+ * Always-on (NOT gated on verbose/profile) threshold above which a single
+ * file's deferred call resolution earns a `logger.warn`. The verbose
+ * slow-file profile (above) only fires with `-v`/`GITNEXUS_PROFILE_DEFERRED`;
+ * a plain `analyze` run that hangs in "Resolving calls" (the #1741 symptom)
+ * gives the user a frozen progress bar and nothing in the log. This higher
+ * default (15s — never hit by a healthy file) turns that silence into one
+ * actionable line naming the expensive file. Override via
+ * `GITNEXUS_SLOW_FILE_WARN_MS`; the throttle in the caller bounds volume.
+ */
+const DEFAULT_ALWAYS_ON_SLOW_FILE_WARN_MS = 15_000;
+/** Min wall-clock gap between always-on slow-file warnings (throttle). */
+export const ALWAYS_ON_SLOW_FILE_WARN_THROTTLE_MS = 30_000;
 /** True when deferred-stage timing / progress logs should emit. */
 export const isDeferredResolutionProfileEnabled = () => isVerboseIngestionEnabled() || parseTruthyEnv(process.env.GITNEXUS_PROFILE_DEFERRED);
 /** Log a call-resolution progress line every N files (finer when verbose). */
@@ -35,6 +48,23 @@ export const deferredCallFileSlowMs = () => {
     }
     return isVerboseIngestionEnabled() ? DEFAULT_SLOW_MS_VERBOSE : DEFAULT_SLOW_MS;
 };
+/**
+ * Always-on per-file slow threshold (ms) for the `logger.warn` watchdog in
+ * `processCallsFromExtracted`. Unlike {@link deferredCallFileSlowMs} this is
+ * NOT gated on verbose/profile — it fires on every run. `0` (or a negative /
+ * non-finite override) disables the watchdog entirely. Override via
+ * `GITNEXUS_SLOW_FILE_WARN_MS`.
+ */
+export const alwaysOnSlowFileWarnMs = () => {
+    const raw = process.env.GITNEXUS_SLOW_FILE_WARN_MS;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        // 0 / negative / NaN → disabled. Use Number() not parseInt (see
+        // deferredCallFileSlowMs for the '1e9' prefix-parse hazard).
+        return Number.isFinite(n) && n > 0 ? n : 0;
+    }
+    return DEFAULT_ALWAYS_ON_SLOW_FILE_WARN_MS;
+};
 export const profileNow = () => process.hrtime.bigint();
 export const profileElapsedMs = (start) => Number(process.hrtime.bigint() - start) / 1e6;
 // Module-private counter for `[deferred-profile]` log lines the underlying

package/dist/core/ingestion/workers/parse-worker.js

@@ -1,4 +1,4 @@
-import { parentPort } from 'node:worker_threads';
+import { parentPort, threadId } from 'node:worker_threads';
 import Parser from 'tree-sitter';
 import JavaScript from 'tree-sitter-javascript';
 import TypeScript from 'tree-sitter-typescript';
@@ -49,6 +49,27 @@ import { extractTemplateArguments, templateArgumentsIdTag } from '../utils/templ
 import { extractParsedFile } from '../scope-extractor-bridge.js';
 import { extractLaravelRoutes } from '../route-extractors/laravel.js';
 import { logger } from '../../logger.js';
+// ── Bootstrap-stage diagnostics (#1741) ────────────────────────────────────
+// When GITNEXUS_WORKER_BOOTSTRAP=1 (or --verbose sets GITNEXUS_VERBOSE), each
+// worker reports its startup stage timings to stderr — which the pool tees
+// and captures (worker-pool.ts captureWorkerStderr). This makes a slow or
+// crashing startup diagnosable: you can see whether a worker reached
+// "grammars loaded", "ready sent", or never emitted a line at all (=> it
+// crashed in a native binding load before this code ran). The pool then
+// attaches whatever stderr it captured to its readiness-failure message,
+// so the operator sees the real cause instead of "did not report ready".
+const BOOTSTRAP_LOG = process.env.GITNEXUS_WORKER_BOOTSTRAP === '1' || process.env.GITNEXUS_VERBOSE === '1';
+const bootstrapStart = performance.now();
+const bootstrapLog = (stage) => {
+    if (!BOOTSTRAP_LOG)
+        return;
+    const ms = Math.round(performance.now() - bootstrapStart);
+    process.stderr.write(`[parse-worker bootstrap] thread=${threadId} ${stage} (+${ms}ms)\n`);
+};
+// First line we can emit: every static import above (tree-sitter native
+// bindings, language grammars, helper modules) has already resolved by the
+// time this module-body statement runs.
+bootstrapLog('imports + grammars loaded');
 // ============================================================================
 // Worker-local parser + language map
 // ============================================================================
@@ -1688,6 +1709,7 @@ const mergeResult = (target, src) => {
 // `WORKER_READY_TIMEOUT_MS` (5s), so emitting it AFTER all top-of-script
 // init (imports, native binding loads, type-env setup) completes is the
 // load-bearing signal that this worker is ready for dispatch.
+bootstrapLog('ready sent');
 parentPort.postMessage({ type: 'ready' });
 // Module-scope `TextDecoder` for sub-batch content. The pool sends each
 // file's content as a `Uint8Array` (zero-copy ArrayBuffer transfer); we
@@ -1713,7 +1735,12 @@ function decodeSubBatchFiles(files) {
         content: typeof f.content === 'string' ? f.content : sharedContentDecoder.decode(f.content),
     }));
 }
+let firstTaskLogged = false;
 parentPort.on('message', (msg) => {
+    if (!firstTaskLogged) {
+        firstTaskLogged = true;
+        bootstrapLog('first task received');
+    }
     try {
         // Sub-batch mode: { type: 'sub-batch', files: [...] }
         if (msg.type === 'sub-batch') {

package/dist/core/ingestion/workers/worker-pool.d.ts

@@ -149,10 +149,37 @@ export declare class WorkerPoolDispatchError extends Error {
     readonly quarantinedPaths: readonly string[];
     constructor(message: string, quarantinedPaths?: readonly string[]);
 }
+/**
+ * How a total worker-startup failure was classified by the pool's bounded
+ * self-heal (#1741). Lets the caller render an accurate cause without
+ * inspecting any operator flag:
+ *  - 'deterministic-startup': ≥2 fresh workers crashed with the SAME signature
+ *    before any reached ready (e.g. a missing native binding) — retrying is
+ *    futile, so the pool short-circuited fast.
+ *  - 'transient-exhausted': workers crashed variably and exhausted the bounded
+ *    startup retry budget without ever reaching ready.
+ */
+export type StartupCrashClass = 'deterministic-startup' | 'transient-exhausted';
 export declare class WorkerPoolInitializationError extends WorkerPoolDispatchError {
     readonly readinessFailures: readonly string[];
-    constructor(message: string, quarantinedPaths?: readonly string[], readinessFailures?: readonly string[]);
+    /** Pool's automatic classification of the startup crash (#1741). */
+    readonly crashClass: StartupCrashClass;
+    constructor(message: string, quarantinedPaths?: readonly string[], readinessFailures?: readonly string[], crashClass?: StartupCrashClass);
 }
+/**
+ * Normalize a worker crash message into a stable signature so two instances of
+ * the SAME deterministic crash compare equal while unrelated crashes don't.
+ * Strips hex addresses, digit runs (pids / line numbers / timestamps) and
+ * absolute paths. Best-effort by design: the deterministic classification's
+ * correctness rests on the STRUCTURAL signal (zero workers ever ready + startup
+ * budget exhausted), so an imperfect signature only changes how fast the
+ * short-circuit fires, never whether the pool ultimately fails fast. Even a
+ * stderr-less crash normalizes its "exited with code N" message to a stable
+ * key, so the empty-stderr timing case still groups.
+ *
+ * @internal Exported for unit tests; production callers are in this module.
+ */
+export declare function crashSignature(message: string): string;
 interface ResolvedWorkerPoolOptions {
     subBatchSize: number;
     subBatchMaxBytes: number;
@@ -164,12 +191,20 @@ interface ResolvedWorkerPoolOptions {
     consecutiveFailureThreshold: number;
 }
 export declare function resolveWorkerPoolOptions(options?: WorkerPoolOptions, poolSize?: number): ResolvedWorkerPoolOptions;
+/**
+ * True when the operator explicitly disabled the worker pool via
+ * `GITNEXUS_WORKER_POOL_SIZE=0` — the env-channel equivalent of `--workers 0`.
+ * The parse phase's `shouldUseWorkers` gate consults this (only when no
+ * explicit `--workers <N>` was passed) to route to sequential parsing instead
+ * of constructing a useless size-0 pool that would fail fast on a phantom
+ * crash (#1741). An explicit positive `--workers N` always wins.
+ */
+export declare function workerPoolDisabledByEnv(): boolean;
 /**
  * Resolve the auto-default worker pool size when no explicit `poolSize`
  * arg is passed to `createWorkerPool`. Precedence:
  *
- * 1. `GITNEXUS_WORKER_POOL_SIZE` env var (operator override; set by
- *    `--workers <N>` on the CLI).
+ * 1. `GITNEXUS_WORKER_POOL_SIZE` env var (operator override).
  * 2. `os.cpus().length - 1`, clamped to `[1, DEFAULT_POOL_SIZE_CAP]`.
  *
  * The cap exists because past ~16 workers the main-thread merge /

package/dist/core/ingestion/workers/worker-pool.js

@@ -79,10 +79,13 @@ export class WorkerPoolDispatchError extends Error {
 }
 export class WorkerPoolInitializationError extends WorkerPoolDispatchError {
     readinessFailures;
-    constructor(message, quarantinedPaths = [], readinessFailures = []) {
+    /** Pool's automatic classification of the startup crash (#1741). */
+    crashClass;
+    constructor(message, quarantinedPaths = [], readinessFailures = [], crashClass = 'transient-exhausted') {
         super(message, quarantinedPaths);
         this.name = 'WorkerPoolInitializationError';
         this.readinessFailures = readinessFailures;
+        this.crashClass = crashClass;
     }
 }
 /**
@@ -117,6 +120,89 @@ const WORKER_READY_TIMEOUT_MS = 5_000;
  * `GITNEXUS_WORKER_POOL_SIZE` or `--workers <N>`.
  */
 const DEFAULT_POOL_SIZE_CAP = 16;
+// ── Self-healing startup restart policy (#1741) ──────────────────────────────
+// A worker that crashes during top-of-script init (broken native binding, bad
+// import) is retried a BOUNDED number of times with jittered backoff before
+// its slot is dropped, so a transient blip self-heals with no operator
+// intervention. The bound is the whole point of #1741: recovery must never
+// become a silent, unbounded "stuck" run. When the budget is exhausted (or a
+// deterministic crash-loop is detected), the slot is dropped; if every slot is
+// dropped the first dispatch fails fast with the captured cause.
+/** Retries beyond the first attempt, per slot, to bring a startup worker ready. */
+const STARTUP_RESTART_BUDGET = 2;
+const RESTART_BACKOFF_BASE_MS = 250;
+const RESTART_BACKOFF_CAP_MS = 2_000;
+/**
+ * When this many freshly-spawned workers crash with the SAME crash signature
+ * before ANY worker reaches the `{type:'ready'}` handshake, the failure is
+ * deterministic (the #1741 missing-binding case: every worker prints a
+ * byte-identical native-binding stack). The pool stops retrying immediately
+ * instead of burning every slot's budget, and fails fast with the cause.
+ */
+const DETERMINISTIC_STARTUP_FINGERPRINT_THRESHOLD = 2;
+/**
+ * Capped exponential backoff with FULL jitter (AWS "Exponential Backoff And
+ * Jitter"): random(0, min(CAP, BASE·2^attempt)). Full jitter de-synchronizes
+ * the N workers that crash near-simultaneously on a shared startup fault so
+ * their respawns don't re-storm in lockstep (Google SRE thundering herd).
+ */
+function startupBackoffMs(attempt) {
+    const ceil = Math.min(RESTART_BACKOFF_CAP_MS, RESTART_BACKOFF_BASE_MS * 2 ** attempt);
+    return Math.floor(Math.random() * (ceil + 1));
+}
+/**
+ * Sleep used between startup self-heal retries. The timer is intentionally NOT
+ * `unref`'d: a pending retry is necessary work, so it must keep the event loop
+ * alive long enough to actually respawn — otherwise a pool whose only live work
+ * is a startup backoff could let the process exit mid-recovery (#1741). To
+ * avoid wedging shutdown, the timer registers a cancel function in `pending`;
+ * `terminate()` invokes those cancels to `clearTimeout` and resolve early, and
+ * a normally-fired timer removes its own cancel. `aborted()` is checked once up
+ * front; the CALLER re-checks after wake (it owns the terminated/deterministic
+ * decision) — this function does not itself re-evaluate abort on wake.
+ */
+function abortableSleep(ms, aborted, pending) {
+    return new Promise((resolve) => {
+        if (ms <= 0 || aborted()) {
+            resolve();
+            return;
+        }
+        // `cancel` is registered so terminate() can clear a pending backoff; it is
+        // also the timer's own callback, so a normally-fired sleep self-deregisters.
+        const cancel = () => {
+            clearTimeout(timer);
+            pending.delete(cancel);
+            resolve();
+        };
+        const timer = setTimeout(cancel, ms);
+        pending.add(cancel);
+    });
+}
+/**
+ * Normalize a worker crash message into a stable signature so two instances of
+ * the SAME deterministic crash compare equal while unrelated crashes don't.
+ * Strips hex addresses, digit runs (pids / line numbers / timestamps) and
+ * absolute paths. Best-effort by design: the deterministic classification's
+ * correctness rests on the STRUCTURAL signal (zero workers ever ready + startup
+ * budget exhausted), so an imperfect signature only changes how fast the
+ * short-circuit fires, never whether the pool ultimately fails fast. Even a
+ * stderr-less crash normalizes its "exited with code N" message to a stable
+ * key, so the empty-stderr timing case still groups.
+ *
+ * @internal Exported for unit tests; production callers are in this module.
+ */
+export function crashSignature(message) {
+    return (message
+        .replace(/0x[0-9a-fA-F]+/g, '0xADDR') // 0x-prefixed addresses
+        // Windows backslash paths (optional drive letter), e.g. C:\Users\ci\Temp\w-7f3a.js
+        .replace(/(?:[A-Za-z]:)?(?:\\[^\s\\'"]+)+/g, '\\PATH')
+        .replace(/(?:\/[^\s:'"]+)+/g, '/PATH') // POSIX paths
+        .replace(/\b[0-9a-fA-F]{6,}\b/g, 'HEX') // bare hex runs (ASLR addrs / backtrace tokens)
+        .replace(/[0-9]+/g, 'N') // pids / line numbers / exit codes / timestamps
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 300));
+}
 function positiveInteger(value) {
     const parsed = typeof value === 'string' ? Number(value) : value;
     return typeof parsed === 'number' && Number.isFinite(parsed) && parsed > 0
@@ -152,12 +238,38 @@ export function resolveWorkerPoolOptions(options = {}, poolSize) {
             Math.max(DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD_FLOOR, poolSize ?? 0),
     };
 }
+/**
+ * The pool size requested via the `GITNEXUS_WORKER_POOL_SIZE` env var, or
+ * `undefined` when unset, empty/whitespace, or invalid. Module-internal sizing
+ * reader consumed by {@link resolveAutoPoolSize} (the env override) and
+ * {@link workerPoolDisabledByEnv} (the sequential-routing gate). Reads only —
+ * never mutates `process.env`. Empty/whitespace is treated as *unset* (falls
+ * through to the auto formula), not as 0 — an empty assignment (`export
+ * GITNEXUS_WORKER_POOL_SIZE=`) is an accident, not a request for zero workers;
+ * only a literal `0` disables the pool.
+ */
+function envWorkerPoolSize() {
+    const raw = process.env.GITNEXUS_WORKER_POOL_SIZE;
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    return nonNegativeInteger(raw);
+}
+/**
+ * True when the operator explicitly disabled the worker pool via
+ * `GITNEXUS_WORKER_POOL_SIZE=0` — the env-channel equivalent of `--workers 0`.
+ * The parse phase's `shouldUseWorkers` gate consults this (only when no
+ * explicit `--workers <N>` was passed) to route to sequential parsing instead
+ * of constructing a useless size-0 pool that would fail fast on a phantom
+ * crash (#1741). An explicit positive `--workers N` always wins.
+ */
+export function workerPoolDisabledByEnv() {
+    return envWorkerPoolSize() === 0;
+}
 /**
  * Resolve the auto-default worker pool size when no explicit `poolSize`
  * arg is passed to `createWorkerPool`. Precedence:
  *
- * 1. `GITNEXUS_WORKER_POOL_SIZE` env var (operator override; set by
- *    `--workers <N>` on the CLI).
+ * 1. `GITNEXUS_WORKER_POOL_SIZE` env var (operator override).
  * 2. `os.cpus().length - 1`, clamped to `[1, DEFAULT_POOL_SIZE_CAP]`.
  *
  * The cap exists because past ~16 workers the main-thread merge /
@@ -170,7 +282,7 @@ export function resolveWorkerPoolOptions(options = {}, poolSize) {
  * on the env / default.
  */
 export function resolveAutoPoolSize() {
-    const envOverride = nonNegativeInteger(process.env.GITNEXUS_WORKER_POOL_SIZE);
+    const envOverride = envWorkerPoolSize();
     if (envOverride !== undefined)
         return envOverride;
     // Prefer os.availableParallelism (Node 18.14+) so cgroup CPU limits
@@ -184,6 +296,51 @@ export function resolveAutoPoolSize() {
     const cores = typeof os.availableParallelism === 'function' ? os.availableParallelism() : os.cpus().length;
     return Math.min(DEFAULT_POOL_SIZE_CAP, Math.max(1, cores - 1));
 }
+/**
+ * Max characters of a worker's stderr retained for crash diagnostics. A
+ * native-binding load failure or a top-of-script throw prints a stack to
+ * stderr; we keep the tail so `waitForWorkerReady` can attach the real
+ * reason to its rejection instead of the generic "did not report ready".
+ */
+const WORKER_STDERR_TAIL_LIMIT = 4000;
+/**
+ * Per-worker captured stderr tail. Populated only for workers spawned with
+ * `{ stderr: true }` (the production factory below). Test-injected workers
+ * via `workerFactory` typically inherit the parent's stderr and have no
+ * `worker.stderr` stream — those are simply skipped (empty tail). A WeakMap
+ * so the buffer is released when the worker is GC'd.
+ */
+const workerStderrTails = new WeakMap();
+/**
+ * Tee a worker's stderr into a bounded in-memory tail (for surfacing the
+ * real crash on a startup failure) while still mirroring it to the parent
+ * process's stderr — preserving the live-diagnostics behavior workers had
+ * when they inherited stderr, before `{ stderr: true }` redirected it to a
+ * stream. No-op when the worker has no `stderr` stream (test factories).
+ */
+function captureWorkerStderr(worker) {
+    const stream = worker.stderr;
+    if (!stream)
+        return;
+    const buf = { text: '' };
+    workerStderrTails.set(worker, buf);
+    stream.on('data', (chunk) => {
+        const s = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        process.stderr.write(s);
+        buf.text = (buf.text + s).slice(-WORKER_STDERR_TAIL_LIMIT);
+    });
+    // A stderr stream error must never crash the pool.
+    stream.on('error', () => undefined);
+}
+/** Captured stderr tail for a worker, trimmed; '' when nothing was captured. */
+function workerStderrTail(worker) {
+    return workerStderrTails.get(worker)?.text.trim() ?? '';
+}
+/** Append the worker's captured stderr to a readiness-failure message. */
+function withStderr(worker, message) {
+    const tail = workerStderrTail(worker);
+    return tail ? `${message}. Worker stderr:\n${tail}` : message;
+}
 /**
  * Wait for a freshly-spawned replacement worker to emit the
  * `{type:'ready'}` handshake from `parse-worker.ts` before treating its
@@ -220,22 +377,24 @@ function waitForWorkerReady(worker) {
         };
         const onError = (err) => {
             cleanup();
-            reject(err);
+            // The 'error' event carries the real top-of-script exception; enrich it
+            // with the worker's stderr tail (native-binding stacks land there).
+            reject(new Error(withStderr(worker, err.message)));
         };
         const onExit = (code) => {
             cleanup();
-            reject(new Error(`Replacement worker exited with code ${code} before reporting ready`));
+            reject(new Error(withStderr(worker, `Replacement worker exited with code ${code} before reporting ready`)));
         };
         const onMessageError = (err) => {
             cleanup();
-            reject(new Error(`Replacement worker emitted messageerror before reporting ready: ${err.message}`));
+            reject(new Error(withStderr(worker, `Replacement worker emitted messageerror before reporting ready: ${err.message}`)));
         };
         // `timer` is declared after `cleanup` so the cleanup closure can reference
         // it. The const is reached before any handler attaches below, so no TDZ
         // access can fire from the listeners.
         const timer = setTimeout(() => {
             cleanup();
-            reject(new Error(`Replacement worker did not report ready within ${WORKER_READY_TIMEOUT_MS}ms — likely crashed during top-of-script init`));
+            reject(new Error(withStderr(worker, `Replacement worker did not report ready within ${WORKER_READY_TIMEOUT_MS}ms — likely crashed during top-of-script init`)));
         }, WORKER_READY_TIMEOUT_MS);
         worker.on('message', onMessage);
         worker.once('error', onError);
@@ -340,7 +499,18 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
     }
     const size = poolSize ?? resolveAutoPoolSize();
     const poolOptions = resolveWorkerPoolOptions(options, size);
-    const spawnWorker = options?.workerFactory ?? ((url) => new Worker(url));
+    // Production factory spawns with `{ stderr: true }` so a worker's crash
+    // output is redirected to a `worker.stderr` stream we can tee + capture
+    // (see captureWorkerStderr) and attach to readiness-failure messages —
+    // instead of the generic "did not report ready" that hid the real cause
+    // in #1741. Test factories (workerFactory) are used verbatim.
+    const spawnWorker = options?.workerFactory ?? ((url) => new Worker(url, { stderr: true }));
+    /** Spawn + wire stderr capture in one step (used by all spawn sites). */
+    const spawnAndCapture = (url) => {
+        const worker = spawnWorker(url);
+        captureWorkerStderr(worker);
+        return worker;
+    };
     const workers = new Array(size);
     const retiredWorkers = new Set();
     const respawnCount = new Array(size).fill(0);
@@ -369,6 +539,9 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
     const slotGenerations = new Array(size).fill(0);
     let poolBroken = false;
     let poolFailure;
+    // Set by `terminate()` (below). Also read by the self-healing startup loop so
+    // a terminate during startup aborts pending backoff/retries (#1741).
+    let terminated = false;
     const terminateTrackedWorkers = async (liveWorkers) => {
         const retired = Array.from(retiredWorkers);
         await Promise.all([
@@ -378,41 +551,96 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
         retiredWorkers.clear();
     };
     for (let i = 0; i < size; i++) {
-        workers[i] = spawnWorker(workerUrl);
+        workers[i] = spawnAndCapture(workerUrl);
         activeSlots.add(i);
     }
-    // Symmetrize the readiness gate across initial and replacement spawn
-    // paths. `replaceWorker` already awaits `waitForWorkerReady` per
-    // replacement so an init-crashing worker is dropped before dispatch
-    // sees it. The initial-spawn loop above didn't — a worker whose
-    // top-of-script init crashes (failed tree-sitter native binding,
-    // missing dependency) would only be noticed at the first dispatch's
-    // 30s idle timeout, vs the 5s WORKER_READY_TIMEOUT_MS bound that
-    // replacements enjoy.
+    // ── Self-healing startup readiness (#1741) ────────────────────────────────
+    // Bring every initial slot to readiness with a BOUNDED, jittered retry loop
+    // instead of dropping it on the first crash. This symmetrizes the gate with
+    // the runtime `replaceWorker` path (which already respawns a crashed slot),
+    // and adds genuine self-healing at startup:
     //
-    // The promise below settles every initial slot in parallel and drops
-    // unready slots from `activeSlots` before any dispatch can fire.
-    // `dispatch` awaits it via `initialReadyGate` on first invocation.
-    // Wrapped in a single `Promise.allSettled` so a slow worker doesn't
-    // block ready workers from being usable — first dispatch waits for
-    // all slots' verdicts (good or bad).
-    const initialReadyGate = Promise.allSettled(workers.map(async (w, i) => {
-        if (!w)
-            return;
-        try {
-            await waitForWorkerReady(w);
-        }
-        catch (err) {
-            initialReadinessFailures.push(err instanceof Error ? err.message : String(err));
-            logger.warn({
-                workerIndex: i,
-                err: err instanceof Error ? err.message : String(err),
-            }, `Worker ${i} did not report ready on initial spawn; dropping slot.`);
-            await w.terminate().catch(() => undefined);
-            workers[i] = undefined;
-            activeSlots.delete(i);
+    //  - TRANSIENT crash (a one-off OS hiccup / fork throttle): the slot is
+    //    respawned after jittered backoff and retried, up to STARTUP_RESTART_BUDGET
+    //    — so a blip heals itself with no operator intervention.
+    //  - DETERMINISTIC crash-loop (every worker dies with the SAME signature
+    //    before any reaches ready — the #1741 missing-binding case): detected via
+    //    `crashSignature` and short-circuited immediately, so the pool gives up in
+    //    ~1s rather than burning every slot's budget.
+    //
+    // When the loop exhausts, the slot is dropped from `activeSlots`. If EVERY
+    // slot is dropped, the first dispatch throws WorkerPoolInitializationError
+    // carrying the captured crash cause + classification — never a silent hang.
+    // Correctness of the deterministic short-circuit rests on the STRUCTURAL
+    // signal (zero workers ever ready + budget exhausted), not on signature
+    // matching alone: a missed match only costs a few seconds of extra retrying.
+    // Deterministic crash-loop detection (#1741). A crash counts toward
+    // "deterministic" ONLY after its signature reproduces across a respawn on the
+    // same slot — so every slot is guaranteed at least one self-heal attempt and
+    // a simultaneous attempt-0 crash storm (e.g. transient `spawn EAGAIN` under
+    // fork pressure) cannot be misclassified as deterministic. We short-circuit
+    // once enough DISTINCT slots have each reproduced: ≥2 normally, or 1 for a
+    // size-1 pool. Until then the structural floor (every slot exhausts its
+    // budget) still bounds the worst case, so a missed match only costs retries.
+    const lastStartupSignature = new Map();
+    const reproducedStartupSlots = new Set();
+    const deterministicSlotThreshold = Math.min(DETERMINISTIC_STARTUP_FINGERPRINT_THRESHOLD, size);
+    let deterministicStartupDetected = false;
+    let anyWorkerReachedReady = false;
+    // Cancel functions for in-flight startup backoffs (see abortableSleep). The
+    // backoff timer is ref'd so a retry actually runs; terminate() invokes these
+    // to clear pending backoffs and resolve their sleeps so the slot loops wake,
+    // see `terminated`, and give up — instead of the process staying pinned for
+    // the backoff cap after terminate (#1741).
+    const pendingStartupTimers = new Set();
+    const bringSlotReady = async (i) => {
+        for (let attempt = 0;; attempt++) {
+            const worker = workers[i];
+            if (!worker)
+                return; // terminated mid-startup
+            try {
+                await waitForWorkerReady(worker);
+                anyWorkerReachedReady = true;
+                return; // ready — slot stays in activeSlots
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                const sig = crashSignature(msg);
+                // Same signature as this slot's previous attempt => it survived a
+                // respawn, so retrying this slot is futile. (First crash has no prior
+                // signature, so attempt 0 never counts — every slot self-heals once.)
+                if (lastStartupSignature.get(i) === sig)
+                    reproducedStartupSlots.add(i);
+                lastStartupSignature.set(i, sig);
+                if (!anyWorkerReachedReady && reproducedStartupSlots.size >= deterministicSlotThreshold) {
+                    deterministicStartupDetected = true;
+                }
+                await worker.terminate().catch(() => undefined);
+                workers[i] = undefined;
+                const giveUp = terminated || deterministicStartupDetected || attempt >= STARTUP_RESTART_BUDGET;
+                if (giveUp) {
+                    initialReadinessFailures.push(msg);
+                    activeSlots.delete(i);
+                    logger.warn({ workerIndex: i, attempt, err: msg, deterministic: deterministicStartupDetected }, deterministicStartupDetected
+                        ? `Worker ${i} hit a deterministic startup crash-loop; dropping slot without further retries.`
+                        : `Worker ${i} did not report ready after ${attempt + 1} attempt(s); dropping slot.`);
+                    return;
+                }
+                // Transient: jittered backoff, then respawn the slot and retry.
+                await abortableSleep(startupBackoffMs(attempt), () => terminated || deterministicStartupDetected, pendingStartupTimers);
+                if (terminated || deterministicStartupDetected) {
+                    initialReadinessFailures.push(msg);
+                    activeSlots.delete(i);
+                    return;
+                }
+                logger.warn({ workerIndex: i, attempt: attempt + 1 }, `Worker ${i} crashed during startup; respawning slot (self-heal attempt ${attempt + 1}/${STARTUP_RESTART_BUDGET}).`);
+                workers[i] = spawnAndCapture(workerUrl);
+            }
         }
-    })).then(() => undefined);
+    };
+    // First dispatch awaits this; it settles every slot's bounded retry loop in
+    // parallel and drops the unrecoverable ones before any dispatch can fire.
+    const initialReadyGate = Promise.allSettled(workers.map((_, i) => bringSlotReady(i))).then(() => undefined);
     const dispatch = async (items, onProgress) => {
         // Await the initial-spawn readiness gate (F13). On first dispatch
         // this blocks for up to WORKER_READY_TIMEOUT_MS while every initial
@@ -434,7 +662,13 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
             const detail = initialReadinessFailures.length > 0
                 ? ` after initial ready handshake: ${initialReadinessFailures.join('; ')}`
                 : '';
-            throw new WorkerPoolInitializationError(`Worker pool has no active workers${detail}`, [], initialReadinessFailures);
+            // The bounded self-heal exhausted (or short-circuited a deterministic
+            // crash-loop). Classify automatically so the caller renders the real
+            // cause without consulting any operator flag (#1741).
+            const crashClass = deterministicStartupDetected
+                ? 'deterministic-startup'
+                : 'transient-exhausted';
+            throw new WorkerPoolInitializationError(`Worker pool has no active workers${detail}`, [], initialReadinessFailures, crashClass);
         }
         // Layer 3: filter out quarantined paths so a known-bad file never reaches
         // a worker again this pool lifetime. The caller queries
@@ -549,7 +783,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                 await removeWorkerFromSlot(workerIndex, mode, reason);
                 if (stopped)
                     return false;
-                const replacement = spawnWorker(workerUrl);
+                const replacement = spawnAndCapture(workerUrl);
                 try {
                     await waitForWorkerReady(replacement);
                 }
@@ -1165,9 +1399,13 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                 runWorker(slotIndex);
         });
     };
-    let terminated = false;
     const terminate = async () => {
         terminated = true;
+        // Cancel any in-flight startup backoff so its ref'd timer doesn't keep the
+        // event loop alive after terminate; each cancel resolves the awaiting sleep
+        // and the slot loop then sees `terminated` and gives up (#1741).
+        for (const cancel of [...pendingStartupTimers])
+            cancel();
         // `.catch(() => undefined)` per-worker matches every other terminate
         // site in this file. Without it, a hung/OOM-killed worker's terminate
         // rejection escapes `Promise.all` and replaces the original pipeline
@@ -1190,6 +1428,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
             quarantined: quarantine.size,
             poolBroken,
             terminated,
+            pendingStartupTimers: pendingStartupTimers.size,
             slotGenerations: slotGenerations.slice(),
         }),
     };

package/dist/core/run-analyze.js

@@ -296,7 +296,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             ? `${p.message || phaseLabel} (${p.detail})`
             : p.message || phaseLabel;
         progress(p.phase, scaled, message);
-    }, { parseCache, workerPoolSize: options.workerPoolSize });
+    }, {
+        parseCache,
+        workerPoolSize: options.workerPoolSize,
+    });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('lbug', 60, 'Loading into LadybugDB...');
     // Compute current per-file content hashes from the pipeline's File nodes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.103",
+  "version": "1.6.6-rc.104",
   "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",