gitnexus 1.6.6-rc.99 → 1.6.6

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

@@ -7,6 +7,7 @@ import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
 import lbug from '@ladybugdb/core';
+import { closeQueryResults } from './query-result-utils.js';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { extensionManager } from './extension-loader.js';
@@ -153,8 +154,19 @@ const DB_LOCK_RETRY_DELAY_MS = 500;
  * analyze` and either already happened or will happen on the next run.
  */
 export const isReadOnlyDbError = (err) => {
-    const msg = err instanceof Error ? err.message : String(err);
-    return /read-only database/i.test(msg);
+    // Walk the `cause` chain (bounded) so a wrapped read-only error — e.g. the
+    // pool adapter's `new Error('…read-only.', { cause: nativeReadOnlyErr })` —
+    // is still detected by callers that only see the wrapper (#2068 follow-up).
+    // The same strict regex is re-applied at each level, so a non-read-only
+    // chain stays false; the depth bound guards a cyclic `cause`.
+    let cur = err;
+    for (let depth = 0; depth < 5 && cur != null; depth++) {
+        const msg = cur instanceof Error ? cur.message : String(cur);
+        if (/read-only database/i.test(msg))
+            return true;
+        cur = cur instanceof Error ? cur.cause : undefined;
+    }
+    return false;
 };
 const isMissingFileError = (err) => {
     const errno = err;
@@ -301,13 +313,10 @@ const runWithSessionLock = async (operation) => {
     }
 };
 const normalizeCopyPath = (filePath) => toNativeSafePath(filePath).replace(/\\/g, '/');
+// Single-result convenience wrapper over the shared best-effort closer
+// (drainQueryResult / readQueryRows close one cursor at a time).
 const closeQueryResult = async (result) => {
-    try {
-        await result.close();
-    }
-    catch {
-        // Best-effort cleanup only.
-    }
+    await closeQueryResults(result);
 };
 const drainQueryResult = async (queryResult) => {
     const results = Array.isArray(queryResult) ? queryResult : [queryResult];
@@ -1544,8 +1553,9 @@ export const queryImporters = async (targetFilePath) => {
     WHERE r.type = 'IMPORTS' AND b.filePath = '${escaped}'
     RETURN DISTINCT a.filePath AS importer
   `;
+    let queryResult;
     try {
-        const queryResult = await conn.query(cypher);
+        queryResult = await conn.query(cypher);
         const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
         const rows = await result.getAll();
         const out = [];
@@ -1559,6 +1569,10 @@ export const queryImporters = async (targetFilePath) => {
     catch {
         return [];
     }
+    finally {
+        if (queryResult)
+            await closeQueryResults(queryResult);
+    }
 };
 /**
  * Drop every Community and Process node (and their MEMBER_OF /
@@ -1573,8 +1587,9 @@ export const deleteAllCommunitiesAndProcesses = async () => {
     }
     let nodesDeleted = 0;
     for (const label of ['Community', 'Process']) {
+        let countResult;
         try {
-            const countResult = await conn.query(`MATCH (n:${label}) RETURN count(n) AS cnt`);
+            countResult = await conn.query(`MATCH (n:${label}) RETURN count(n) AS cnt`);
             const result = Array.isArray(countResult) ? countResult[0] : countResult;
             const rows = await result.getAll();
             const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0);
@@ -1586,6 +1601,10 @@ export const deleteAllCommunitiesAndProcesses = async () => {
         catch {
             // Table may not exist yet on a freshly-initialized DB — fine.
         }
+        finally {
+            if (countResult)
+                await closeQueryResults(countResult);
+        }
     }
     return { nodesDeleted };
 };

package/dist/core/lbug/native-check.js

@@ -36,11 +36,18 @@ export function checkLbugNative(overridePkgDir) {
                 'To repair:',
                 `  node ${path.join(pkgDir, 'install.js')}`,
                 '',
-                'If using bun, add to package.json and reinstall:',
-                '  "trustedDependencies": ["@ladybugdb/core"]',
-                '',
-                'Also check that npm is not configured with ignore-scripts=true',
-                '(in .npmrc or via --ignore-scripts).',
+                'Common causes:',
+                '  - pnpm dlx / pnpx skip build scripts by default (security model). Options:',
+                '      # Keep pnpm dlx — explicitly allow the required builds:',
+                '      pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter \\',
+                '        dlx gitnexus@latest serve',
+                '      # Or install globally with build scripts allowed (pnpm 10.2+):',
+                '      pnpm add -g --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter gitnexus',
+                '      # Or npm i -g gitnexus@latest (bare npx on npm 11 may crash before gitnexus runs).',
+                '  - bun: add to package.json and reinstall:',
+                '      "trustedDependencies": ["@ladybugdb/core"]',
+                '  - npm configured with ignore-scripts=true',
+                '    (in .npmrc or via --ignore-scripts).',
             ].join('\n'),
         };
     }
@@ -62,6 +69,11 @@ export function checkLbugNative(overridePkgDir) {
                 'To repair:',
                 `  node ${path.join(pkgDir, 'install.js')}`,
                 '',
+                'If install scripts were skipped (pnpm dlx / pnpx / ignore-scripts):',
+                '  pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter \\',
+                '    dlx gitnexus@latest serve',
+                '  pnpm add -g --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter gitnexus',
+                '',
                 'If using bun, add to package.json and reinstall:',
                 '  "trustedDependencies": ["@ladybugdb/core"]',
             ].join('\n'),

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

@@ -15,25 +15,6 @@
  * from the same Database is the officially supported concurrency pattern.
  */
 import lbug from '@ladybugdb/core';
-/**
- * Probe whether a Windows FTS extension binary is locally installed under
- * ~/.lbdb/extension/<any-version>/win_amd64/fts/. Returns true on the first
- * version dir whose libfts.lbug_extension exists on disk; false if the
- * extension root is missing or contains no FTS binary.
- *
- * Gates the Windows skip-FTS-load guard below so we only skip the load
- * when no extension binary is present. When at least one binary exists,
- * loadFTSExtension is called with policy: 'load-only' — LadybugDB resolves
- * LOAD EXTENSION fts to its version-specific path internally, and the
- * ExtensionManager's tryLoad try/catch handles version-mismatch errors
- * cleanly without ever attempting dlopen of a stale binary. The install
- * path that the #1199/#1217 SIGSEGV documented is never exercised at
- * query time.
- *
- * Exported so unit tests can exercise the probe directly against a
- * temp-dir plus spied `os.homedir()` — see lbug-pool-win-fts-probe.test.ts.
- */
-export declare function hasLocalWinFtsExtension(): Promise<boolean>;
 /**
  * Listeners notified when a pool entry is torn down (LRU eviction, idle
  * timeout, explicit close). Used by upper layers (e.g. the BM25 search

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

@@ -15,49 +15,11 @@
  * from the same Database is the officially supported concurrency pattern.
  */
 import fs from 'fs/promises';
-import os from 'os';
-import path from 'path';
 import lbug from '@ladybugdb/core';
 import { isReadOnlyDbError, loadFTSExtension } from './lbug-adapter.js';
+import { closeQueryResults } from './query-result-utils.js';
 import { createLbugDatabase, isWalCorruptionError, toNativeSafePath, WAL_RECOVERY_SUGGESTION, } from './lbug-config.js';
 import { isMissingFsError, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, statIfExists, } from './sidecar-recovery.js';
-/**
- * Probe whether a Windows FTS extension binary is locally installed under
- * ~/.lbdb/extension/<any-version>/win_amd64/fts/. Returns true on the first
- * version dir whose libfts.lbug_extension exists on disk; false if the
- * extension root is missing or contains no FTS binary.
- *
- * Gates the Windows skip-FTS-load guard below so we only skip the load
- * when no extension binary is present. When at least one binary exists,
- * loadFTSExtension is called with policy: 'load-only' — LadybugDB resolves
- * LOAD EXTENSION fts to its version-specific path internally, and the
- * ExtensionManager's tryLoad try/catch handles version-mismatch errors
- * cleanly without ever attempting dlopen of a stale binary. The install
- * path that the #1199/#1217 SIGSEGV documented is never exercised at
- * query time.
- *
- * Exported so unit tests can exercise the probe directly against a
- * temp-dir plus spied `os.homedir()` — see lbug-pool-win-fts-probe.test.ts.
- */
-export async function hasLocalWinFtsExtension() {
-    try {
-        const extRoot = path.join(os.homedir(), '.lbdb', 'extension');
-        const versions = await fs.readdir(extRoot);
-        for (const v of versions) {
-            try {
-                await fs.stat(path.join(extRoot, v, 'win_amd64', 'fts', 'libfts.lbug_extension'));
-                return true;
-            }
-            catch {
-                /* missing for this version, keep looking */
-            }
-        }
-    }
-    catch {
-        /* no .lbdb/extension dir */
-    }
-    return false;
-}
 const pool = new Map();
 const poolCloseListeners = new Set();
 /**
@@ -151,6 +113,18 @@ function closeOne(repoId) {
     if (!entry)
         return;
     entry.closed = true;
+    // Reject any callers still queued for a connection: the pool is going away
+    // (re-init / teardown / LRU eviction), so they must fail fast with an
+    // actionable error instead of hanging until WAITER_TIMEOUT_MS and then
+    // surfacing a misleading "pool exhausted" (#2068 follow-up). Draining the
+    // queue also guarantees checkin() below finds no waiter expecting a
+    // connection, so a connection returned after close is simply closed.
+    if (entry.waiters.length > 0) {
+        const closedErr = new Error(`LadybugDB connection pool closed for repo "${repoId}" (re-init/teardown); retry the query.`);
+        for (const waiter of entry.waiters)
+            waiter.reject(closedErr);
+        entry.waiters.length = 0;
+    }
     // Close available connections — fire-and-forget with .catch() to prevent
     // unhandled rejections.  Native close() returns Promise<void> but can crash
     // the N-API destructor on macOS/Windows; deferring to process exit lets
@@ -522,28 +496,7 @@ async function doInitLbug(repoId, dbPath) {
     // install; analyze owns extension installation. If LOAD fails, search
     // features degrade gracefully and the user-facing query path proceeds.
     if (!shared.ftsLoaded) {
-        // Windows guard: LOAD EXTENSION fts crashes with SIGSEGV on Windows during
-        // *install* — the @ladybugdb/core out-of-process installer hits an unhandled
-        // error path that signals SIGSEGV instead of throwing (see #1199, #1217).
-        // The previous unconditional skip was over-broad: it also disabled FTS on
-        // hosts where the binary was already on disk and only needed LOAD, leaving
-        // BM25 silently degraded with no error path (see #1690).
-        //
-        // Probe ~/.lbdb/extension/*/win_amd64/fts/ first. If any binary is on disk
-        // we run loadFTSExtension(..., 'load-only'); the install path is never
-        // exercised, and LadybugDB's version-specific resolution + ExtensionManager
-        // try/catch handle stale/zero-byte siblings cleanly (verified empirically
-        // on Win10 + Node 22.19 + gitnexus 1.6.5 + @ladybugdb/core 0.16.1). With
-        // no binary at all, we fall back to the upstream skip so install-time
-        // SIGSEGV continues to be avoided.
-        if (process.platform === 'win32') {
-            shared.ftsLoaded = (await hasLocalWinFtsExtension())
-                ? await loadFTSExtension(available[0], { policy: 'load-only' })
-                : true;
-        }
-        else {
-            shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
-        }
+        shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
     }
     // Register pool entry only after all connections are pre-warmed and FTS is
     // loaded.  Concurrent executeQuery calls see either "not initialized"
@@ -599,16 +552,8 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     // Load FTS extension if not already loaded on this Database.
     // policy: 'load-only' — same contract as initLbug above; the read pool
     // must not block on a network install during query execution.
-    // Windows guard: same probe-then-load policy as doInitLbug above.
     if (!shared.ftsLoaded) {
-        if (process.platform === 'win32') {
-            shared.ftsLoaded = (await hasLocalWinFtsExtension())
-                ? await loadFTSExtension(available[0], { policy: 'load-only' })
-                : true;
-        }
-        else {
-            shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
-        }
+        shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
     }
     pool.set(repoId, {
         db: existingDb,
@@ -643,15 +588,21 @@ function checkout(entry) {
     }
     // At capacity — queue the caller with a timeout.
     return new Promise((resolve, reject) => {
-        const waiter = (conn) => {
-            clearTimeout(timer);
-            resolve(conn);
+        const waiter = {
+            resolve: (conn) => {
+                clearTimeout(timer);
+                resolve(conn);
+            },
+            reject: (err) => {
+                clearTimeout(timer);
+                reject(err);
+            },
         };
         const timer = setTimeout(() => {
             const idx = entry.waiters.indexOf(waiter);
             if (idx !== -1)
                 entry.waiters.splice(idx, 1);
-            reject(new Error(`Connection pool exhausted: timed out after ${WAITER_TIMEOUT_MS}ms waiting for a free connection`));
+            waiter.reject(new Error(`Connection pool exhausted: timed out after ${WAITER_TIMEOUT_MS}ms waiting for a free connection`));
         }, WAITER_TIMEOUT_MS);
         entry.waiters.push(waiter);
     });
@@ -672,7 +623,7 @@ function checkin(entry, conn) {
     if (entry.waiters.length > 0) {
         // Hand directly to the next waiter — no intermediate available state
         const waiter = entry.waiters.shift();
-        waiter(conn);
+        waiter.resolve(conn);
     }
     else {
         entry.checkedOut--;
@@ -707,24 +658,36 @@ export const executeParameterized = async (repoId, cypher, params) => {
     const conn = await checkout(entry);
     silenceStdout();
     activeQueryCount++;
+    let queryResult;
     try {
         const stmt = await withTimeout(conn.prepare(cypher), QUERY_TIMEOUT_MS, 'Prepare');
         if (!stmt.isSuccess()) {
             const errMsg = await stmt.getErrorMessage();
             throw new Error(`Prepare failed: ${errMsg}`);
         }
-        const queryResult = await withTimeout(conn.execute(stmt, params), QUERY_TIMEOUT_MS, 'Execute');
+        queryResult = await withTimeout(conn.execute(stmt, params), QUERY_TIMEOUT_MS, 'Execute');
         const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
         const rows = await result.getAll();
         return rows;
     }
     catch (err) {
         if (isReadOnlyDbError(err)) {
-            throw new Error('Write operations are not allowed. The pool adapter is read-only.');
+            // Preserve the native error as `cause` so the original frame/message is
+            // not lost behind the friendly read-only message (#2068 follow-up).
+            throw new Error('Write operations are not allowed. The pool adapter is read-only.', {
+                cause: err,
+            });
         }
         throw err;
     }
     finally {
+        // Close the native QueryResult cursor(s) before returning the connection —
+        // getAll() drains rows but does not release the native cursor, so without
+        // this the cursor leaks for the connection's lifetime (#2068 follow-up).
+        // Best-effort via the shared helper; never masks the query result or a real
+        // error.
+        if (queryResult)
+            await closeQueryResults(queryResult);
         activeQueryCount--;
         restoreStdout();
         checkin(entry, conn);

package/dist/core/lbug/query-result-utils.d.ts

@@ -0,0 +1,19 @@
+import lbug from '@ladybugdb/core';
+/**
+ * Best-effort close of one or more native `QueryResult` cursors.
+ *
+ * `result.getAll()` materializes rows into a JS array but does not release the
+ * native cursor — leaving it open holds native resources for the connection's
+ * lifetime. Both the pooled adapter (`pool-adapter.ts`) and the direct adapter
+ * (`lbug-adapter.ts`) must release cursors after reading; this is the single
+ * shared implementation so neither re-rolls the array-normalize + swallow loop
+ * (a #2068 follow-up de-dup). Lives in its own leaf module so the two adapters
+ * depend on it rather than on each other.
+ *
+ * `conn.execute()` can return either a single `QueryResult` or an array
+ * (multi-statement); this normalizes both. Each close is independent and
+ * best-effort: a failing or absent `close()` on one cursor never throws and
+ * never prevents the others from closing — a cleanup failure must not mask the
+ * query result or a real error at the call site.
+ */
+export declare function closeQueryResults(queryResult: lbug.QueryResult | lbug.QueryResult[]): Promise<void>;

package/dist/core/lbug/query-result-utils.js

@@ -0,0 +1,28 @@
+/**
+ * Best-effort close of one or more native `QueryResult` cursors.
+ *
+ * `result.getAll()` materializes rows into a JS array but does not release the
+ * native cursor — leaving it open holds native resources for the connection's
+ * lifetime. Both the pooled adapter (`pool-adapter.ts`) and the direct adapter
+ * (`lbug-adapter.ts`) must release cursors after reading; this is the single
+ * shared implementation so neither re-rolls the array-normalize + swallow loop
+ * (a #2068 follow-up de-dup). Lives in its own leaf module so the two adapters
+ * depend on it rather than on each other.
+ *
+ * `conn.execute()` can return either a single `QueryResult` or an array
+ * (multi-statement); this normalizes both. Each close is independent and
+ * best-effort: a failing or absent `close()` on one cursor never throws and
+ * never prevents the others from closing — a cleanup failure must not mask the
+ * query result or a real error at the call site.
+ */
+export async function closeQueryResults(queryResult) {
+    const results = Array.isArray(queryResult) ? queryResult : [queryResult];
+    for (const r of results) {
+        try {
+            await r?.close();
+        }
+        catch {
+            // Best-effort cleanup only.
+        }
+    }
+}

package/dist/core/run-analyze.d.ts

@@ -48,6 +48,13 @@ export interface AnalyzeOptions {
     noStats?: boolean;
     /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
     skipSkills?: boolean;
+    /**
+     * Default branch threaded into generated AGENTS.md / CLAUDE.md so the
+     * regression-compare example uses the configured branch instead of a
+     * hardcoded "main" (#243). Resolved by the CLI; `undefined` here keeps the
+     * "main" fallback for non-CLI callers (e.g. the server analyze worker).
+     */
+    defaultBranch?: string;
     /**
      * User-provided alias for the registry `name` (#829). When set,
      * forwarded to `registerRepo` so the indexed repo is stored under
@@ -67,8 +74,8 @@ export interface AnalyzeOptions {
      * Worker pool size override, threaded from the CLI `--workers` flag.
      * Forwarded to `PipelineOptions.workerPoolSize` so the parse phase
      * sizes the pool without `analyzeCommand` mutating `process.env`.
-     * `0` disables the pool (sequential fallback); positive integer sets
-     * the count; `undefined` defers to the env / auto-formula fallback.
+     * Must be a positive integer — `0` hard-errors (sequential parsing was
+     * removed); `undefined` defers to the env / auto-formula fallback.
      */
     workerPoolSize?: number;
 }

package/dist/core/run-analyze.js

@@ -12,6 +12,7 @@ import path from 'path';
 import fs from 'fs/promises';
 import { execFileSync } from 'child_process';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
+import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
 import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
@@ -20,7 +21,8 @@ import { getStoragePaths, saveMeta, loadMeta, ensureGitNexusIgnored, registerRep
 import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js';
 import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental/subgraph-extract.js';
 import { shadowCandidatesFor } from './incremental/shadow-candidates.js';
-import { loadParseCache, saveParseCache, pruneCache } from '../storage/parse-cache.js';
+import { loadParseCache, saveParseCache, pruneCache, PARSE_CACHE_VERSION, } from '../storage/parse-cache.js';
+import { getDurableParsedFileDir, pruneAndSaveDurableParsedFileStore, } from '../storage/parsedfile-store.js';
 import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName, resolveRepoIdentityRoot, } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
@@ -71,6 +73,13 @@ export const PHASE_LABELS = {
 export async function runFullAnalysis(repoPath, options, callbacks) {
     const log = (msg) => callbacks.onLog?.(msg);
     const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
+    // Scope the degraded-parse log throttle to this run. On a reused process
+    // (e.g. tests, or any host that calls runFullAnalysis more than once) the
+    // module-level counter would otherwise stay saturated and suppress every
+    // degraded-parse log after the first run. The per-parse worker holds its own
+    // counter in its own module instance and is process-scoped, so no separate
+    // worker-side reset is needed (see safe-parse.ts ParseTimeoutError contract).
+    resetDegradedParseCounter();
     const { storagePath, lbugPath } = getStoragePaths(repoPath);
     // Clean up stale KuzuDB files from before the LadybugDB migration.
     const kuzuResult = await cleanupOldKuzuFiles(storagePath);
@@ -296,7 +305,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             ? `${p.message || phaseLabel} (${p.detail})`
             : p.message || phaseLabel;
         progress(p.phase, scaled, message);
-    }, { parseCache, workerPoolSize: options.workerPoolSize });
+    }, {
+        parseCache,
+        workerPoolSize: options.workerPoolSize,
+    });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('lbug', 60, 'Loading into LadybugDB...');
     // Compute current per-file content hashes from the pipeline's File nodes.
@@ -726,7 +738,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             if (pruned > 0) {
                 log(`Parse cache: pruned ${pruned} stale chunk entries`);
             }
-            await saveParseCache(storagePath, parseCache);
+            const savedKeys = await saveParseCache(storagePath, parseCache);
+            // Prune the durable ParsedFile store to EXACTLY the parse cache's
+            // surviving keys (#2038 warm-cache coverage), so the two content-addressed
+            // stores stay coherent: a chunk is "cached" iff both its parse-cache shard
+            // and its durable shards exist. A quarantined chunk (in usedKeys but with
+            // no parse-cache shard) drops its durable subdir here and re-dispatches
+            // next run. Same try/catch — a durable-store write failure must never
+            // break an otherwise successful run (next run treats it as a miss).
+            await pruneAndSaveDurableParsedFileStore(getDurableParsedFileDir(storagePath), PARSE_CACHE_VERSION, new Set(savedKeys));
         }
         catch (e) {
             log(`Warning: could not save parse cache (${e.message}); continuing.`);
@@ -768,6 +788,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 skipAgentsMd: options.skipAgentsMd,
                 skipSkills: options.skipSkills,
                 noStats: options.noStats,
+                defaultBranch: options.defaultBranch,
             });
         }
         catch {

package/dist/core/tree-sitter/parser-loader.d.ts

@@ -1,5 +1,18 @@
 import Parser from 'tree-sitter';
 import { SupportedLanguages } from '../../_shared/index.js';
+/**
+ * Introspection over the grammar registry for the ABI load-smoke test
+ * (`test/unit/parser-loader-abi.test.ts`, #1922). Returns one descriptor per
+ * `SOURCES` row — including the `:tsx` variant — so the smoke can assert that
+ * EVERY registered grammar loads (required) or "loads OR cleanly reports
+ * unavailable" (optional/vendored). Derived from `SOURCES` so adding a grammar
+ * automatically widens the smoke's coverage with no second list to maintain.
+ */
+export interface GrammarSourceDescriptor {
+    key: string;
+    optional: boolean;
+}
+export declare const listGrammarSources: () => GrammarSourceDescriptor[];
 export declare const resolveLanguageKey: (language: SupportedLanguages, filePath?: string) => string;
 export declare const isLanguageAvailable: (language: SupportedLanguages, filePath?: string) => boolean;
 export declare const getLanguageGrammar: (language: SupportedLanguages, filePath?: string) => unknown;

package/dist/core/tree-sitter/parser-loader.js

@@ -106,6 +106,10 @@ const SOURCES = {
             'and is not installed (or its native binding failed to build).',
     },
 };
+export const listGrammarSources = () => Object.entries(SOURCES).map(([key, source]) => ({
+    key,
+    optional: source.optional === true,
+}));
 const loadCache = new Map();
 const logged = new Set();
 const logFailure = (key, result) => {

package/dist/core/tree-sitter/safe-parse.d.ts

@@ -1,6 +1,73 @@
 import type Parser from 'tree-sitter';
 /**
- * Parse `sourceText` safely on every platform. See {@link SAFE_PARSE_CHUNK_CHARS}
- * for the underlying tree-sitter binding bug this works around.
+ * Thrown when a parse exceeds its wall-clock budget (see
+ * {@link DEFAULT_PARSE_TIMEOUT_MS}). The parser has already been `reset()` and
+ * its budget cleared by the time this propagates, so callers may safely reuse
+ * the same parser for the next file.
+ *
+ * Hard-skip contract: a timeout is fatal for the offending file but MUST NOT
+ * abort the run. Every caller is responsible for catching this specific error
+ * (`instanceof ParseTimeoutError`), skipping that one file (degrade-and-
+ * continue), and re-throwing anything else. Catching it generically and
+ * swallowing all errors would mask real bugs, so callers match on the type.
  */
-export declare function parseSourceSafe(parser: Parser, sourceText: string, oldTree?: Parser.Tree, options?: Parser.Options): Parser.Tree;
+export declare class ParseTimeoutError extends Error {
+    readonly budgetMs: number;
+    readonly label?: string;
+    constructor(budgetMs: number, label?: string);
+}
+/**
+ * Reset the per-run degraded-parse log throttle. Called at the start of every
+ * analysis run (`runFullAnalysis`) so the first-N-then-suppress budget is
+ * scoped to a single run rather than to the lifetime of the module (which, on
+ * a reused process, would suppress all degraded-parse logs after the first
+ * run). Safe to call at any time.
+ */
+export declare function resetDegradedParseCounter(): void;
+/**
+ * @internal Test-only alias for {@link resetDegradedParseCounter}, kept so the
+ * existing `safe-parse.test.ts` import keeps working. Prefer the public name.
+ */
+export declare function _resetDegradedParseCounter(): void;
+/**
+ * True when the parsed tree contains any ERROR or MISSING node — i.e. the
+ * source did not parse cleanly and tree-sitter applied error recovery.
+ * `parse` never throws on bad syntax (it recovers into ERROR/MISSING nodes),
+ * so this is the only signal callers have that a tree is degraded.
+ */
+export declare function parseHadErrors(tree: Parser.Tree): boolean;
+/**
+ * Structured diagnostics for a parsed tree. Cheap (reads boolean node
+ * properties only); callers that just want a yes/no use {@link parseHadErrors}.
+ */
+export declare function getParseDiagnostics(tree: Parser.Tree): {
+    hasError: boolean;
+    isMissing: boolean;
+};
+/**
+ * Parse `sourceText` safely on every platform.
+ *
+ * This is the single "parse safely" entry point and its contract covers three
+ * concerns:
+ *
+ *  1. **Windows crash workaround.** Inputs longer than 32 767 chars are fed
+ *     through the chunked `Parser.Input` callback overload to dodge the
+ *     0.21.x string-to-buffer SIGSEGV. See {@link SAFE_PARSE_CHUNK_CHARS}.
+ *
+ *  2. **Runaway-parse timeout.** A per-parse budget (default 15 s, env
+ *     `GITNEXUS_PARSE_TIMEOUT_MS`, `0` disables) is armed before parsing on
+ *     both the direct and chunked paths. On timeout the runtime returns
+ *     `null`; this function `reset()`s the parser, clears the budget, and
+ *     throws {@link ParseTimeoutError}. The budget is always cleared in a
+ *     `finally` so it never leaks to the next parse on a reused/singleton
+ *     parser (`loadParser()` and the worker both reuse one `Parser`).
+ *
+ *  3. **Intrinsic error detection.** On a successful parse, a degraded tree
+ *     (`rootNode.hasError`) is logged at `debug` level with throttling, then
+ *     the tree is **returned anyway** — error recovery is a downgrade, never a
+ *     drop. Callers wanting the boolean use {@link parseHadErrors}.
+ *
+ * @param label optional context (e.g. file path) attached to timeout errors
+ *   and degraded-parse logs. Non-breaking trailing param.
+ */
+export declare function parseSourceSafe(parser: Parser, sourceText: string, oldTree?: Parser.Tree, options?: Parser.Options, label?: string): Parser.Tree;