gitnexus 1.6.8-rc.8 → 1.6.8

package/dist/core/lbug/pdg-emit-sink.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Streaming PDG graph-emit sink (issue #2202).
+ *
+ * The PDG emit loop (`scope-resolution/pipeline/run.ts`, the `--pdg` block)
+ * materializes BasicBlock nodes + intra-file PDG edges (CFG / REACHING_DEF /
+ * CDG / POST_DOMINATE / TAINTED / SANITIZES) into the in-memory
+ * `KnowledgeGraph`. At full-kernel scale that layer dominates peak RSS
+ * (~7 GB at 511K BasicBlocks; ~100 GB extrapolated to the full kernel → OOM).
+ *
+ * `PdgEmitSink` is a write-routing façade over the real graph: the emit
+ * functions are write-only and compute every edge endpoint by deterministic id
+ * (audited — no read-back), so the sink can route BasicBlock node rows and PDG
+ * edge rows straight to bounded CSV-on-disk writers and **never store them**.
+ * The graph's resident size stops growing with the PDG layer → peak RSS becomes
+ * O(chunk buffer), not O(graph). Everything else (structural nodes/edges, the
+ * whole-program M4 TAINT_PATH edges) is delegated to the real graph unchanged.
+ *
+ * Why synchronous writers? The whole PDG emit (`runScopeResolution` and its
+ * per-file loop) is synchronous — there is no `await` point to drain an async
+ * stream, so a `BufferedCSVWriter` (Node `WriteStream`) would accumulate
+ * unwritten chunks in process memory across millions of rows, defeating the RSS
+ * bound. `fs.writeSync` goes straight to the OS; resident memory is bounded to
+ * one `chunkRows` buffer. This mirrors the sync-shard pattern in
+ * `storage/parsedfile-store.ts`.
+ *
+ * Byte-identity (issue acceptance): the sink reuses the SAME shared row
+ * builders (`buildBasicBlockRow`, `buildRelRow`) and label derivation
+ * (`getNodeLabel`) as `streamAllCSVsToDisk`, so the streamed CSV line SET is
+ * identical to the whole-graph emit's, and the bulk COPY loads the same rows →
+ * the persisted graph is SET-identical and DB-identical. The guarantee is
+ * set-level, not byte-level on the CSV file: the sink streams rows in emit
+ * order and does NOT re-sort them under `GITNEXUS_SORT_GRAPH_OUTPUT`, so a
+ * streamed CSV file is not necessarily byte-for-byte equal to the sorted
+ * whole-graph CSV — but the row set, and therefore the DB outcome, is. (The
+ * streamed CSVs are deleted right after the COPY, so their on-disk byte order
+ * is never observed.) Cross-pass dedup is done upstream, per FILE, in the emit
+ * loop (`run.ts` skips a file whose PDG already streamed) rather than in the
+ * sink, because a file can be PDG-emitted in more than one language pass (a
+ * `.ts` module imported by a `.vue` SFC is emitted in both the TypeScript and
+ * Vue context passes over the same worker-built CFG) and a sink-level per-id
+ * dedup set would retain every id → O(total ids) memory, defeating the
+ * O(chunk) RSS bound (#2202 review #1). The differential fingerprint test
+ * (issue #2202 U6) and the Vue+TS cross-pass integration test guard the set.
+ */
+import type { GraphNode, GraphRelationship, RelationshipType } from '../../_shared/index.js';
+import type { KnowledgeGraph } from '../graph/types.js';
+import { type NodeTableName } from './schema.js';
+/** Default streamed-write buffer (rows). Matches the whole-graph emit's
+ *  `FLUSH_EVERY` order of magnitude; overridable via `GITNEXUS_PDG_EMIT_CHUNK_SIZE`. */
+export declare const DEFAULT_PDG_EMIT_CHUNK_ROWS = 500;
+/**
+ * COPY manifest produced by {@link PdgEmitSink.finalize}. Shaped to merge
+ * directly into `StreamedCSVResult` so `loadGraphToLbug` COPYs the streamed
+ * PDG CSVs through the same per-table / per-pair loops as the structural CSVs.
+ * Paths are absolute, so persistence needs no dir recomputation.
+ */
+export interface PdgEmitManifest {
+    /** Node-table CSVs (only `BasicBlock` today). */
+    readonly nodeFiles: Map<NodeTableName, {
+        csvPath: string;
+        rows: number;
+    }>;
+    /** pairKey (`From|To`) → per-pair edge CSV. */
+    readonly relsByPair: Map<string, {
+        csvPath: string;
+        rows: number;
+    }>;
+}
+/**
+ * Write-routing graph façade. Construct one per analyze run, thread it into the
+ * per-language `runScopeResolution` calls in place of the real graph during the
+ * `--pdg` emit, then {@link finalize} once after the last language.
+ */
+export declare class PdgEmitSink implements KnowledgeGraph {
+    private readonly real;
+    private readonly pdgCsvDir;
+    private readonly chunkRows;
+    private readonly validTables;
+    private bbWriter;
+    /** pairKey (`From|To`) → writer. PDG edges are all `BasicBlock|BasicBlock`,
+     *  but the map keeps the sink general and the manifest pair-keyed. */
+    private readonly relWriters;
+    private finalized;
+    /**
+     * First writer-construction failure (a `fs.openSync` throwing on e.g. EMFILE
+     * — out of file descriptors). The failure happens inside the `SyncCsvWriter`
+     * constructor before a writer object exists to carry poison, so it is held
+     * here at the sink level and folded into the {@link finalize} error check.
+     * Like an in-flight write fault, an open failure mid-emit would otherwise be
+     * swallowed by the emit loop's per-file try/catch and silently drop the rest
+     * of that file's rows (#2202 review #4/#6).
+     */
+    private openFailure;
+    constructor(real: KnowledgeGraph, pdgCsvDir: string, chunkRows?: number);
+    addNode(node: GraphNode): void;
+    addRelationship(relationship: GraphRelationship): void;
+    /** Flush + close every streamed writer and return the COPY manifest. Every
+     *  fd is closed even when a writer is poisoned (its `close` never throws); any
+     *  IO fault — an in-flight write that poisoned a writer, a final-flush failure,
+     *  or a writer-open failure (EMFILE) — is surfaced loudly here so a disk-full
+     *  / out-of-fds run never hands a truncated CSV to the bulk COPY (#2202 review
+     *  #4). The emit loop's per-file try/catch swallows the synchronous throw, so
+     *  this poison check is the backstop that turns a silent partial manifest into
+     *  a hard failure. */
+    finalize(): PdgEmitManifest;
+    /**
+     * Best-effort fd release for the error path — when a language pass throws
+     * before {@link finalize} runs, the caller's `finally` calls this so the
+     * BasicBlock + per-pair fds never leak. Idempotent with finalize via the
+     * `finalized` flag; close errors are swallowed because the run is already
+     * failing.
+     */
+    close(): void;
+    get nodes(): GraphNode[];
+    get relationships(): GraphRelationship[];
+    iterNodes(): IterableIterator<GraphNode>;
+    iterRelationships(): IterableIterator<GraphRelationship>;
+    iterRelationshipsByType(type: RelationshipType): IterableIterator<GraphRelationship>;
+    forEachNode(fn: (node: GraphNode) => void): void;
+    forEachRelationship(fn: (rel: GraphRelationship) => void): void;
+    getNode(id: string): GraphNode | undefined;
+    get nodeCount(): number;
+    get relationshipCount(): number;
+    removeNode(nodeId: string): boolean;
+    removeNodesByFile(filePath: string): number;
+    removeRelationship(relationshipId: string): boolean;
+}

package/dist/core/lbug/pdg-emit-sink.js

@@ -0,0 +1,358 @@
+/**
+ * Streaming PDG graph-emit sink (issue #2202).
+ *
+ * The PDG emit loop (`scope-resolution/pipeline/run.ts`, the `--pdg` block)
+ * materializes BasicBlock nodes + intra-file PDG edges (CFG / REACHING_DEF /
+ * CDG / POST_DOMINATE / TAINTED / SANITIZES) into the in-memory
+ * `KnowledgeGraph`. At full-kernel scale that layer dominates peak RSS
+ * (~7 GB at 511K BasicBlocks; ~100 GB extrapolated to the full kernel → OOM).
+ *
+ * `PdgEmitSink` is a write-routing façade over the real graph: the emit
+ * functions are write-only and compute every edge endpoint by deterministic id
+ * (audited — no read-back), so the sink can route BasicBlock node rows and PDG
+ * edge rows straight to bounded CSV-on-disk writers and **never store them**.
+ * The graph's resident size stops growing with the PDG layer → peak RSS becomes
+ * O(chunk buffer), not O(graph). Everything else (structural nodes/edges, the
+ * whole-program M4 TAINT_PATH edges) is delegated to the real graph unchanged.
+ *
+ * Why synchronous writers? The whole PDG emit (`runScopeResolution` and its
+ * per-file loop) is synchronous — there is no `await` point to drain an async
+ * stream, so a `BufferedCSVWriter` (Node `WriteStream`) would accumulate
+ * unwritten chunks in process memory across millions of rows, defeating the RSS
+ * bound. `fs.writeSync` goes straight to the OS; resident memory is bounded to
+ * one `chunkRows` buffer. This mirrors the sync-shard pattern in
+ * `storage/parsedfile-store.ts`.
+ *
+ * Byte-identity (issue acceptance): the sink reuses the SAME shared row
+ * builders (`buildBasicBlockRow`, `buildRelRow`) and label derivation
+ * (`getNodeLabel`) as `streamAllCSVsToDisk`, so the streamed CSV line SET is
+ * identical to the whole-graph emit's, and the bulk COPY loads the same rows →
+ * the persisted graph is SET-identical and DB-identical. The guarantee is
+ * set-level, not byte-level on the CSV file: the sink streams rows in emit
+ * order and does NOT re-sort them under `GITNEXUS_SORT_GRAPH_OUTPUT`, so a
+ * streamed CSV file is not necessarily byte-for-byte equal to the sorted
+ * whole-graph CSV — but the row set, and therefore the DB outcome, is. (The
+ * streamed CSVs are deleted right after the COPY, so their on-disk byte order
+ * is never observed.) Cross-pass dedup is done upstream, per FILE, in the emit
+ * loop (`run.ts` skips a file whose PDG already streamed) rather than in the
+ * sink, because a file can be PDG-emitted in more than one language pass (a
+ * `.ts` module imported by a `.vue` SFC is emitted in both the TypeScript and
+ * Vue context passes over the same worker-built CFG) and a sink-level per-id
+ * dedup set would retain every id → O(total ids) memory, defeating the
+ * O(chunk) RSS bound (#2202 review #1). The differential fingerprint test
+ * (issue #2202 U6) and the Vue+TS cross-pass integration test guard the set.
+ */
+import fs from 'fs';
+import path from 'path';
+import { BASICBLOCK_CSV_HEADER, REL_CSV_HEADER, buildBasicBlockRow, buildRelRow, } from './csv-generator.js';
+import { getNodeLabel } from './rel-pair-routing.js';
+import { NODE_TABLES } from './schema.js';
+/**
+ * PDG edge types streamed per-file (all intra-block BasicBlock→BasicBlock).
+ * `TAINT_PATH` is intentionally excluded — it is the whole-program M4 edge
+ * (Function→Function), computed in a separate post-resolution phase over the
+ * complete CALLS graph, and stays in the in-memory graph (it is small and is
+ * persisted by the normal whole-graph emit).
+ */
+const PDG_EDGE_TYPES = new Set([
+    'CFG',
+    'REACHING_DEF',
+    'CDG',
+    'POST_DOMINATE',
+    'TAINTED',
+    'SANITIZES',
+]);
+/** Default streamed-write buffer (rows). Matches the whole-graph emit's
+ *  `FLUSH_EVERY` order of magnitude; overridable via `GITNEXUS_PDG_EMIT_CHUNK_SIZE`. */
+export const DEFAULT_PDG_EMIT_CHUNK_ROWS = 500;
+/**
+ * Synchronous buffered CSV writer. Buffers up to `chunkRows` rows, then issues
+ * one `fs.writeSync` straight to the OS (no in-process stream buffer). Header
+ * is written into the buffer at construction and is NOT counted in `rows`
+ * (matching `BufferedCSVWriter` semantics, so manifest row counts line up).
+ */
+class SyncCsvWriter {
+    csvPath;
+    fd;
+    buf = [];
+    chunkRows;
+    rows = 0;
+    /**
+     * First IO error this writer hit (a `fs.writeSync` short-write loop throwing
+     * on e.g. disk-full). Once poisoned the writer refuses further rows and
+     * skips its final flush; the sink surfaces it from {@link PdgEmitSink.finalize}
+     * so a truncated CSV is never handed to the bulk COPY (#2202 review #4). A
+     * streamed-write failure is an IO fault, not the CFG-logic error that the
+     * emit loop's per-file try/catch is built to swallow — poisoning routes it
+     * past that catch to a loud failure.
+     */
+    poison = undefined;
+    constructor(csvPath, header, chunkRows) {
+        this.csvPath = csvPath;
+        // Guard a 0/negative buffer: the flush modulo would never fire and `buf`
+        // would grow unbounded, defeating the whole point of streaming.
+        this.chunkRows = Math.max(1, chunkRows);
+        // Exclusive create (O_EXCL): the streamed-CSV dir is wiped + recreated fresh
+        // by the PdgEmitSink constructor before any writer opens a file, so the path
+        // never pre-exists — 'wx' both matches that invariant and refuses to follow
+        // a pre-planted symlink at the path (CWE-377 / CodeQL js/insecure-temporary-file).
+        this.fd = fs.openSync(csvPath, 'wx');
+        this.buf.push(header);
+    }
+    addRow(row) {
+        // A poisoned writer is dead — stop buffering so memory can't grow on a
+        // writer whose fd is already in a bad state; finalize will report the fault.
+        if (this.poison !== undefined)
+            return;
+        this.buf.push(row);
+        this.rows++;
+        // Flush on DATA-row count, not buffer length: the header occupies buf[0]
+        // until the first flush, so a `buf.length >= chunkRows` test would fire one
+        // row early on the first chunk. Counting rows makes every flush exactly
+        // `chunkRows` rows.
+        if (this.rows % this.chunkRows === 0)
+            this.flushOrPoison();
+    }
+    /** Flush, recording (and re-throwing) any IO error as poison. Re-throwing
+     *  lets the immediate caller log the per-file failure; the persisted `poison`
+     *  is the backstop that makes finalize fail loudly even when that throw is
+     *  swallowed by the emit loop's CFG try/catch. */
+    flushOrPoison() {
+        try {
+            this.flush();
+        }
+        catch (e) {
+            this.poison ??= e;
+            throw e;
+        }
+    }
+    flush() {
+        if (this.buf.length === 0)
+            return;
+        const data = Buffer.from(this.buf.join('\n') + '\n', 'utf8');
+        // fs.writeSync can return a short byte count; loop until the whole buffer
+        // lands so a partial write never truncates a CSV row mid-field.
+        let offset = 0;
+        while (offset < data.length) {
+            offset += fs.writeSync(this.fd, data, offset, data.length - offset);
+        }
+        this.buf.length = 0;
+    }
+    /** Flush remaining rows (unless already poisoned) and close the fd. Never
+     *  throws: a final-flush IO error is recorded as poison and the fd is still
+     *  closed, so a write error neither leaks an fd nor escapes here — the sink
+     *  reads {@link poison} after closing every writer and fails loudly then. */
+    close() {
+        try {
+            if (this.poison === undefined)
+                this.flush();
+        }
+        catch (e) {
+            this.poison ??= e;
+        }
+        finally {
+            try {
+                fs.closeSync(this.fd);
+            }
+            catch {
+                /* fd may already be invalid after an IO fault — nothing to recover */
+            }
+        }
+    }
+}
+/**
+ * Write-routing graph façade. Construct one per analyze run, thread it into the
+ * per-language `runScopeResolution` calls in place of the real graph during the
+ * `--pdg` emit, then {@link finalize} once after the last language.
+ */
+export class PdgEmitSink {
+    real;
+    pdgCsvDir;
+    chunkRows;
+    validTables;
+    bbWriter;
+    /** pairKey (`From|To`) → writer. PDG edges are all `BasicBlock|BasicBlock`,
+     *  but the map keeps the sink general and the manifest pair-keyed. */
+    relWriters = new Map();
+    finalized = false;
+    /**
+     * First writer-construction failure (a `fs.openSync` throwing on e.g. EMFILE
+     * — out of file descriptors). The failure happens inside the `SyncCsvWriter`
+     * constructor before a writer object exists to carry poison, so it is held
+     * here at the sink level and folded into the {@link finalize} error check.
+     * Like an in-flight write fault, an open failure mid-emit would otherwise be
+     * swallowed by the emit loop's per-file try/catch and silently drop the rest
+     * of that file's rows (#2202 review #4/#6).
+     */
+    openFailure = undefined;
+    // NOTE on dedup: the same file can be PDG-emitted in more than one language
+    // pass (e.g. a `.ts` module imported by a `.vue` SFC is emitted in both the
+    // TypeScript pass and the Vue context pass over the same worker-built
+    // `cfgSideChannel`). The in-memory graph dedups that by id (first-writer-wins);
+    // this sink does NOT — to keep peak memory O(write buffer) rather than
+    // O(total ids), cross-pass dedup is done upstream, per FILE, in the emit loop
+    // (`run.ts` skips a file whose PDG already streamed via `pdgEmittedFiles`).
+    // The sink therefore receives each id exactly once and is a faithful
+    // pass-through; it must not be fed duplicate ids.
+    constructor(real, pdgCsvDir, chunkRows = DEFAULT_PDG_EMIT_CHUNK_ROWS) {
+        this.real = real;
+        this.pdgCsvDir = pdgCsvDir;
+        this.chunkRows = chunkRows;
+        this.validTables = new Set(NODE_TABLES);
+        // Clear any streamed CSVs left by a previous (possibly crashed) run so a
+        // later COPY never picks up stale rows.
+        fs.rmSync(pdgCsvDir, { recursive: true, force: true });
+        fs.mkdirSync(pdgCsvDir, { recursive: true });
+    }
+    // ── routed writes ──────────────────────────────────────────────────────────
+    addNode(node) {
+        if (node.label === 'BasicBlock') {
+            if (this.bbWriter === undefined) {
+                try {
+                    this.bbWriter = new SyncCsvWriter(path.join(this.pdgCsvDir, 'basicblock.csv'), BASICBLOCK_CSV_HEADER, this.chunkRows);
+                }
+                catch (e) {
+                    this.openFailure ??= e;
+                    throw e;
+                }
+            }
+            this.bbWriter.addRow(buildBasicBlockRow(node));
+            return;
+        }
+        this.real.addNode(node);
+    }
+    addRelationship(relationship) {
+        if (PDG_EDGE_TYPES.has(relationship.type)) {
+            const fromLabel = getNodeLabel(relationship.sourceId);
+            const toLabel = getNodeLabel(relationship.targetId);
+            // Skip edges whose endpoint labels are not valid node tables — mirrors
+            // `RelPairRouter` exactly so the streamed set matches the whole-graph set.
+            if (!this.validTables.has(fromLabel) || !this.validTables.has(toLabel))
+                return;
+            const pairKey = `${fromLabel}|${toLabel}`;
+            let writer = this.relWriters.get(pairKey);
+            if (writer === undefined) {
+                try {
+                    writer = new SyncCsvWriter(path.join(this.pdgCsvDir, `rel_${fromLabel}_${toLabel}.csv`), REL_CSV_HEADER, this.chunkRows);
+                }
+                catch (e) {
+                    this.openFailure ??= e;
+                    throw e;
+                }
+                this.relWriters.set(pairKey, writer);
+            }
+            writer.addRow(buildRelRow(relationship));
+            return;
+        }
+        this.real.addRelationship(relationship);
+    }
+    /** Flush + close every streamed writer and return the COPY manifest. Every
+     *  fd is closed even when a writer is poisoned (its `close` never throws); any
+     *  IO fault — an in-flight write that poisoned a writer, a final-flush failure,
+     *  or a writer-open failure (EMFILE) — is surfaced loudly here so a disk-full
+     *  / out-of-fds run never hands a truncated CSV to the bulk COPY (#2202 review
+     *  #4). The emit loop's per-file try/catch swallows the synchronous throw, so
+     *  this poison check is the backstop that turns a silent partial manifest into
+     *  a hard failure. */
+    finalize() {
+        if (this.finalized)
+            throw new Error('PdgEmitSink.finalize() called twice');
+        this.finalized = true;
+        const errors = [];
+        if (this.openFailure !== undefined)
+            errors.push(this.openFailure);
+        const nodeFiles = new Map();
+        if (this.bbWriter !== undefined) {
+            this.bbWriter.close();
+            if (this.bbWriter.poison !== undefined)
+                errors.push(this.bbWriter.poison);
+            nodeFiles.set('BasicBlock', {
+                csvPath: this.bbWriter.csvPath,
+                rows: this.bbWriter.rows,
+            });
+        }
+        const relsByPair = new Map();
+        for (const [pairKey, writer] of this.relWriters) {
+            writer.close();
+            if (writer.poison !== undefined)
+                errors.push(writer.poison);
+            relsByPair.set(pairKey, { csvPath: writer.csvPath, rows: writer.rows });
+        }
+        if (errors.length > 0) {
+            const first = errors[0];
+            throw new Error(`PdgEmitSink: ${errors.length} streamed CSV writer(s) hit an IO error ` +
+                `(disk-full / out-of-fds) during the emit — the persisted graph would ` +
+                `be truncated, so the run is failed rather than COPYing a partial CSV: ${first instanceof Error ? first.message : String(first)}`);
+        }
+        return { nodeFiles, relsByPair };
+    }
+    /**
+     * Best-effort fd release for the error path — when a language pass throws
+     * before {@link finalize} runs, the caller's `finally` calls this so the
+     * BasicBlock + per-pair fds never leak. Idempotent with finalize via the
+     * `finalized` flag; close errors are swallowed because the run is already
+     * failing.
+     */
+    close() {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        try {
+            this.bbWriter?.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        for (const writer of this.relWriters.values()) {
+            try {
+                writer.close();
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    // ── delegated reads / non-PDG mutations ─────────────────────────────────────
+    // The PDG emit functions never call these on the routed graph, but the
+    // façade implements the full KnowledgeGraph surface so it is a drop-in for
+    // the emit target and any non-PDG write transparently reaches the real graph.
+    get nodes() {
+        return this.real.nodes;
+    }
+    get relationships() {
+        return this.real.relationships;
+    }
+    iterNodes() {
+        return this.real.iterNodes();
+    }
+    iterRelationships() {
+        return this.real.iterRelationships();
+    }
+    iterRelationshipsByType(type) {
+        return this.real.iterRelationshipsByType(type);
+    }
+    forEachNode(fn) {
+        this.real.forEachNode(fn);
+    }
+    forEachRelationship(fn) {
+        this.real.forEachRelationship(fn);
+    }
+    getNode(id) {
+        return this.real.getNode(id);
+    }
+    get nodeCount() {
+        return this.real.nodeCount;
+    }
+    get relationshipCount() {
+        return this.real.relationshipCount;
+    }
+    removeNode(nodeId) {
+        return this.real.removeNode(nodeId);
+    }
+    removeNodesByFile(filePath) {
+        return this.real.removeNodesByFile(filePath);
+    }
+    removeRelationship(relationshipId) {
+        return this.real.removeRelationship(relationshipId);
+    }
+}

package/dist/core/lbug/pool-adapter.d.ts

@@ -37,6 +37,41 @@ export { realStdoutWrite, realStderrWrite, setActiveStdoutWrite } from '../../mc
  * Call this during long-running operations to prevent the connection from being closed.
  */
 export declare const touchRepo: (repoId: string) => void;
+/**
+ * Acquire one eviction-exemption lease on a repo (LRU + idle timeout) by
+ * incrementing its reference count. The repoId must match the key passed to
+ * initLbug (e.g. group sync leases by handle.id — the same id it inits with).
+ * Leasing a repoId before it enters the pool is allowed and protects the entry
+ * once it is created, but the lease does NOT survive a teardown: closeOne
+ * force-clears the count, so a later re-init of the same repoId starts
+ * unpinned. Each pinRepo MUST be balanced by exactly one release (the repo
+ * stays exempt until the last lease is released). See the pinnedRepos docstring
+ * for the full contract.
+ *
+ * Returns a `release` disposer (mirroring addPoolCloseListener) that releases
+ * THIS lease exactly once — calling it twice is a no-op, so it can never
+ * over-decrement a sibling holder's count. Prefer the disposer
+ * (`const release = pinRepo(id); try { … } finally { release(); }`) so the
+ * pin/release pair is leak-proof; unpinRepo remains available for callers that
+ * pair explicitly.
+ */
+export declare const pinRepo: (repoId: string) => (() => void);
+/**
+ * Release one eviction-exemption lease on a repo. The repo becomes eligible for
+ * automatic eviction again only once its count reaches 0 (the key is deleted).
+ * Idempotent at the floor: releasing a repo with no active lease is a no-op (no
+ * negative counts). Does NOT close the repo's pool.
+ */
+export declare const unpinRepo: (repoId: string) => void;
+/**
+ * Maximum number of repos a bounded multi-repo operation (e.g. group sync's
+ * windowed manifest resolution) should hold resident at once. Equals
+ * MAX_POOL_SIZE today, but exposed under an intent-named accessor so callers
+ * size their working set against "max repos a bounded op should hold" rather
+ * than coupling to the LRU eviction-cap constant, which may be tuned
+ * independently.
+ */
+export declare const getMaxResidentRepos: () => number;
 /**
  * Silence stdout by replacing process.stdout.write with a no-op.
  * Uses a reference counter so nested silence/restore pairs are safe.

package/dist/core/lbug/pool-adapter.js

@@ -39,6 +39,30 @@ const MAX_POOL_SIZE = 5;
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 /** Max connections per repo (caps concurrent queries per repo) */
 const MAX_CONNS_PER_REPO = 8;
+/**
+ * Repos exempt from AUTOMATIC eviction (LRU + idle timeout) until explicitly
+ * unpinned. Used by bounded multi-repo operations like `group sync`, which
+ * initializes one pool per repo and then resolves cross-repo manifest/workspace
+ * links against ALL of those pools after the init loop. Without pinning, a
+ * group larger than MAX_POOL_SIZE would LRU-evict the earliest repos before
+ * resolution runs, leaving the deferred executor closures pointing at dead pool
+ * entries (issue #2189).
+ *
+ * Pins are REFERENCE-COUNTED: the map holds repoId → active lease count. This
+ * lets overlapping holders (two windows of one sync, or two concurrent
+ * `group sync` calls sharing a repo) coexist safely — the repo stays exempt
+ * until the LAST holder releases. A boolean Set could not represent "two
+ * holders," so the first release would wrongly clear a pin another holder still
+ * needs (PR #2191 review, Finding 1).
+ *
+ * Pins block only automatic eviction (LRU + idle). Explicit teardown
+ * (closeOne / closeLbug) always closes the entry and force-clears its count —
+ * teardown is authoritative. A present key always means count ≥ 1. While every
+ * pooled repo is pinned, evictLRU finds no eligible victim and the pool may
+ * transiently exceed MAX_POOL_SIZE — the same soft-cap behavior that already
+ * occurs when every entry is checked out.
+ */
+const pinnedRepos = new Map();
 // Behavior-neutral RSS tracing for the FTS evict→reload memory repro
 // (gitnexus/scripts/bench/fts-evict-reload-rss.mjs). Two invariants keep it safe
 // in the pool init/close hot path: it writes ONLY to stderr (stdout is the MCP
@@ -77,6 +101,8 @@ function ensureIdleTimer() {
     idleTimer = setInterval(() => {
         const now = Date.now();
         for (const [repoId, entry] of pool) {
+            if (pinnedRepos.has(repoId))
+                continue;
             if (now - entry.lastUsed > IDLE_TIMEOUT_MS && entry.checkedOut === 0) {
                 closeOne(repoId);
             }
@@ -97,7 +123,64 @@ export const touchRepo = (repoId) => {
     }
 };
 /**
- * Evict the least-recently-used repo if pool is at capacity
+ * Acquire one eviction-exemption lease on a repo (LRU + idle timeout) by
+ * incrementing its reference count. The repoId must match the key passed to
+ * initLbug (e.g. group sync leases by handle.id — the same id it inits with).
+ * Leasing a repoId before it enters the pool is allowed and protects the entry
+ * once it is created, but the lease does NOT survive a teardown: closeOne
+ * force-clears the count, so a later re-init of the same repoId starts
+ * unpinned. Each pinRepo MUST be balanced by exactly one release (the repo
+ * stays exempt until the last lease is released). See the pinnedRepos docstring
+ * for the full contract.
+ *
+ * Returns a `release` disposer (mirroring addPoolCloseListener) that releases
+ * THIS lease exactly once — calling it twice is a no-op, so it can never
+ * over-decrement a sibling holder's count. Prefer the disposer
+ * (`const release = pinRepo(id); try { … } finally { release(); }`) so the
+ * pin/release pair is leak-proof; unpinRepo remains available for callers that
+ * pair explicitly.
+ */
+export const pinRepo = (repoId) => {
+    pinnedRepos.set(repoId, (pinnedRepos.get(repoId) ?? 0) + 1);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        unpinRepo(repoId);
+    };
+};
+/**
+ * Release one eviction-exemption lease on a repo. The repo becomes eligible for
+ * automatic eviction again only once its count reaches 0 (the key is deleted).
+ * Idempotent at the floor: releasing a repo with no active lease is a no-op (no
+ * negative counts). Does NOT close the repo's pool.
+ */
+export const unpinRepo = (repoId) => {
+    const count = pinnedRepos.get(repoId);
+    if (count === undefined)
+        return;
+    if (count <= 1) {
+        pinnedRepos.delete(repoId);
+    }
+    else {
+        pinnedRepos.set(repoId, count - 1);
+    }
+};
+/**
+ * Maximum number of repos a bounded multi-repo operation (e.g. group sync's
+ * windowed manifest resolution) should hold resident at once. Equals
+ * MAX_POOL_SIZE today, but exposed under an intent-named accessor so callers
+ * size their working set against "max repos a bounded op should hold" rather
+ * than coupling to the LRU eviction-cap constant, which may be tuned
+ * independently.
+ */
+export const getMaxResidentRepos = () => MAX_POOL_SIZE;
+/**
+ * Evict the least-recently-used repo if pool is at capacity.
+ * Pinned repos are never chosen as the eviction victim — when every eligible
+ * entry is pinned, no eviction occurs and the pool transiently exceeds
+ * MAX_POOL_SIZE (see the pinnedRepos docstring).
  */
 function evictLRU() {
     if (pool.size < MAX_POOL_SIZE)
@@ -105,6 +188,8 @@ function evictLRU() {
     let oldestId = null;
     let oldestTime = Infinity;
     for (const [id, entry] of pool) {
+        if (pinnedRepos.has(id))
+            continue;
         if (entry.checkedOut === 0 && entry.lastUsed < oldestTime) {
             oldestTime = entry.lastUsed;
             oldestId = id;
@@ -167,6 +252,10 @@ function closeOne(repoId) {
         }
     }
     pool.delete(repoId);
+    // Clear any eviction pin — the entry is gone, so the pin is meaningless and
+    // would otherwise leak across operations in a long-lived process. Teardown
+    // is authoritative: an explicit close always wins over a pin.
+    pinnedRepos.delete(repoId);
     // Notify listeners AFTER the pool entry is gone so any cache-invalidation
     // they perform is consistent with `isLbugReady(repoId) === false`.
     for (const listener of poolCloseListeners) {