gitnexus 1.6.6-rc.25 → 1.6.6-rc.27

package/README.md

@@ -359,6 +359,16 @@ npx gitnexus analyze
 
 For repositories with very large source files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. The default is **8388608 bytes (8 MB)**.
 
+### Worker pool resilience tuning
+
+Three env vars expose the pool's resilience layers (respawn budget, cumulative-timeout cap, circuit breaker). Defaults are tuned for typical repos; bump them when an analyze legitimately needs more retries, or lower them to fail-fast on a known-bad shape.
+
+| Variable                                          | Default                   | Effect                                                                                                                            |
+| ------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT`            | `3`                       | Max replacement spawns per slot before the slot is dropped from the active rotation.                                              |
+| `GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`        | `5 × subBatchTimeoutMs`   | Total retry wall-time budget per job before quarantining. Bounds exponentially-growing retry waits.                              |
+| `GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD`    | `max(3, poolSize)`        | Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, dispatches require a fresh pool.            |
+
 ## Privacy
 
 - All processing happens locally on your machine

package/dist/cli/analyze.d.ts

@@ -69,6 +69,8 @@ export interface AnalyzeOptions {
     maxFileSize?: string;
     /** Override worker sub-batch idle timeout in seconds. */
     workerTimeout?: string;
+    /** Parse worker pool size; 0 disables workers (sequential fallback). */
+    workers?: string;
     embeddingThreads?: string;
     embeddingBatchSize?: string;
     embeddingSubBatchSize?: string;

package/dist/cli/analyze.js

@@ -133,10 +133,46 @@ function ensureHeap() {
                 `    (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' });
         }
-        process.exitCode = e.status ?? 1;
+        const status = typeof e === 'object' && e !== null && 'status' in e && typeof e.status === 'number'
+            ? e.status
+            : 1;
+        process.exitCode = status;
     }
     return true;
 }
+/**
+ * GITNEXUS_* env vars that `analyzeCommand` writes for backward-compatible
+ * downstream consumption. Snapshotted at function entry and restored in the
+ * finally block so that programmatic callers (tests, long-running hosts)
+ * don't see leaked state across invocations. `GITNEXUS_WORKER_POOL_SIZE` is
+ * NOT in this list: that knob is threaded through `runFullAnalysis` options
+ * (see `workerPoolSize` plumbing) so the CLI never has to mutate `process.env`
+ * for it in the first place.
+ */
+const ANALYZE_CLI_ENV_KEYS = [
+    'GITNEXUS_VERBOSE',
+    'GITNEXUS_MAX_FILE_SIZE',
+    'GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS',
+    'GITNEXUS_EMBEDDING_THREADS',
+    'GITNEXUS_EMBEDDING_BATCH_SIZE',
+    'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
+    'GITNEXUS_EMBEDDING_DEVICE',
+];
+const snapshotAnalyzeEnv = () => {
+    const snap = {};
+    for (const k of ANALYZE_CLI_ENV_KEYS)
+        snap[k] = process.env[k];
+    return snap;
+};
+const restoreAnalyzeEnv = (snap) => {
+    for (const k of ANALYZE_CLI_ENV_KEYS) {
+        const v = snap[k];
+        if (v === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = v;
+    }
+};
 /**
  * Whether the post-index skill step should run.
  *
@@ -159,6 +195,22 @@ export const analyzeCommand = async (inputPath, options) => {
     // async error that escapes the try/catch below (#1169) surfaces with
     // a stack trace and a non-zero exit code instead of a silent exit 0.
     installFatalHandlers();
+    // Snapshot the GITNEXUS_* env vars that the impl writes for downstream
+    // consumption, so they don't leak across `analyzeCommand` invocations in
+    // programmatic callers (tests, long-running hosts). `process.exit(0)` on
+    // the success path bypasses `finally` — intentional: when the process is
+    // exiting, restoration is moot. For early-return paths (validation
+    // errors) and the alreadyUpToDate fast path the finally restores the
+    // pre-call values.
+    const envSnap = snapshotAnalyzeEnv();
+    try {
+        await analyzeCommandImpl(inputPath, options);
+    }
+    finally {
+        restoreAnalyzeEnv(envSnap);
+    }
+};
+const analyzeCommandImpl = async (inputPath, options) => {
     if (options?.verbose) {
         process.env.GITNEXUS_VERBOSE = '1';
     }
@@ -174,6 +226,23 @@ export const analyzeCommand = async (inputPath, options) => {
         }
         process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(Math.round(workerTimeoutSeconds * 1000));
     }
+    // `--workers` is threaded through `runFullAnalysis` options → PipelineOptions
+    // → createWorkerPool, intentionally bypassing the GITNEXUS_WORKER_POOL_SIZE
+    // env channel so this CLI surface never mutates `process.env` for pool size.
+    // Tests can therefore re-invoke analyzeCommand with different --workers
+    // values back-to-back and observe the value they passed, not whatever the
+    // previous call leaked.
+    let workerPoolSize;
+    if (options?.workers !== undefined) {
+        const parsedWorkers = Number(options.workers);
+        if (!Number.isInteger(parsedWorkers) || parsedWorkers < 0) {
+            cliError('  --workers must be a non-negative integer. ' +
+                'Pass 0 to disable the worker pool (sequential fallback).\n');
+            process.exitCode = 1;
+            return;
+        }
+        workerPoolSize = parsedWorkers;
+    }
     // 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
@@ -394,6 +463,10 @@ export const analyzeCommand = async (inputPath, options) => {
             // be able to accept the duplicate name without also paying the
             // cost of a full pipeline re-index. See #829 review round 2.
             allowDuplicateName: options?.allowDuplicateName,
+            // Worker pool size threaded from --workers, replacing the previous
+            // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
+            // env / auto-formula fallback inside the pipeline.
+            workerPoolSize,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);
@@ -515,7 +588,7 @@ export const analyzeCommand = async (inputPath, options) => {
         // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.error = origError;
         bar.stop();
-        const msg = err.message || String(err);
+        const msg = err instanceof Error ? err.message : String(err);
         // Registry name-collision from --name (#829) — surface as an
         // actionable error rather than a generic stack-trace.
         if (err instanceof RegistryNameCollisionError) {

package/dist/cli/index.js

@@ -38,6 +38,7 @@ program
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
     .option('--worker-timeout <seconds>', 'Worker sub-batch idle timeout before retry/fallback. Default: 30.')
+    .option('--workers <n>', 'Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).')
     .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
     .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
     .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
@@ -47,6 +48,11 @@ program
     '  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
     '  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\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_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n' +
     '  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n' +
     '\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n' +

package/dist/cli/wiki.js

@@ -80,6 +80,25 @@ function prompt(question, hide = false) {
     });
 }
 export const wikiCommand = async (inputPath, options) => {
+    // Snapshot GITNEXUS_VERBOSE at entry — wikiCommand mutates it (the impl
+    // below) so cursor-client (process.env-driven) sees the right value during
+    // this run. Restored in finally so back-to-back wiki calls in long-running
+    // hosts don't leak verbose state from one invocation to the next. Pairs
+    // with the same snapshot/restore pattern in `analyzeCommand`.
+    const originalVerbose = process.env.GITNEXUS_VERBOSE;
+    try {
+        await wikiCommandImpl(inputPath, options);
+    }
+    finally {
+        if (originalVerbose === undefined) {
+            delete process.env.GITNEXUS_VERBOSE;
+        }
+        else {
+            process.env.GITNEXUS_VERBOSE = originalVerbose;
+        }
+    }
+};
+const wikiCommandImpl = async (inputPath, options) => {
     // Set verbose mode globally for cursor-client to pick up
     if (options?.verbose) {
         process.env.GITNEXUS_VERBOSE = '1';

package/dist/core/group/extractors/http-route-extractor.d.ts

@@ -18,4 +18,5 @@ export declare class HttpRouteExtractor implements ContractExtractor {
     private extractConsumersGraph;
     private extractConsumersSourceScan;
     private dedupeContracts;
+    private mergeGraphAndSourceContracts;
 }

package/dist/core/group/extractors/http-route-extractor.js

@@ -15,12 +15,14 @@ import { getPluginForFile, HTTP_SCAN_GLOB } from './http-patterns/index.js';
  *    the preferred path because the graph has richer symbol metadata
  *    (real uids, class/method structure, etc.).
  *
- * 2. **Source-scan fallback (Strategy B)** — parse files directly with
- *    the per-language plugin registry in `./http-patterns/`. Used when
- *    the graph has no routes/fetches for this repo (e.g. a repo that
- *    hasn't been indexed yet, or whose indexer doesn't know the
- *    framework). Each plugin owns its tree-sitter grammar and query
- *    sources — this orchestrator imports NO grammars or query strings.
+ * 2. **Source-scan supplement (Strategy B)** — parse files directly with
+ *    the per-language plugin registry in `./http-patterns/`. Used to
+ *    fill gaps when graph extraction only covers part of a polyglot repo
+ *    (e.g. Java graph routes plus Go source-scan routes). Graph entries
+ *    remain authoritative for duplicate contract IDs because they carry
+ *    richer symbol metadata. Each plugin owns its tree-sitter grammar
+ *    and query sources — this orchestrator imports NO grammars or query
+ *    strings.
  *
  * Adding a new language for Strategy B is a one-file edit in
  * `http-patterns/index.ts`: register a new `HttpLanguagePlugin` and
@@ -175,13 +177,11 @@ export class HttpRouteExtractor {
             return scannedFiles;
         };
         const graphProviders = dbExecutor != null ? await this.extractProvidersGraph(dbExecutor, getDetections) : [];
-        const providers = graphProviders.length > 0
-            ? graphProviders
-            : this.extractProvidersSourceScan(await getScannedFiles(), getDetections);
+        // Source scan always runs to capture routes in languages/files not covered
+        // by graph edges; the glob and per-file parse results are cached above.
+        const providers = this.mergeGraphAndSourceContracts(graphProviders, this.extractProvidersSourceScan(await getScannedFiles(), getDetections));
         const graphConsumers = dbExecutor != null ? await this.extractConsumersGraph(dbExecutor, getDetections) : [];
-        const consumers = graphConsumers.length > 0
-            ? graphConsumers
-            : this.extractConsumersSourceScan(await getScannedFiles(), getDetections);
+        const consumers = this.mergeGraphAndSourceContracts(graphConsumers, this.extractConsumersSourceScan(await getScannedFiles(), getDetections));
         return [...providers, ...consumers];
     }
     async scanFiles(repoPath) {
@@ -427,4 +427,15 @@ export class HttpRouteExtractor {
         }
         return out;
     }
+    mergeGraphAndSourceContracts(graphContracts, sourceContracts) {
+        const seenContractIds = new Set(graphContracts.map((c) => c.contractId));
+        const out = [...graphContracts];
+        for (const contract of sourceContracts) {
+            if (seenContractIds.has(contract.contractId))
+                continue;
+            seenContractIds.add(contract.contractId);
+            out.push(contract);
+        }
+        return out;
+    }
 }

package/dist/core/ingestion/languages/typescript/captures.js

@@ -53,7 +53,7 @@ const CALL_TAGS = [
     '@reference.call.member',
     '@reference.call.constructor',
 ];
-function pickFirstDefined(grouped, tags) {
+function pickFirstCapture(grouped, tags) {
     for (const tag of tags) {
         const cap = grouped[tag];
         if (cap !== undefined)
@@ -61,6 +61,14 @@ function pickFirstDefined(grouped, tags) {
     }
     return undefined;
 }
+function pickFirstNode(grouped, tags) {
+    for (const tag of tags) {
+        const node = grouped[tag];
+        if (node !== undefined)
+            return node;
+    }
+    return undefined;
+}
 /**
  * Drop `@reference.read.member` matches whose underlying `member_expression`
  * is NOT actually a read context:
@@ -102,6 +110,33 @@ function shouldEmitReadMember(memberNode) {
             return true;
     }
 }
+/** Walks the parent chain from `node` (inclusive), returning the first node
+ *  whose type matches, or null. Faster than `findNodeAtRange` when the caller
+ *  already holds the anchor node — avoids re-scanning the tree from the root. */
+function findSelfOrAncestorOfType(node, type) {
+    if (node === undefined)
+        return null;
+    let current = node;
+    while (current !== null) {
+        if (current.type === type)
+            return current;
+        current = current.parent;
+    }
+    return null;
+}
+/** Walks the parent chain from `node` (inclusive), returning the first node
+ *  whose type is in the set, or null. Plural form of {@link findSelfOrAncestorOfType}. */
+function findSelfOrAncestorOfTypes(node, types) {
+    if (node === undefined)
+        return null;
+    let current = node;
+    while (current !== null) {
+        if (types.includes(current.type))
+            return current;
+        current = current.parent;
+    }
+    return null;
+}
 export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
     // Skip the parse when the caller (parse phase's scopeTreeCache) already
     // produced a Tree for this source. Cache miss = re-parse, same as before.
@@ -135,9 +170,11 @@ export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
         // `@`; we put it back so the central extractor's prefix lookups
         // (`@scope.`, `@declaration.`, …) work.
         const grouped = {};
+        const groupedNodes = {};
         for (const c of m.captures) {
             const tag = '@' + c.name;
             grouped[tag] = nodeToCapture(tag, c.node);
+            groupedNodes[tag] = c.node;
         }
         if (Object.keys(grouped).length === 0)
             continue;
@@ -148,7 +185,11 @@ export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
         // the file-level dependency.
         if (grouped['@import.statement'] !== undefined) {
             const stmtCapture = grouped['@import.statement'];
-            const stmtNode = findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_statement') ??
+            const stmtNode = findSelfOrAncestorOfTypes(groupedNodes['@import.statement'], [
+                'import_statement',
+                'export_statement',
+            ]) ??
+                findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_statement') ??
                 findNodeAtRange(tree.rootNode, stmtCapture.range, 'export_statement');
             if (stmtNode !== null) {
                 const decomposed = splitImportStatement(stmtNode);
@@ -166,7 +207,8 @@ export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
         // `splitDynamicImport` branch consumes.
         if (grouped['@import.dynamic'] !== undefined) {
             const dynCapture = grouped['@import.dynamic'];
-            const callNode = findNodeAtRange(tree.rootNode, dynCapture.range, 'call_expression');
+            const callNode = findSelfOrAncestorOfType(groupedNodes['@import.dynamic'], 'call_expression') ??
+                findNodeAtRange(tree.rootNode, dynCapture.range, 'call_expression');
             if (callNode !== null) {
                 const decomposed = splitImportStatement(callNode);
                 for (const d of decomposed)
@@ -180,7 +222,8 @@ export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
         // we rely on this emit-side filter so the query stays simple.
         if (grouped['@reference.read.member'] !== undefined) {
             const anchor = grouped['@reference.read.member'];
-            const memberNode = findNodeAtRange(tree.rootNode, anchor.range, 'member_expression');
+            const memberNode = findSelfOrAncestorOfType(groupedNodes['@reference.read.member'], 'member_expression') ??
+                findNodeAtRange(tree.rootNode, anchor.range, 'member_expression');
             if (memberNode === null || !shouldEmitReadMember(memberNode)) {
                 continue;
             }
@@ -190,9 +233,10 @@ export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
         // overloads — TypeScript supports overload signatures via
         // function_signature, so `parameterTypes` is populated when
         // available.
-        const declAnchor = pickFirstDefined(grouped, FUNCTION_DECL_TAGS);
+        const declAnchor = pickFirstCapture(grouped, FUNCTION_DECL_TAGS);
+        const declAnchorNode = pickFirstNode(groupedNodes, FUNCTION_DECL_TAGS);
         if (declAnchor !== undefined) {
-            const fnNode = findFunctionNode(tree.rootNode, declAnchor.range);
+            const fnNode = findFunctionNode(tree.rootNode, declAnchor.range, declAnchorNode);
             if (fnNode !== null) {
                 const arity = computeTsArityMetadata(fnNode);
                 if (arity.parameterCount !== undefined) {
@@ -224,9 +268,11 @@ export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
         // calls to disambiguate by props-arity, a JSX-aware arity
         // synthesizer would need to count `jsx_attribute` children of the
         // opening tag instead of `arguments`.
-        const callAnchor = pickFirstDefined(grouped, CALL_TAGS);
+        const callAnchor = pickFirstCapture(grouped, CALL_TAGS);
+        const callAnchorNode = pickFirstNode(groupedNodes, CALL_TAGS);
         if (callAnchor !== undefined && grouped['@reference.arity'] === undefined) {
-            const callNode = findNodeAtRange(tree.rootNode, callAnchor.range, 'call_expression') ??
+            const callNode = findSelfOrAncestorOfTypes(callAnchorNode, ['call_expression', 'new_expression']) ??
+                findNodeAtRange(tree.rootNode, callAnchor.range, 'call_expression') ??
                 findNodeAtRange(tree.rootNode, callAnchor.range, 'new_expression');
             if (callNode !== null) {
                 const argList = callNode.childForFieldName('arguments');
@@ -247,7 +293,7 @@ export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
         // lookup instead of synthesis — covered by `tsReceiverBinding`.
         const scopeFnAnchor = grouped['@scope.function'];
         if (scopeFnAnchor !== undefined) {
-            const fnNode = findFunctionNode(tree.rootNode, scopeFnAnchor.range);
+            const fnNode = findFunctionNode(tree.rootNode, scopeFnAnchor.range, groupedNodes['@scope.function']);
             if (fnNode !== null) {
                 const synth = synthesizeTsReceiverBinding(fnNode);
                 if (synth !== null)
@@ -464,7 +510,10 @@ function inferArgType(argNode) {
  *  The `@scope.function` anchor range covers the whole node, but the
  *  tag alone doesn't identify which node type among the many TS
  *  function-likes. */
-function findFunctionNode(rootNode, range) {
+function findFunctionNode(rootNode, range, anchorNode) {
+    const fromAnchor = findSelfOrAncestorOfTypes(anchorNode, FUNCTION_NODE_TYPES);
+    if (fromAnchor !== null)
+        return fromAnchor;
     for (const nodeType of FUNCTION_NODE_TYPES) {
         const n = findNodeAtRange(rootNode, range, nodeType);
         if (n !== null)

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

@@ -652,6 +652,13 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
 // ============================================================================
 // Public API
 // ============================================================================
+/**
+ * Per-`WorkerPool` log-dedup state for quarantine reporting. Keyed on the
+ * pool instance so multiple concurrent pools (test fixtures, future
+ * multi-pool callers) each get their own seen-set. WeakMap entries vanish
+ * when the pool is garbage-collected.
+ */
+const loggedQuarantineByPool = new WeakMap();
 export const processParsing = async (graph, files, symbolTable, astCache, 
 /**
  * Persistent tree cache (separate from `astCache`, which the caller
@@ -684,14 +691,61 @@ outRawResults) => {
             // a repo crosses the worker-pool threshold.
             logger.warn(`[scope-resolution prof] worker pool engaged for ${files.length} files — cross-phase tree cache will be empty; scope-resolution re-parses.`);
         }
-        try {
-            return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, reportProgress, outRawResults);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            logger.warn({ message }, 'Worker pool parsing stopped; continuing with sequential parser:');
-            reportProgress?.(lastProgress, files.length, `Sequential fallback after worker issue: ${message}`);
+        // U20 design pivot: the worker pool's resilience layers
+        // (respawn budget, circuit breaker, quarantine, slot-attribution,
+        // cumulative timeout) are the SOLE contract for handling worker
+        // failures. There is no sequential-parser fallback for either
+        // partial quarantine or full pool failure — the operator must see
+        // a clear hard signal when workers can't recover, instead of a
+        // silently-degraded graph from a possibly-crashing main-thread
+        // sequential parser. A failing tree-sitter native binding that
+        // quarantined a worker would, under the previous design, re-trigger
+        // the same SIGSEGV on the main thread; we avoid that risk entirely.
+        //
+        // - Partial quarantine: the file is missing from this run's graph;
+        //   the per-chunk warn log below surfaces it; U2's chunk-cache
+        //   write-guard in parse-impl.ts keeps the chunk uncached so the
+        //   next analyze gets a cache miss and a fresh pool retries.
+        // - Full pool failure: `WorkerPoolDispatchError` propagates from
+        //   `processParsingWithWorkers` up through this function. The
+        //   analyze run errors out instead of falling back to sequential.
+        const data = await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, reportProgress, outRawResults);
+        // Session-scoped quarantine (worker-pool resilience Layer 3): surface
+        // any files this pool has decided are unsafe for workers so the
+        // operator can see what was skipped. The pool already filtered them
+        // out of dispatch; we only need to log + progress-report. Quarantine
+        // is session-scoped per pool instance — a fresh `createWorkerPool`
+        // call clears it.
+        //
+        // Dedup: log full path list only for entries newly quarantined since
+        // the previous dispatch on the same pool. The per-chunk progress
+        // message still surfaces the count for UX continuity, but the
+        // structured `quarantinedFiles` payload is only emitted when there
+        // is new signal — prevents O(quarantine × chunks) log spam.
+        const quarantineSnapshot = workerPool.getQuarantinedPaths?.() ?? [];
+        const quarantineSet = new Set(quarantineSnapshot);
+        if (quarantineSet.size > 0) {
+            const quarantinedInChunk = files.filter((file) => quarantineSet.has(file.path));
+            if (quarantinedInChunk.length > 0) {
+                const seenForPool = loggedQuarantineByPool.get(workerPool) ?? new Set();
+                const newlyQuarantined = quarantinedInChunk
+                    .map((file) => file.path)
+                    .filter((p) => !seenForPool.has(p));
+                for (const p of newlyQuarantined)
+                    seenForPool.add(p);
+                loggedQuarantineByPool.set(workerPool, seenForPool);
+                if (newlyQuarantined.length > 0) {
+                    logger.warn({
+                        newlyQuarantined,
+                        cumulativeQuarantine: quarantineSet.size,
+                        chunkSkipped: quarantinedInChunk.length,
+                    }, `Worker quarantine: ${newlyQuarantined.length} new file(s) skipped this chunk ` +
+                        `(${quarantinedInChunk.length} skipped total, ${quarantineSet.size} cumulative).`);
+                }
+                reportProgress?.(lastProgress, files.length, `${quarantinedInChunk.length} worker-quarantined file(s) skipped`);
+            }
         }
+        return data;
     }
     // Fallback: sequential parsing (no pre-extracted data)
     await processParsingSequential(graph, files, symbolTable, astCache, scopeTreeCache, reportProgress);