gitnexus 1.6.8-rc.32 → 1.6.8-rc.33

package/dist/core/group/sync.d.ts

@@ -1,5 +1,5 @@
 import { type RegistryEntry } from '../../storage/repo-manager.js';
-import type { GroupConfig, RepoHandle, RepoSnapshot, StoredContract, CrossLink } from './types.js';
+import type { GroupConfig, RepoHandle, RepoSnapshot, StoredContract, CrossLink, GroupManifestLink } from './types.js';
 export interface SyncOptions {
     extractorOverride?: ((repo: RepoHandle) => Promise<StoredContract[]>) | (() => Promise<StoredContract[]>);
     resolveRepoHandle?: (registryName: string, groupPath: string) => Promise<RepoHandle | null>;
@@ -18,4 +18,30 @@ export interface SyncResult {
     repoSnapshots: Record<string, RepoSnapshot>;
 }
 export declare function stableRepoPoolId(entry: RegistryEntry, allEntries: RegistryEntry[]): string;
+/** A batch of manifest links whose referenced in-group repos fit one resident window. */
+export interface ManifestWindow {
+    links: GroupManifestLink[];
+    /** In-group repos (group paths) this window's links reference; size ≤ maxResident. */
+    repos: Set<string>;
+}
+/**
+ * Partition manifest links into windows so each window references at most
+ * `maxResident` distinct in-group repos. Manifest resolution then materializes
+ * only one window's repos at a time, bounding peak pool residency regardless of
+ * group size (PR #2191 review, Finding 3 — windowed deferred resolution).
+ *
+ * Each link references ≤2 in-group repos, so every link fits a window when
+ * `maxResident ≥ 2`. Links are pre-sorted by their referenced-repo key so links
+ * sharing a repo land in contiguous windows — combined with release-not-close
+ * pooling, a hub repo stays warm across the windows that reference it (its
+ * lease is released, not closed, so the next window's initLbug fast-paths it).
+ * Every link lands in EXACTLY one window (a true partition): downstream
+ * dedupeCrossLinks dedupes cross-links but not contracts, so a link in two
+ * windows would emit duplicate contracts nothing absorbs.
+ *
+ * Repos not in `knownRepos` (dangling / unresolved) add 0 to a window's repo
+ * budget — the link is still placed (so it yields synthetic-UID contracts), it
+ * just consumes no residency.
+ */
+export declare function partitionManifestWindows(links: GroupManifestLink[], knownRepos: Set<string>, maxResident: number): ManifestWindow[];
 export declare function syncGroup(config: GroupConfig, opts?: SyncOptions): Promise<SyncResult>;

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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.32",
+  "version": "1.6.8-rc.33",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",