gitnexus 1.6.6-rc.99 → 1.6.6

package/dist/mcp/resources.js

@@ -234,7 +234,7 @@ async function getReposResource(backend) {
     if (repos.length > 1) {
         lines.push('');
         lines.push('# Multiple repos indexed. Use repo parameter in tool calls:');
-        lines.push(`# gitnexus_search({query: "auth", repo: "${repos[0].name}"})`);
+        lines.push(`# query({query: "auth", repo: "${repos[0].name}"})`);
     }
     return lines.join('\n');
 }
@@ -308,7 +308,7 @@ async function getClustersResource(backend, repoName) {
             }
         }
         if (result.clusters.length > displayLimit) {
-            lines.push(`\n# Showing top ${displayLimit} of ${result.clusters.length} modules. Use gitnexus_query for deeper search.`);
+            lines.push(`\n# Showing top ${displayLimit} of ${result.clusters.length} modules. Use the query tool for deeper search.`);
         }
         return lines.join('\n');
     }
@@ -335,7 +335,7 @@ async function getProcessesResource(backend, repoName) {
             lines.push(`    steps: ${proc.stepCount || 0}`);
         }
         if (result.processes.length > displayLimit) {
-            lines.push(`\n# Showing top ${displayLimit} of ${result.processes.length} processes. Use gitnexus_query for deeper search.`);
+            lines.push(`\n# Showing top ${displayLimit} of ${result.processes.length} processes. Use the query tool for deeper search.`);
         }
         return lines.join('\n');
     }

package/dist/mcp/server.js

@@ -287,7 +287,6 @@ export async function startMCPServer(backend) {
         },
     });
     const transport = new CompatibleStdioServerTransport(process.stdin, safeStdout);
-    await server.connect(transport);
     // Surface the redirect counter on shutdown so users see the volume of
     // stray writes even when individual payloads were truncated/suppressed.
     process.on('exit', () => sentinel.flushSummary());
@@ -337,9 +336,18 @@ export async function startMCPServer(backend) {
         process.stderr.write(`GitNexus MCP unhandledRejection: ${reason?.stack || reason}\n`);
     });
     // Handle stdio errors — stdin close means the parent process is gone.
+    // Defense-in-depth: the transport also listens for stdin end/close and
+    // handles transport-level cleanup. These listeners handle process-level
+    // shutdown. Both paths are idempotent and safe to fire together.
     // Wrap so the event payload (e.g. an Error for 'error') can never reach
     // process.exit() as a non-numeric exit code, and void the returned promise.
     process.stdin.on('end', () => void shutdown(0));
+    process.stdin.on('close', () => void shutdown(0));
     process.stdin.on('error', () => void shutdown(0));
     process.stdout.on('error', () => void shutdown(0));
+    if (process.stdin.readableEnded || process.stdin.destroyed) {
+        await shutdown(0);
+        return;
+    }
+    await server.connect(transport);
 }

package/dist/storage/git.d.ts

@@ -107,6 +107,17 @@ export declare const hasGitDir: (dirPath: string) => boolean;
  * `<rig>/refinery/rig/` layouts).
  */
 export declare const getRemoteOriginUrl: (repoPath: string) => string | null;
+/**
+ * Best-effort detection of the repository's default branch (#243).
+ *
+ * Reads `git symbolic-ref --short refs/remotes/origin/HEAD`, which resolves to
+ * the short ref `origin/<branch>` that the local `origin/HEAD` points at, and
+ * strips the `origin/` prefix. This is a purely local lookup — it never makes a
+ * network call. Returns `null` when there is no git repo, no `origin` remote, no
+ * `origin/HEAD` (e.g. it was never set by clone, or the repo is detached), or
+ * git is unavailable, so callers can fall back to a configured/default branch.
+ */
+export declare const getDefaultBranch: (repoPath: string) => string | null;
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/dist/storage/git.js

@@ -265,6 +265,36 @@ export const getRemoteOriginUrl = (repoPath) => {
         return null;
     }
 };
+/**
+ * Best-effort detection of the repository's default branch (#243).
+ *
+ * Reads `git symbolic-ref --short refs/remotes/origin/HEAD`, which resolves to
+ * the short ref `origin/<branch>` that the local `origin/HEAD` points at, and
+ * strips the `origin/` prefix. This is a purely local lookup — it never makes a
+ * network call. Returns `null` when there is no git repo, no `origin` remote, no
+ * `origin/HEAD` (e.g. it was never set by clone, or the repo is detached), or
+ * git is unavailable, so callers can fall back to a configured/default branch.
+ */
+export const getDefaultBranch = (repoPath) => {
+    try {
+        const ref = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
+            cwd: repoPath,
+            // Suppress stderr -- see getCurrentCommit comment and #1172. Without it,
+            // git prints "fatal: ref refs/remotes/origin/HEAD is not a symbolic ref"
+            // to the user's terminal on repos that never set origin/HEAD.
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        })
+            .toString()
+            .trim();
+        if (!ref)
+            return null;
+        return ref.startsWith('origin/') ? ref.slice('origin/'.length) : ref;
+    }
+    catch {
+        return null;
+    }
+};
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/dist/storage/parse-cache.d.ts

@@ -35,6 +35,14 @@ export interface ParseCache {
      * Transient — never serialized to disk.
      */
     usedKeys: Set<string>;
+    /**
+     * When set, chunk payloads are loaded from / flushed to sharded files on
+     * demand instead of retaining every chunk in `entries` for the whole run
+     * (#1983 — Linux kernel OOM from duplicate in-memory cache + graph).
+     */
+    storagePath?: string;
+    /** Index of chunk hashes known to exist under `storagePath/parse-cache/`. */
+    onDiskKeys?: Set<string>;
 }
 /** Stable hash of a single file's contents — used by callers to compose a chunk hash. */
 export declare const fileContentHash: (content: Buffer | string) => string;
@@ -49,6 +57,20 @@ export declare const computeChunkHash: (entries: Array<{
     filePath: string;
     contentHash: string;
 }>) => string;
+export declare const mapReplacer: (_key: string, value: unknown) => unknown;
+export declare const mapReviver: (_key: string, value: unknown) => unknown;
+/**
+ * Drop fields that are not replayed by `mergeChunkResults` / parse-impl after
+ * RING4-1 (#942). Shrinks on-disk shards and peak RSS during cold runs.
+ */
+export declare const slimParseWorkerResultsForCache: (chunkResults: readonly ParseWorkerResult[]) => ParseWorkerResult[];
+/** Load one chunk shard. Does not retain it in `cache.entries`. */
+export declare const loadParseCacheChunk: (cache: ParseCache, chunkHash: string) => Promise<ParseWorkerResult[] | undefined>;
+/**
+ * Persist one chunk shard and avoid retaining it in RAM for the rest of the
+ * run. Falls back to `cache.entries` when `storagePath` is unset (unit tests).
+ */
+export declare const persistParseCacheChunk: (cache: ParseCache, chunkHash: string, chunkResults: readonly ParseWorkerResult[]) => Promise<void>;
 /**
  * Load the parse cache. Returns an empty cache on any failure (missing
  * file, corrupt JSON, version mismatch). Never throws on a normal load.
@@ -64,7 +86,7 @@ export declare const loadParseCache: (storagePath: string) => Promise<ParseCache
  * reparses. This is not a single atomic swap of the whole tree, but avoids
  * leaving a half-written shard set visible to readers.
  */
-export declare const saveParseCache: (storagePath: string, cache: ParseCache) => Promise<void>;
+export declare const saveParseCache: (storagePath: string, cache: ParseCache) => Promise<string[]>;
 /**
  * Drop entries whose hashes are not in `usedHashes`. Called at the end
  * of a run so chunks that no longer correspond to any current chunk

package/dist/storage/parse-cache.js

@@ -41,7 +41,18 @@ import { fileURLToPath } from 'url';
  * On version mismatch, `loadParseCache` returns an empty cache and the
  * next save overwrites the on-disk file with the new version baked in.
  */
-const SCHEMA_BUMP = 2;
+// Bumped to 4 in #1983: on-disk parse-cache shards omit legacy DAG fields
+// (`calls`, `assignments`, `constructorBindings`) unused after RING4-1 (#942)
+// and the worker `parsedFiles` (the worker writes those to the disk ParsedFile
+// store instead). #2038 added a DURABLE, content-addressed ParsedFile store
+// (`parsedfile-cache/`, see parsedfile-store.ts) keyed by chunk hash that
+// mirrors THIS cache's lifecycle — version-gated by PARSE_CACHE_VERSION, pruned
+// in lockstep to the surviving keys. On a warm parse-cache hit the chunk's
+// ParsedFiles are restored from it, so scope-resolution does NOT re-extract on
+// the main thread (the #1983 OOM). Because the two stores share this version,
+// any future change to the `ParsedFile` serialization shape MUST bump
+// SCHEMA_BUMP so both invalidate in lockstep.
+const SCHEMA_BUMP = 4;
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from
@@ -104,14 +115,14 @@ export const computeChunkHash = (entries) => {
  */
 const MAP_TAG = '__$mapEntries$__';
 const SET_TAG = '__$setValues$__';
-const mapReplacer = (_key, value) => {
+export const mapReplacer = (_key, value) => {
     if (value instanceof Map)
         return { [MAP_TAG]: Array.from(value.entries()) };
     if (value instanceof Set)
         return { [SET_TAG]: Array.from(value.values()) };
     return value;
 };
-const mapReviver = (_key, value) => {
+export const mapReviver = (_key, value) => {
     if (value && typeof value === 'object') {
         const v = value;
         if (Array.isArray(v[MAP_TAG]))
@@ -125,6 +136,73 @@ const getLegacyCachePath = (storagePath) => path.join(storagePath, LEGACY_CACHE_
 const getCacheDirPath = (storagePath) => path.join(storagePath, CACHE_DIRNAME);
 const getCacheIndexPath = (storagePath) => path.join(getCacheDirPath(storagePath), CACHE_INDEX_FILENAME);
 const getCacheChunkPath = (storagePath, chunkHash) => path.join(getCacheDirPath(storagePath), `${chunkHash}.json`);
+/**
+ * Drop fields that are not replayed by `mergeChunkResults` / parse-impl after
+ * RING4-1 (#942). Shrinks on-disk shards and peak RSS during cold runs.
+ */
+export const slimParseWorkerResultsForCache = (chunkResults) => {
+    const slim = [];
+    for (const result of chunkResults) {
+        slim.push({
+            ...result,
+            calls: [],
+            assignments: [],
+            constructorBindings: [],
+            parsedFiles: [],
+        });
+    }
+    return slim;
+};
+const readParseCacheChunkFromDisk = async (storagePath, chunkHash) => {
+    if (!isValidChunkCacheKey(chunkHash))
+        return undefined;
+    try {
+        const chunkRaw = await fs.readFile(getCacheChunkPath(storagePath, chunkHash), 'utf-8');
+        const chunkData = JSON.parse(chunkRaw, mapReviver);
+        return Array.isArray(chunkData) ? chunkData : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Load one chunk shard. Does not retain it in `cache.entries`. */
+export const loadParseCacheChunk = async (cache, chunkHash) => {
+    const inMemory = cache.entries.get(chunkHash);
+    if (inMemory !== undefined)
+        return inMemory;
+    if (cache.storagePath && cache.onDiskKeys?.has(chunkHash)) {
+        return readParseCacheChunkFromDisk(cache.storagePath, chunkHash);
+    }
+    return undefined;
+};
+/**
+ * Cache directories already created this process. `persistParseCacheChunk` runs
+ * once per cache-miss chunk; without this guard every miss re-issues a redundant
+ * `mkdir` syscall (hundreds on a large cold repo) (#1983). Storage paths are
+ * process-scoped, so the Set stays bounded.
+ */
+const createdCacheDirs = new Set();
+/**
+ * Persist one chunk shard and avoid retaining it in RAM for the rest of the
+ * run. Falls back to `cache.entries` when `storagePath` is unset (unit tests).
+ */
+export const persistParseCacheChunk = async (cache, chunkHash, chunkResults) => {
+    const slim = slimParseWorkerResultsForCache(chunkResults);
+    if (cache.storagePath) {
+        const cacheDir = getCacheDirPath(cache.storagePath);
+        if (!createdCacheDirs.has(cacheDir)) {
+            await fs.mkdir(cacheDir, { recursive: true });
+            createdCacheDirs.add(cacheDir);
+        }
+        const payload = JSON.stringify(slim, mapReplacer);
+        await fs.writeFile(getCacheChunkPath(cache.storagePath, chunkHash), payload, 'utf-8');
+        cache.onDiskKeys ??= new Set();
+        cache.onDiskKeys.add(chunkHash);
+        cache.entries.delete(chunkHash);
+        return;
+    }
+    cache.entries.set(chunkHash, slim);
+};
 const loadLegacyParseCache = async (storagePath) => {
     const cachePath = getLegacyCachePath(storagePath);
     try {
@@ -135,17 +213,17 @@ const loadLegacyParseCache = async (storagePath) => {
             data.version !== PARSE_CACHE_VERSION ||
             typeof data.entries !== 'object' ||
             data.entries === null) {
-            return emptyCache();
+            return emptyCache(storagePath);
         }
         const entries = new Map();
         for (const [k, v] of Object.entries(data.entries)) {
             if (Array.isArray(v))
                 entries.set(k, v);
         }
-        return { version: PARSE_CACHE_VERSION, entries, usedKeys: new Set() };
+        return { version: PARSE_CACHE_VERSION, entries, usedKeys: new Set(), storagePath };
     }
     catch {
-        return emptyCache();
+        return emptyCache(storagePath);
     }
 };
 const loadShardedParseCache = async (storagePath) => {
@@ -157,23 +235,22 @@ const loadShardedParseCache = async (storagePath) => {
             data === null ||
             data.version !== PARSE_CACHE_VERSION ||
             !Array.isArray(data.keys)) {
-            return emptyCache();
+            return emptyCache(storagePath);
         }
-        const entries = new Map();
+        const onDiskKeys = new Set();
         for (const chunkHash of data.keys) {
-            if (typeof chunkHash !== 'string' || !isValidChunkCacheKey(chunkHash))
-                continue;
-            try {
-                const chunkRaw = await fs.readFile(getCacheChunkPath(storagePath, chunkHash), 'utf-8');
-                const chunkData = JSON.parse(chunkRaw, mapReviver);
-                if (Array.isArray(chunkData))
-                    entries.set(chunkHash, chunkData);
-            }
-            catch {
-                /* skip corrupt or missing shard */
+            if (typeof chunkHash === 'string' && isValidChunkCacheKey(chunkHash)) {
+                onDiskKeys.add(chunkHash);
             }
         }
-        return { version: PARSE_CACHE_VERSION, entries, usedKeys: new Set() };
+        // Lazy: index only — load individual shards on cache hit (#1983).
+        return {
+            version: PARSE_CACHE_VERSION,
+            entries: new Map(),
+            usedKeys: new Set(),
+            storagePath,
+            onDiskKeys,
+        };
     }
     catch {
         return null;
@@ -205,31 +282,50 @@ export const saveParseCache = async (storagePath, cache) => {
     const tmpDir = `${cacheDir}.tmp`;
     await fs.rm(tmpDir, { recursive: true, force: true });
     await fs.mkdir(tmpDir, { recursive: true });
-    const keys = [];
-    for (const [chunkHash, chunkResults] of cache.entries) {
-        if (!isValidChunkCacheKey(chunkHash))
+    const keys = [...cache.usedKeys].filter(isValidChunkCacheKey).sort();
+    // Track hashes whose shard was actually written/copied this save. A hash can
+    // be in `usedKeys` without a backing shard — its in-memory serialize threw, or
+    // its on-disk copy failed/was-absent (e.g. a worker-quarantined chunk added to
+    // usedKeys but never persisted). Writing such a hash into `index.keys` would
+    // make the next load reference a shard that doesn't exist (#1983). Build the
+    // index from what we persisted, not from the raw usedKeys snapshot.
+    const writtenKeys = [];
+    for (const chunkHash of keys) {
+        const chunkPath = path.join(tmpDir, `${chunkHash}.json`);
+        const inMemory = cache.entries.get(chunkHash);
+        if (inMemory !== undefined) {
+            let payload;
+            try {
+                payload = JSON.stringify(inMemory, mapReplacer);
+            }
+            catch {
+                continue;
+            }
+            await fs.writeFile(chunkPath, payload, 'utf-8');
+            writtenKeys.push(chunkHash);
             continue;
-        let payload;
+        }
+        const existingPath = getCacheChunkPath(storagePath, chunkHash);
         try {
-            payload = JSON.stringify(chunkResults, mapReplacer);
+            await fs.copyFile(existingPath, chunkPath);
+            writtenKeys.push(chunkHash);
         }
         catch {
-            // Extremely dense chunks could theoretically exceed string limits; skip
-            // rather than failing the entire save (orchestrator catches save errors).
-            continue;
+            /* shard missing — skip; next run treats as cache miss */
         }
-        keys.push(chunkHash);
-        const chunkPath = path.join(tmpDir, `${chunkHash}.json`);
-        await fs.writeFile(chunkPath, payload, 'utf-8');
     }
     const index = {
         version: cache.version,
-        keys,
+        keys: writtenKeys,
     };
     await fs.writeFile(path.join(tmpDir, CACHE_INDEX_FILENAME), JSON.stringify(index), 'utf-8');
     await fs.rm(cacheDir, { recursive: true, force: true });
     await fs.rename(tmpDir, cacheDir);
     await fs.rm(getLegacyCachePath(storagePath), { force: true });
+    // The authoritative final key set actually backed by a shard on disk.
+    // Callers (the durable ParsedFile store) prune to exactly these so the two
+    // content-addressed stores stay coherent — a chunk is cached iff BOTH have it.
+    return writtenKeys;
 };
 /**
  * Drop entries whose hashes are not in `usedHashes`. Called at the end
@@ -244,10 +340,20 @@ export const pruneCache = (cache, usedHashes) => {
             removed++;
         }
     }
+    if (cache.onDiskKeys) {
+        for (const k of cache.onDiskKeys) {
+            if (!usedHashes.has(k)) {
+                cache.onDiskKeys.delete(k);
+                removed++;
+            }
+        }
+    }
     return removed;
 };
-const emptyCache = () => ({
+const emptyCache = (storagePath) => ({
     version: PARSE_CACHE_VERSION,
     entries: new Map(),
     usedKeys: new Set(),
+    storagePath,
+    onDiskKeys: storagePath ? new Set() : undefined,
 });

package/dist/storage/parsedfile-store.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Disk-backed `ParsedFile` store (#1983 scope-resolution OOM).
+ *
+ * ## Why this exists
+ *
+ * The scope-resolution phase needs a `ParsedFile` (scopes / defs / reference
+ * sites) for every file. Historically it re-extracted each file from source on
+ * the **main thread** via `extractParsedFile` → `parseSourceSafe`. On a huge
+ * repo (Linux kernel, ~64k C files) that re-parse accumulates an unbounded
+ * **native** memory leak in `tree-sitter` 0.21.1 (`CallbackInput` retains the
+ * input string with no destructor; node-tree-sitter PR #201) — the leaked
+ * `TSTree` memory is invisible to V8, never reclaimed by GC, and not freed by
+ * worker_thread teardown. The parse phase escapes it only because each parse is
+ * relatively cheap there; a second full re-parse of every file on the immortal
+ * main thread pushes RSS past the heap cap and the OOM-killer fires.
+ *
+ * The fix: the parse workers already build a tree-sitter `Tree` per file, so
+ * they emit the `ParsedFile` directly (reusing that tree — no second parse).
+ * Holding all of them in main-thread heap is what the original #1983 work
+ * removed (it cost ~1× the semantic model in RAM during parse), so instead we
+ * flush them to this disk store per chunk and stream them back per language in
+ * scope-resolution. Net effect: the file is parsed exactly once (in a worker),
+ * scope-resolution does ZERO parsing, and peak heap stays bounded.
+ *
+ * ## Shape
+ *
+ * `<storagePath>/parsedfile-store/<shardId>.json` — one shard per parse chunk,
+ * a JSON array of `ParsedFile` serialized with the same `mapReplacer` the parse
+ * cache uses (Scope.bindings / Scope.typeBindings are `Map`s). The store is
+ * cleared at the start of each parse and after scope-resolution consumes it, so
+ * it never lingers and never goes stale across runs.
+ *
+ * ## Durable sibling store (`parsedfile-cache/`, warm-cache coverage)
+ *
+ * The run-scoped store above is only populated when the parse workers actually
+ * run. On a warm re-analyze where every chunk is a parse-cache HIT, no worker
+ * runs, the run-scoped store was cleared at parse start, and the cached
+ * `ParseWorkerResult` carries no `ParsedFile`s (the worker emptied them after
+ * its store write) — so scope-resolution would find an empty store and fall
+ * back to main-thread `extractParsedFile`, re-opening the #1983 OOM. To close
+ * that gap we ALSO write the worker's ParsedFiles to a second, CONTENT-ADDRESSED
+ * store keyed by the parse chunk hash (`getDurableParsedFileDir`), which mirrors
+ * the parse cache's lifecycle (persists across runs, pruned by `usedKeys`,
+ * version-tied via `PARSE_CACHE_VERSION`). On a warm hit the chunk's durable
+ * shards are byte-COPIED into the run-scoped store (no re-parse, no
+ * re-serialize → byte-identical), so scope-resolution streams them exactly as
+ * on a cold run. Content-addressing makes stale reuse impossible: a changed
+ * file changes its chunk hash, which misses BOTH stores and re-dispatches.
+ */
+import type { ParsedFile, SymbolDefinition } from '../_shared/index.js';
+/**
+ * Build a JSON.parse reviver that (a) interns every string against a shared
+ * pool and (b) applies the parse-cache `mapReviver` (Map/Set reconstruction).
+ *
+ * `JSON.parse` allocates a DISTINCT string object for every textual token, so a
+ * `ParsedFile` graph round-tripped through disk holds millions of duplicate
+ * strings — every def repeats its `filePath`, and common type/qualified names
+ * (`int`, `void`, `struct …`) recur across the whole repo. On the Linux kernel
+ * that roughly DOUBLES the deserialized heap (~15 GB vs ~7.6 GB interned).
+ * Interning IN the reviver collapses duplicates as the tree is revived (one
+ * pass, no second walk). The pool is per-load; the interned strings stay shared
+ * through the retained `ParsedFile` references after the pool is dropped.
+ */
+export declare const makeInterningReviver: (pool: Map<string, string>, defPool: Map<string, SymbolDefinition>) => (key: string, value: unknown) => unknown;
+/**
+ * Best-effort synchronous GC. Uses `globalThis.gc` when `--expose-gc` is set,
+ * else lazily wires it via `v8.setFlagsFromString('--expose-gc')` + a fresh
+ * `vm` context. Exported so scope-resolution can reclaim a finished language's
+ * ParsedFiles at the per-language eviction boundary (#1741 / kernel memory work).
+ */
+export declare const forceGc: () => void;
+export declare const getParsedFileStoreDir: (storagePath: string) => string;
+/** Remove any prior run's shards so a fresh parse starts clean. Idempotent. */
+export declare const clearParsedFileStore: (storagePath: string) => Promise<void>;
+/**
+ * Write one parse chunk's `ParsedFile[]` to the store as a single shard (async).
+ * No-op for an empty chunk. `shardId` must be unique within a run. Used by the
+ * main-thread no-store-disabled fallback and any non-worker writer; the worker
+ * store path uses {@link persistParsedFileShardSync}.
+ */
+export declare const persistParsedFileChunk: (storagePath: string, shardId: string, parsedFiles: readonly ParsedFile[]) => Promise<void>;
+/**
+ * Synchronous shard writer for use INSIDE a parse worker (#1983 parallel
+ * serialization). The worker is a dedicated thread, so a blocking write there
+ * protects the main thread, and a sync write avoids threading `async`/`await`
+ * through the synchronous per-file extract loop. Produces byte-identical shards
+ * to {@link persistParsedFileChunk} via the shared {@link serializeParsedFileShard}.
+ * No-op for an empty chunk. `shardId` must be globally unique for the run (the
+ * worker uses `w<threadId>-<seq>`); a duplicate would silently overwrite.
+ */
+export declare const persistParsedFileShardSync: (storagePath: string, shardId: string, parsedFiles: readonly ParsedFile[]) => void;
+/**
+ * Stream the store and return the `ParsedFile`s whose `filePath` is in
+ * `wantPaths`, keyed by path. Loads one shard at a time and retains only the
+ * matching entries, so peak heap is bounded by (matched set) + (one shard)
+ * rather than the whole store. Returns an empty map when the store is absent
+ * (e.g. tests, or a run with no worker pool) — callers fall back to a fresh
+ * extract for the missing files.
+ */
+export declare const loadParsedFilesForPaths: (storagePath: string, wantPaths: ReadonlySet<string>) => Promise<Map<string, ParsedFile>>;
+/** Durable store dir — a sibling of `parsedfile-store/`, NEVER cleared per run. */
+export declare const getDurableParsedFileDir: (storagePath: string) => string;
+/**
+ * Synchronous durable-shard writer for use INSIDE a parse worker, alongside
+ * {@link persistParsedFileShardSync}. Writes the SAME bytes to a content-addressed
+ * durable location keyed by the parse chunk hash so a future warm hit can reuse
+ * them. `chunkHash`+`threadId`+`shardSeq` is collision-free across the
+ * N-shards-per-chunk fan-out and across worker-death retries — the same
+ * uniqueness that makes the run-scoped `w<tid>-<seq>` name safe, prefixed by
+ * content. No-op for an empty chunk.
+ */
+export declare const persistDurableParsedFileShardSync: (durableDir: string, chunkHash: string, threadId: number, shardSeq: number, parsedFiles: readonly ParsedFile[]) => void;
+/**
+ * Restore a cached chunk's durable shards into the run-scoped store on a warm
+ * hit. A verbatim byte copy (no parse, no re-serialize), so the restored
+ * ParsedFiles are byte-identical to a cold run and `loadParsedFilesForPaths`
+ * (which keys on `filePath`, not shard name) gives scope-resolution full
+ * coverage. The durable shard names already carry the chunk hash, so they never
+ * collide with the worker's run-scoped `w<tid>-<seq>` shards. Returns the number
+ * of shards restored (0 ⇒ no durable coverage for this chunk; caller treats it
+ * as a miss).
+ */
+export declare const restoreDurableParsedFileShard: (durableDir: string, runStoragePath: string, chunkHash: string) => Promise<number>;
+/**
+ * Read the durable index and return the set of chunk hashes it vouches for,
+ * gated on `expectedVersion` (`PARSE_CACHE_VERSION`). A version mismatch or a
+ * missing/corrupt index returns the empty set — the caller then treats every
+ * chunk as a durable miss and re-dispatches workers (NEVER the main-thread
+ * `extractParsedFile` fallback), which rewrites the durable store under the new
+ * version. Mirrors `loadParseCache`'s version-invalidation contract.
+ */
+export declare const loadDurableParsedFileIndex: (durableDir: string, expectedVersion: string) => Promise<Set<string>>;
+/**
+ * Prune the durable store to `keepKeys` and rewrite its index. `keepKeys` must
+ * be the parse cache's surviving on-disk keys (so the two stores stay coherent:
+ * a chunk is "cached" iff BOTH its parse-cache shard and its durable shards
+ * exist; a quarantined chunk — no parse-cache shard — drops its durable subdir
+ * here and re-dispatches next run). Only subdirs with ≥1 shard are indexed
+ * (mirrors `saveParseCache`'s written-keys discipline — never vouch for a chunk
+ * hash with no backing shard). The index write is tmp+rename atomic.
+ */
+export declare const pruneAndSaveDurableParsedFileStore: (durableDir: string, version: string, keepKeys: ReadonlySet<string>) => Promise<void>;