gitnexus 1.6.6-rc.30 → 1.6.6-rc.31

package/dist/cli/analyze.js

@@ -8,7 +8,7 @@
  * skill generation (--skills), summary output, and process.exit().
  */
 import path from 'path';
-import { execFileSync } from 'child_process';
+import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
@@ -29,6 +29,7 @@ import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
 // previous behaviour silently swallowed stack traces and made #1169
 // indistinguishable from a no-op success on Windows.
 const realStderrWrite = process.stderr.write.bind(process.stderr);
+const realStdoutWrite = process.stdout.write.bind(process.stdout);
 const writeFatalToStderr = (label, err) => {
     const isErr = err instanceof Error;
     const message = isErr ? err.message : String(err);
@@ -67,14 +68,212 @@ const HEAP_FLAG = `--max-old-space-size=${RESPAWN_HEAP_MB}`;
 /** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
 const STACK_KB = 4096;
 const STACK_FLAG = `--stack-size=${STACK_KB}`;
+const RESPAWN_OUTPUT_TAIL_CHARS = 1024 * 1024;
+const RESPAWN_PROGRESS_ENV = 'GITNEXUS_RESPAWN_PROGRESS_TTY';
+const terminalColumns = () => {
+    const parsed = Number(process.env.COLUMNS);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 80;
+};
+const ANSI_ESCAPE_PATTERN = /\x1B(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\)|[PX^_][\s\S]*?\x1B\\|[78]|[@-Z\\-_])/y;
+const splitGraphemes = (text) => {
+    const Segmenter = Intl.Segmenter;
+    if (Segmenter) {
+        return Array.from(new Segmenter(undefined, { granularity: 'grapheme' }).segment(text), (s) => s.segment);
+    }
+    return Array.from(text);
+};
+const isZeroWidthCodePoint = (codePoint) => codePoint === 0x200d ||
+    (codePoint >= 0x0300 && codePoint <= 0x036f) ||
+    (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+    (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+    (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+    (codePoint >= 0xfe00 && codePoint <= 0xfe0f) ||
+    (codePoint >= 0xfe20 && codePoint <= 0xfe2f);
+const isWideCodePoint = (codePoint) => codePoint >= 0x1100 &&
+    (codePoint <= 0x115f ||
+        codePoint === 0x2329 ||
+        codePoint === 0x232a ||
+        (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+        (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+        (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+        (codePoint >= 0x1f300 && codePoint <= 0x1faff) ||
+        (codePoint >= 0x20000 && codePoint <= 0x3fffd));
+const visibleColumns = (text) => {
+    let columns = 0;
+    for (const char of Array.from(text)) {
+        const codePoint = char.codePointAt(0);
+        if (codePoint === undefined || isZeroWidthCodePoint(codePoint))
+            continue;
+        columns += isWideCodePoint(codePoint) ? 2 : 1;
+    }
+    return columns;
+};
+const readAnsiEscapeAt = (text, index) => {
+    ANSI_ESCAPE_PATTERN.lastIndex = index;
+    return ANSI_ESCAPE_PATTERN.exec(text)?.[0];
+};
+const truncateAnsiToColumns = (text, maxColumns) => {
+    if (!Number.isFinite(maxColumns) || maxColumns <= 0)
+        return '';
+    let output = '';
+    let columns = 0;
+    let index = 0;
+    while (index < text.length) {
+        const escape = readAnsiEscapeAt(text, index);
+        if (escape) {
+            output += escape;
+            index += escape.length;
+            continue;
+        }
+        const nextEscapeIndex = text.indexOf('\x1B', index);
+        const plainEnd = nextEscapeIndex === -1 ? text.length : nextEscapeIndex;
+        const plainText = text.slice(index, plainEnd);
+        for (const segment of splitGraphemes(plainText)) {
+            const width = visibleColumns(segment);
+            if (width > 0 && columns + width > maxColumns)
+                return output;
+            output += segment;
+            columns += width;
+        }
+        index = plainEnd;
+    }
+    return output;
+};
+const createAnsiPipeTerminal = (stream) => {
+    let linewrap = true;
+    let dy = 0;
+    const write = (s) => {
+        stream.write(s);
+    };
+    const moveVertical = (delta) => {
+        if (delta > 0)
+            write(`\x1B[${delta}B`);
+        else if (delta < 0)
+            write(`\x1B[${Math.abs(delta)}A`);
+    };
+    return {
+        cursorSave: () => write('\x1B7'),
+        cursorRestore: () => write('\x1B8'),
+        cursor: (enabled) => write(enabled ? '\x1B[?25h' : '\x1B[?25l'),
+        lineWrapping: (enabled) => {
+            linewrap = enabled;
+            write(enabled ? '\x1B[?7h' : '\x1B[?7l');
+        },
+        cursorTo: (x = null, y = null) => {
+            if (typeof y === 'number' && typeof x === 'number') {
+                write(`\x1B[${y + 1};${x + 1}H`);
+                return;
+            }
+            if (typeof x === 'number') {
+                write(x === 0 ? '\r' : `\x1B[${x + 1}G`);
+            }
+        },
+        cursorRelative: (dx = null, nextDy = null) => {
+            if (typeof dx === 'number' && dx !== 0) {
+                write(dx > 0 ? `\x1B[${dx}C` : `\x1B[${Math.abs(dx)}D`);
+            }
+            if (typeof nextDy === 'number' && nextDy !== 0) {
+                dy += nextDy;
+                moveVertical(nextDy);
+            }
+        },
+        cursorRelativeReset: () => {
+            moveVertical(-dy);
+            write('\r');
+            dy = 0;
+        },
+        clearRight: () => write('\x1B[0K'),
+        clearLine: () => write('\x1B[2K'),
+        clearBottom: () => write('\x1B[0J'),
+        newline: () => {
+            write('\n');
+            dy++;
+        },
+        write: (s, rawWrite = false) => {
+            const width = terminalColumns();
+            write(linewrap && rawWrite === false ? truncateAnsiToColumns(s, width) : s);
+        },
+        isTTY: () => true,
+        getWidth: terminalColumns,
+    };
+};
+const shouldBridgeRespawnProgressTty = () => process.stderr.isTTY === true || process.stdout.isTTY === true;
+const appendOutputTail = (tail, chunk) => {
+    const text = Buffer.isBuffer(chunk)
+        ? chunk.toString('utf8')
+        : typeof chunk === 'string'
+            ? chunk
+            : String(chunk ?? '');
+    if (!text)
+        return tail;
+    const next = tail + text;
+    return next.length > RESPAWN_OUTPUT_TAIL_CHARS ? next.slice(-RESPAWN_OUTPUT_TAIL_CHARS) : next;
+};
+/**
+ * Run the respawned analyzer while teeing child output through to the parent
+ * and keeping a bounded tail for crash classification.
+ *
+ * `execFileSync(..., { stdio: 'inherit' })` preserved live progress but hid
+ * stderr/stdout from the parent on abnormal exits. That made every
+ * SIGABRT/status-134 child look like an output-less V8 heap OOM, even when the
+ * terminal had already shown a native crash such as
+ * `libc++abi: ... Napi::Error`. Piped streams plus an explicit tee keeps the UX
+ * and gives `childProcessLikelyOom` the evidence it needs.
+ */
+const runRespawnedAnalyze = (args, env) => new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (exit) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve(exit);
+    };
+    const child = spawn(process.execPath, [...args], {
+        stdio: ['inherit', 'pipe', 'pipe'],
+        env,
+    });
+    child.stdout?.on('data', (chunk) => {
+        stdout = appendOutputTail(stdout, chunk);
+        realStdoutWrite(chunk);
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderr = appendOutputTail(stderr, chunk);
+        realStderrWrite(chunk);
+    });
+    child.on('error', (err) => {
+        finish({
+            status: 1,
+            signal: null,
+            stdout,
+            stderr,
+            message: err instanceof Error ? err.message : String(err),
+        });
+    });
+    child.on('close', (status, signal) => {
+        finish({
+            status,
+            signal,
+            stdout,
+            stderr,
+            message: `Command failed: ${process.execPath} ${args.join(' ')}`,
+        });
+    });
+});
 /**
  * Heuristic for "child re-exec likely died from V8 OOM".
  *
- * Platform-independent detection is best-effort: V8/Node usually emit
- * stable heap-exhaustion phrases in stderr/message across Linux/macOS/Windows
- * (for example "JavaScript heap out of memory" or "Reached heap limit"),
- * while some environments only expose status/signal (e.g. 134/SIGABRT).
- * We combine both text signatures and process-exit signatures.
+ * Platform-independent detection is best-effort: V8/Node usually emit stable
+ * heap-exhaustion phrases in stderr/message across Linux/macOS/Windows (for
+ * example "JavaScript heap out of memory" or "Reached heap limit"). When the
+ * child produced no output at all, we still treat status 134/SIGABRT as likely
+ * heap OOM. If stderr/stdout contains a native crash diagnostic, the output
+ * evidence wins and we do not print heap guidance.
  */
 const childProcessLikelyOom = (err) => {
     if (!err || typeof err !== 'object')
@@ -97,6 +296,23 @@ const childProcessLikelyOom = (err) => {
         return false;
     return e.status === 134 || e.signal === 'SIGABRT';
 };
+const childProcessLikelyNativeAbort = (err) => {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    const hasNativeAbortSignature = (v) => {
+        const text = (Buffer.isBuffer(v) ? v.toString('utf8') : typeof v === 'string' ? v : '').toLowerCase();
+        if (!text)
+            return false;
+        return (text.includes('napi::error') ||
+            text.includes('libc++abi: terminating') ||
+            text.includes('abort trap') ||
+            text.includes('native stack') ||
+            text.includes('native worker') ||
+            text.includes('native binding'));
+    };
+    return [e.message, e.stderr, e.stdout].some((v) => hasNativeAbortSignature(v));
+};
 const forceHeapOOMForTestIfEnabled = () => {
     if (process.env.GITNEXUS_TEST_FORCE_HEAP_OOM !== '1')
         return;
@@ -107,7 +323,7 @@ const forceHeapOOMForTestIfEnabled = () => {
         chunks.push('x'.repeat(1024 * 1024));
 };
 /** Re-exec the process with a 16GB heap and larger stack if we're currently below that. */
-function ensureHeap() {
+async function ensureHeap() {
     const nodeOpts = process.env.NODE_OPTIONS || '';
     if (nodeOpts.includes('--max-old-space-size'))
         return false;
@@ -119,23 +335,30 @@ function ensureHeap() {
     const cliFlags = [HEAP_FLAG];
     if (!nodeOpts.includes('--stack-size'))
         cliFlags.push(STACK_FLAG);
-    try {
-        execFileSync(process.execPath, [...cliFlags, ...process.argv.slice(1)], {
-            stdio: 'inherit',
-            env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
-        });
-    }
-    catch (e) {
-        if (childProcessLikelyOom(e)) {
+    const childArgs = [...cliFlags, ...process.argv.slice(1)];
+    const childEnv = {
+        ...process.env,
+        NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim(),
+    };
+    if (shouldBridgeRespawnProgressTty())
+        childEnv[RESPAWN_PROGRESS_ENV] = '1';
+    const childExit = await runRespawnedAnalyze(childArgs, childEnv);
+    if (childExit.status !== 0 || childExit.signal) {
+        if (childProcessLikelyOom(childExit)) {
             cliError(`  Analysis likely ran out of memory.\n` +
                 `  Retry with a larger heap if your machine allows it:\n` +
                 `    NODE_OPTIONS="--max-old-space-size=24576" gitnexus analyze [your-args]\n` +
                 `    (Windows: set NODE_OPTIONS=--max-old-space-size=24576 && gitnexus analyze [your-args])\n` +
                 `  If this persists, it may be a native crash unrelated to heap size.\n`, { recoveryHint: 'heap-oom-respawn' });
         }
-        const status = typeof e === 'object' && e !== null && 'status' in e && typeof e.status === 'number'
-            ? e.status
-            : 1;
+        else if (childProcessLikelyNativeAbort(childExit)) {
+            cliError(`  Analysis aborted in a native worker or native binding path.\n` +
+                `  Try one of these recovery paths:\n` +
+                `    gitnexus analyze --workers 0\n` +
+                `    npm uninstall -g gitnexus && npm install -g gitnexus@latest\n` +
+                `    Use Node 22 LTS if you are on a newer non-LTS runtime.\n`, { recoveryHint: 'native-worker-abort' });
+        }
+        const status = typeof childExit.status === 'number' && childExit.status !== 0 ? childExit.status : 1;
         process.exitCode = status;
     }
     return true;
@@ -157,6 +380,7 @@ const ANALYZE_CLI_ENV_KEYS = [
     'GITNEXUS_EMBEDDING_BATCH_SIZE',
     'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
     'GITNEXUS_EMBEDDING_DEVICE',
+    'GITNEXUS_ANALYZE_PROGRESS_ACTIVE',
 ];
 const snapshotAnalyzeEnv = () => {
     const snap = {};
@@ -188,7 +412,7 @@ const restoreAnalyzeEnv = (snap) => {
  */
 export const shouldGenerateCommunitySkillFiles = (options, pipelineResult) => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
 export const analyzeCommand = async (inputPath, options) => {
-    if (ensureHeap())
+    if (await ensureHeap())
         return;
     forceHeapOOMForTestIfEnabled();
     // Install fatal handlers immediately after re-exec resolution so any
@@ -362,7 +586,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
         console.log(`${maxFileSizeBanner}\n`);
     }
     // ── CLI progress bar setup ─────────────────────────────────────────
-    const bar = new cliProgress.SingleBar({
+    const barOptions = {
         format: '  {bar} {percentage}% | {phase}',
         barCompleteChar: '\u2588',
         barIncompleteChar: '\u2591',
@@ -371,7 +595,16 @@ const analyzeCommandImpl = async (inputPath, options) => {
         autopadding: true,
         clearOnComplete: false,
         stopOnComplete: false,
-    }, cliProgress.Presets.shades_grey);
+    };
+    if (process.env[RESPAWN_PROGRESS_ENV] === '1' && process.stderr.isTTY !== true) {
+        // Heap respawn pipes stderr so the parent can classify native/OOM crashes.
+        // The parent was a real TTY when it opted into this env var, so forward
+        // ANSI cursor controls through the pipe instead of cli-progress' non-TTY
+        // newline mode. That keeps one-line redraw UX while retaining stderr tail
+        // capture for diagnostics.
+        barOptions.terminal = createAnsiPipeTerminal(process.stderr);
+    }
+    const bar = new cliProgress.SingleBar(barOptions, cliProgress.Presets.shades_grey);
     bar.start(100, 0, { phase: 'Initializing...' });
     // Graceful SIGINT handling. Pino's default destination is `sync: false`
     // (buffered) — flush before exit so in-flight records reach stderr.
@@ -413,6 +646,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
     console.warn = barLog;
     // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     console.error = barLog;
+    process.env.GITNEXUS_ANALYZE_PROGRESS_ACTIVE = '1';
     // Track elapsed time per phase
     let lastPhaseLabel = 'Initializing...';
     let phaseStart = Date.now();

package/dist/core/ingestion/filesystem-walker.js

@@ -6,6 +6,20 @@ import { glob } from 'glob';
 import { createIgnoreFilter } from '../../config/ignore-service.js';
 import { logger } from '../logger.js';
 const READ_CONCURRENCY = 32;
+const ANALYZE_PROGRESS_ACTIVE_ENV = 'GITNEXUS_ANALYZE_PROGRESS_ACTIVE';
+const warnLargeFileSkip = (message) => {
+    if (process.env[ANALYZE_PROGRESS_ACTIVE_ENV] === '1') {
+        // analyze.ts routes console.warn through the progress bar logger while
+        // the bar is active. Emitting the operator-facing large-file notice there
+        // avoids raw pino NDJSON corrupting the one-line progress display in the
+        // heap-respawn child, whose stderr is intentionally piped for crash
+        // classification.
+        // eslint-disable-next-line no-console -- intentionally routed by analyze progress UI
+        console.warn(message);
+        return;
+    }
+    logger.warn(message);
+};
 /**
  * Phase 1: Scan repository — stat files to get paths + sizes, no content loaded.
  * Memory: ~10MB for 100K files vs ~1GB+ with content.
@@ -50,7 +64,7 @@ export const walkRepositoryPaths = async (repoPath, onProgress) => {
         const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
         const isOverrideUnset = !process.env.GITNEXUS_MAX_FILE_SIZE;
         const suffix = isDefault ? ', likely generated/vendored' : '';
-        logger.warn(`  Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
+        warnLargeFileSkip(`  Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
         // Always show at least the first few paths so users can diagnose why
         // edges are missing from a specific file (issue #1659). The full list is
         // gated behind GITNEXUS_VERBOSE=1 to avoid flooding output on repos with
@@ -61,17 +75,17 @@ export const walkRepositoryPaths = async (repoPath, onProgress) => {
         const showAll = isVerboseIngestionEnabled() || skippedLargePaths.length <= SKIPPED_PREVIEW_CAP;
         const preview = showAll ? skippedLargePaths : skippedLargePaths.slice(0, SKIPPED_PREVIEW_CAP);
         for (const p of preview) {
-            logger.warn(`  - ${p}`);
+            warnLargeFileSkip(`  - ${p}`);
         }
         if (!showAll) {
             const remaining = skippedLargePaths.length - SKIPPED_PREVIEW_CAP;
-            logger.warn(`  ...and ${remaining} more (set GITNEXUS_VERBOSE=1 to list them all)`);
+            warnLargeFileSkip(`  ...and ${remaining} more (set GITNEXUS_VERBOSE=1 to list them all)`);
         }
         // Only hint about the env var when the user has not set it at all. An
         // explicit GITNEXUS_MAX_FILE_SIZE=512 happens to resolve to the same
         // bytes as the default but the operator clearly already knows the knob.
         if (isDefault && isOverrideUnset) {
-            logger.warn(`  Set GITNEXUS_MAX_FILE_SIZE=<KB> to include files above the default cap.`);
+            warnLargeFileSkip(`  Set GITNEXUS_MAX_FILE_SIZE=<KB> to include files above the default cap.`);
         }
     }
     return entries;

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

@@ -24,7 +24,7 @@ import { createASTCache } from '../ast-cache.js';
 import { getLanguageFromFilename } from '../../../_shared/index.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isLanguageAvailable } from '../../tree-sitter/parser-loader.js';
-import { createWorkerPool } from '../workers/worker-pool.js';
+import { createWorkerPool, WorkerPoolInitializationError } from '../workers/worker-pool.js';
 import { extractFetchCallsFromFiles } from '../call-processor.js';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -158,18 +158,24 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const MIN_FILES_FOR_WORKERS = options?.workerThresholdsForTest?.minFiles ?? 15;
     const MIN_BYTES_FOR_WORKERS = options?.workerThresholdsForTest?.minBytes ?? 512 * 1024;
     const totalBytes = parseableScanned.reduce((s, f) => s + f.size, 0);
-    // Create worker pool once, reuse across chunks.
+    // Create worker pool lazily, reuse across cache-miss chunks.
     //
     // `workerPoolSize === 0` is a programmatic equivalent of `skipWorkers:
     // true` per the `PipelineOptions.workerPoolSize` contract. Short-
-    // circuiting here avoids constructing a useless pool that rejects
-    // every dispatch (with a `Worker pool parsing stopped` warn log per
-    // chunk) just to fall back to the sequential path via the error
-    // catch — the gate honors the docstring directly.
-    let workerPool;
-    if (!options?.skipWorkers &&
+    // circuiting here avoids constructing a useless pool. The pool is
+    // 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.
+    const shouldUseWorkers = !options?.skipWorkers &&
         options?.workerPoolSize !== 0 &&
-        (totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS)) {
+        (totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS);
+    let workerPool;
+    let workerPoolDisabled = false;
+    const getOrCreateWorkerPool = () => {
+        if (!shouldUseWorkers || workerPoolDisabled)
+            return undefined;
+        if (workerPool)
+            return workerPool;
         try {
             // U20.U3 test-only injection: integration tests pass a custom
             // worker script URL via `workerUrlForTest` (mirrors the
@@ -188,11 +194,14 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 }
             }
             workerPool = createWorkerPool(workerUrl, options?.workerPoolSize);
+            return workerPool;
         }
         catch (err) {
+            workerPoolDisabled = true;
             logger.warn({ err: err.message }, 'Worker pool creation failed, using sequential fallback:');
+            return undefined;
         }
-    }
+    };
     let filesParsedSoFar = 0;
     // Two caches with different lifetimes:
     //   - `astCache` (chunk-local, cleared between chunks) — call /
@@ -300,12 +309,19 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             // operators running `gitnexus analyze --verbose` in production
             // never saw the log (M3 from PR #1693 review).
             const chunkStartMs = verboseThroughputLog ? Date.now() : null;
-            const chunkContents = await chunkContentPromises[chunkIdx];
+            const chunkContentPromise = chunkContentPromises[chunkIdx];
+            if (!chunkContentPromise) {
+                throw new Error(`Missing prefetched parse chunk ${chunkIdx + 1}/${numChunks}`);
+            }
+            const chunkContents = await chunkContentPromise;
             chunkContentPromises[chunkIdx] = undefined; // release the in-memory copy
             startChunkPrefetch(chunkIdx + parseChunkConcurrency);
-            const chunkFiles = chunkPaths
-                .filter((p) => chunkContents.has(p))
-                .map((p) => ({ path: p, content: chunkContents.get(p) }));
+            const chunkFiles = [];
+            for (const p of chunkPaths) {
+                const content = chunkContents.get(p);
+                if (content !== undefined)
+                    chunkFiles.push({ path: p, content });
+            }
             // Compute the chunk's content-hash signature (if cache available).
             let chunkHash = null;
             if (parseCache) {
@@ -316,7 +332,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 chunkHash = computeChunkHash(entries);
             }
             let chunkWorkerData;
-            const cachedRaw = chunkHash ? parseCache.entries.get(chunkHash) : undefined;
+            const cachedRaw = chunkHash && parseCache ? parseCache.entries.get(chunkHash) : undefined;
             // Track every chunk hash we touched so the orchestrator can
             // prune stale entries (chunks whose composition no longer
             // corresponds to a live chunk in the current scan) before saving.
@@ -328,7 +344,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 chunkCacheHits++;
                 chunkWorkerData = mergeChunkResults(graph, symbolTable, cachedRaw);
                 if (isDev) {
-                    logger.info(`📦 parse-cache HIT: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash.slice(0, 8)})`);
+                    logger.info(`📦 parse-cache HIT: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash?.slice(0, 8) ?? 'unknown'})`);
                 }
                 // Progress update so UI advances even on a cache hit.
                 const cachedFiles = chunkFiles.length;
@@ -352,7 +368,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 // them under the chunk hash for the next run.
                 chunkCacheMisses++;
                 const rawResults = [];
-                chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, (current, _total, filePath) => {
+                const progressForChunk = (current, _total, filePath) => {
                     const globalCurrent = filesParsedSoFar + current;
                     // Parse phase covers 20-70 (M2). Deferred extraction handles 70-95.
                     const parsingProgress = 20 + (globalCurrent / totalParseable) * 50;
@@ -367,10 +383,28 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                             nodesCreated: graph.nodeCount,
                         },
                     });
-                }, workerPool, 
-                // Capture raw results only when we have a cache to write to —
-                // otherwise we'd retain extra arrays for nothing.
-                parseCache && chunkHash ? rawResults : undefined);
+                };
+                const activeWorkerPool = getOrCreateWorkerPool();
+                try {
+                    chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, progressForChunk, activeWorkerPool, 
+                    // Capture raw results only when we have a cache to write to —
+                    // otherwise we'd retain extra arrays for nothing.
+                    parseCache && chunkHash && activeWorkerPool ? rawResults : undefined);
+                }
+                catch (err) {
+                    if (!(err instanceof WorkerPoolInitializationError))
+                        throw err;
+                    logger.warn({
+                        err: err.message,
+                        readinessFailures: err.readinessFailures,
+                    }, 'Worker pool initialization failed, using sequential fallback:');
+                    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);
+                }
                 // Persist the raw results for this chunk hash. Sequential path
                 // doesn't populate rawResults (it writes directly to graph), so
                 // small repos without worker pool simply don't cache. That's fine.
@@ -686,9 +720,12 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         const cachedSequentialChunkFiles = [];
         for (const chunkPaths of sequentialChunkPaths) {
             const chunkContents = await readFileContents(repoPath, chunkPaths);
-            const chunkFiles = chunkPaths
-                .filter((p) => chunkContents.has(p))
-                .map((p) => ({ path: p, content: chunkContents.get(p) }));
+            const chunkFiles = [];
+            for (const p of chunkPaths) {
+                const content = chunkContents.get(p);
+                if (content !== undefined)
+                    chunkFiles.push({ path: p, content });
+            }
             cachedSequentialChunkFiles.push(chunkFiles);
             astCache = createASTCache(chunkFiles.length);
             const sequentialHeritage = await extractExtractedHeritageFromFiles(chunkFiles, astCache);

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

@@ -149,6 +149,10 @@ export declare class WorkerPoolDispatchError extends Error {
     readonly quarantinedPaths: readonly string[];
     constructor(message: string, quarantinedPaths?: readonly string[]);
 }
+export declare class WorkerPoolInitializationError extends WorkerPoolDispatchError {
+    readonly readinessFailures: readonly string[];
+    constructor(message: string, quarantinedPaths?: readonly string[], readinessFailures?: readonly string[]);
+}
 interface ResolvedWorkerPoolOptions {
     subBatchSize: number;
     subBatchMaxBytes: number;

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

@@ -77,6 +77,14 @@ export class WorkerPoolDispatchError extends Error {
         this.quarantinedPaths = quarantinedPaths;
     }
 }
+export class WorkerPoolInitializationError extends WorkerPoolDispatchError {
+    readinessFailures;
+    constructor(message, quarantinedPaths = [], readinessFailures = []) {
+        super(message, quarantinedPaths);
+        this.name = 'WorkerPoolInitializationError';
+        this.readinessFailures = readinessFailures;
+    }
+}
 /**
  * Max files to send to a worker in a single postMessage.
  * Keeps structured-clone memory bounded per sub-batch.
@@ -342,6 +350,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
     // 1100+ LOC of pool plumbing. Public worker-pool API is unchanged —
     // `getQuarantinedPaths()` still returns the same defensive copy.
     const quarantine = createQuarantine();
+    const initialReadinessFailures = [];
     // Per-slot consecutive-failure counter (F6): replaces the prior pool-wide
     // scalar so a chronically-failing slot trips the breaker on its own
     // failure streak instead of being masked by another slot's successes.
@@ -385,6 +394,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
             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),
@@ -412,7 +422,10 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
         if (items.length === 0)
             return [];
         if (activeSlots.size === 0) {
-            throw new WorkerPoolDispatchError('Worker pool has no active workers', []);
+            const detail = initialReadinessFailures.length > 0
+                ? ` after initial ready handshake: ${initialReadinessFailures.join('; ')}`
+                : '';
+            throw new WorkerPoolInitializationError(`Worker pool has no active workers${detail}`, [], initialReadinessFailures);
         }
         // Layer 3: filter out quarantined paths so a known-bad file never reaches
         // a worker again this pool lifetime. The caller queries