gitnexus 1.6.7 → 1.6.8-rc.10

package/dist/core/run-analyze.js

@@ -17,14 +17,15 @@ import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReuse
 import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
-import { getStoragePaths, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
+import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 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, 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 { getCurrentCommit, getCurrentBranch, getDefaultBranch, getRemoteUrl, hasGitDir, getInferredRepoName, resolveRepoIdentityRoot, } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
+import { sanitizeDetectedBranch } from '../cli/analyze-config.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
 /**
@@ -70,6 +71,63 @@ export const PHASE_LABELS = {
  * the {@link AnalyzeCallbacks} interface — it never writes to stdout/stderr
  * directly and never calls `process.exit()`.
  */
+/**
+ * Build the primary-inversion warning (#2106 R8), or `undefined` when there is
+ * nothing to warn about. Pure + exported for testing. Both inputs are trimmed
+ * (a diagnostic — a missed warning is low-harm; a false warning is the thing to
+ * avoid). `defaultBranch` is the repo's `origin/HEAD` branch (null when unset,
+ * e.g. fresh clones / CI), `flatOwner` is the branch that owns the flat slot.
+ */
+export const primaryInversionWarning = (defaultBranch, flatOwner) => {
+    const norm = (s) => s?.trim() || undefined;
+    const d = norm(defaultBranch);
+    const o = norm(flatOwner);
+    if (!d || !o || d === o)
+        return undefined;
+    return (`Warning: the default branch "${d}" is not the primary index — "${o}" owns the flat slot. ` +
+        `Run \`gitnexus clean --branch ${o}\` then re-index on "${d}", or query it explicitly with \`--branch ${d}\`.`);
+};
+/**
+ * Collect the recorded parse-cache chunk keys across the flat + every branch
+ * meta under a flat `.gitnexus` storage, EXCLUDING `excludeDir` (the current
+ * run's own meta dir) so a single-branch repo collects nothing and its prune
+ * stays byte-identical to today (#2106 R6). `complete` is false when a sibling
+ * meta.json exists but fails to parse — callers then retain the whole shared
+ * cache rather than over-evict another branch's still-live shards. Exported for
+ * testing.
+ */
+export const collectBranchCacheKeys = async (storagePath, excludeDir) => {
+    const keys = new Set();
+    let complete = true;
+    const metaDirs = [storagePath];
+    const branchesDir = path.join(storagePath, 'branches');
+    const slugs = await fs.readdir(branchesDir).catch(() => []);
+    for (const slug of slugs)
+        metaDirs.push(path.join(branchesDir, slug));
+    for (const dir of metaDirs) {
+        if (excludeDir && path.resolve(dir) === path.resolve(excludeDir))
+            continue;
+        let raw;
+        try {
+            raw = await fs.readFile(path.join(dir, 'meta.json'), 'utf-8');
+        }
+        catch {
+            continue; // no meta here — not a branch index, not a failure
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed.cacheKeys)) {
+                for (const k of parsed.cacheKeys)
+                    if (typeof k === 'string')
+                        keys.add(k);
+            }
+        }
+        catch {
+            complete = false; // present but corrupt → fail-safe toward retention
+        }
+    }
+    return { keys, complete };
+};
 export async function runFullAnalysis(repoPath, options, callbacks) {
     const log = (msg) => callbacks.onLog?.(msg);
     const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
@@ -80,7 +138,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // 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);
+    // `storagePath` is ALWAYS the flat `.gitnexus` — content-addressed caches
+    // (parse-cache, parsedfile-store) and the kuzu-migration cleanup live there
+    // and are shared across branches (#2106 KTD7).
+    const { storagePath } = getStoragePaths(repoPath);
     // Clean up stale KuzuDB files from before the LadybugDB migration.
     const kuzuResult = await cleanupOldKuzuFiles(storagePath);
     if (kuzuResult.found && kuzuResult.needsReindex) {
@@ -88,7 +149,53 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }
     const repoHasGit = hasGitDir(repoPath);
     const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
-    const existingMeta = await loadMeta(storagePath);
+    // ── #2106: resolve which branch slot this run writes to ───────────────
+    // `branchLabel` is the branch identity recorded in meta.json (incl. the
+    // primary). `placement.branch` is undefined for the flat/primary slot (the
+    // lbug/meta paths stay byte-identical to single-branch behavior) and set for
+    // a `branches/<slug>/` sub-directory. Explicit `--branch` is always honored;
+    // otherwise auto-detect the checked-out branch (null for detached HEAD /
+    // non-git → flat slot).
+    // Normalize the auto-detected branch the same way an explicit `--branch` is
+    // validated (#2106 R1): a git ref the branch-name rules forbid (backtick,
+    // `~ ^ : ? *`, leading `-`, `..`) becomes `null` → the flat slot, matching
+    // that a later `--branch <that-ref>` query would also be rejected. A normal
+    // ref passes through unchanged so index-time and query-time labels round-trip.
+    const checkedOutBranch = repoHasGit
+        ? (sanitizeDetectedBranch(getCurrentBranch(repoPath)) ?? null)
+        : null;
+    // Analyze indexes the working tree, not an arbitrary ref. An explicit
+    // `--branch X` while a DIFFERENT branch Y is checked out would write Y's
+    // content (and Y's commit) into X's index slot, corrupting X (#2106). Refuse
+    // the mismatch. Detached HEAD / non-git (checkedOutBranch === null) still
+    // allow an explicit label so CI checkouts can name their snapshot.
+    if (options.branch && checkedOutBranch && options.branch !== checkedOutBranch) {
+        throw new Error(`--branch "${options.branch}" does not match the checked-out branch "${checkedOutBranch}". ` +
+            `Check out "${options.branch}" before indexing it, or omit --branch to index the current branch.`);
+    }
+    const branchLabel = options.branch ?? checkedOutBranch;
+    const placement = await resolveBranchPlacement(repoPath, branchLabel);
+    const { lbugPath, metaPath } = getStoragePaths(repoPath, placement.branch);
+    // Directory that owns this run's meta.json (flat `.gitnexus` for the primary
+    // slot, `branches/<slug>/` otherwise). loadMeta/saveMeta operate on it so
+    // each branch keeps its own lastCommit / fileHashes / incremental dirty flag.
+    const metaDir = path.dirname(metaPath);
+    const existingMeta = await loadMeta(metaDir);
+    // ── #2106 (R8): warn when the repo's default branch is not the primary ──
+    // A non-default branch can own the flat slot (it was indexed first). That
+    // index is still fully queryable via `--branch`, so this is an ergonomics
+    // wart, not data loss — we only warn (no risky relocation of a live DB).
+    if (repoHasGit) {
+        // Who owns the flat slot after this run? For a flat/primary run it is this
+        // run's resolved label (carrying an existing stamp forward); for a branch
+        // run the flat owner is unchanged, so read the flat meta.
+        const flatOwner = placement.branch
+            ? (await loadMeta(storagePath))?.branch
+            : (branchLabel ?? existingMeta?.branch);
+        const warning = primaryInversionWarning(getDefaultBranch(repoPath), flatOwner);
+        if (warning)
+            log(warning);
+    }
     // ── FTS-only repair path ────────────────────────────────────────────
     if (options.repairFts) {
         if (!existingMeta) {
@@ -220,6 +327,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     repoPath,
                     stats: existingMeta.stats ?? {},
                     alreadyUpToDate: true,
+                    isPrimaryBranch: !placement.branch,
                 };
             }
         }
@@ -308,6 +416,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }, {
         parseCache,
         workerPoolSize: options.workerPoolSize,
+        fetchWrappers: options.fetchWrappers,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('lbug', 60, 'Loading into LadybugDB...');
@@ -345,8 +454,8 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             `deleted=${hashDiff.deleted.length} ` +
             `(skipping wipe + ${allFilePaths.length - hashDiff.toWrite.length} unchanged file rows preserved)`);
         // Set the dirty flag BEFORE any destructive DB mutation. Cleared on
-        // success at the meta-save step.
-        await saveMeta(storagePath, {
+        // success at the meta-save step. Scoped to this branch's meta.json.
+        await saveMeta(metaDir, {
             ...existingMeta,
             incrementalInProgress: {
                 startedAt: Date.now(),
@@ -685,6 +794,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             repoPath,
             lastCommit: currentCommit,
             indexedAt: new Date().toISOString(),
+            // Branch identity this index represents (#2106). Recorded for the flat
+            // slot too (so resolveBranchPlacement knows which branch owns it). When
+            // the label is null (detached HEAD / non-git re-analyze) we PRESERVE an
+            // existing stamp rather than stripping it — otherwise a detached re-index
+            // of the primary (e.g. CI's `actions/checkout` default) would un-claim the
+            // flat slot and let the next branch analyze overwrite the primary index.
+            // Stays absent only when never stamped (fresh detached/non-git repo).
+            branch: branchLabel ?? existingMeta?.branch,
             // Captured here (not at registration) so it travels with the
             // on-disk meta.json — sibling-clone fingerprinting works for
             // out-of-tree consumers (group-status, future tooling) without
@@ -723,9 +840,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // dirty flag (full and incremental success paths converge here).
             schemaVersion: hasGitDir(repoPath) ? INCREMENTAL_SCHEMA_VERSION : undefined,
             fileHashes: hasGitDir(repoPath) ? newFileHashesRecord : undefined,
+            // This branch's full live chunk-key set (#2106 R6). `usedKeys` is every
+            // chunk hash touched in this scan — cache HITS included (see parse-impl
+            // usedKeys.add) — so it's complete even on an incremental run. Persisted
+            // so a sibling branch's prune can union it and not evict our shards.
+            cacheKeys: [...parseCache.usedKeys],
             incrementalInProgress: undefined,
         };
-        await saveMeta(storagePath, meta);
+        await saveMeta(metaDir, meta);
         // Persist the incremental parse cache for the next run. Wraps in
         // try/catch so a cache-write failure never breaks an otherwise
         // successful indexing run. Prune stale chunk-hash entries first so
@@ -734,6 +856,25 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // dead weight; the parse phase populates `usedKeys` as it processes
         // chunks).
         try {
+            // #2106 R6: the parse cache + durable store are shared across branches.
+            // Before pruning to this run's keys, fold in the OTHER branches' recorded
+            // chunk keys so a branch switch doesn't evict their still-live shards.
+            // Adding to usedKeys makes them survive pruneCache AND land in the saved
+            // index (saveParseCache builds the index from usedKeys). Excludes this
+            // run's own meta dir, so a single-branch repo folds in nothing → prune
+            // set byte-identical to today.
+            const { keys: siblingKeys, complete } = await collectBranchCacheKeys(storagePath, metaDir);
+            if (complete) {
+                for (const k of siblingKeys)
+                    parseCache.usedKeys.add(k);
+            }
+            else {
+                // Fail-safe toward retention: a sibling meta was unreadable, so keep
+                // everything currently loaded rather than evict on incomplete info.
+                log('Parse cache: a branch meta was unreadable — retaining all cached chunks (#2106).');
+                for (const k of parseCache.entries.keys())
+                    parseCache.usedKeys.add(k);
+            }
             const pruned = pruneCache(parseCache, parseCache.usedKeys);
             if (pruned > 0) {
                 log(`Parse cache: pruned ${pruned} stale chunk entries`);
@@ -763,6 +904,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         const projectName = await registerRepo(repoPath, meta, {
             name: options.registryName,
             allowDuplicateName: options.allowDuplicateName,
+            // Non-primary branch runs upsert into the entry's branches[]; the
+            // primary/flat run (placement.branch === undefined) refreshes the
+            // top-level fields (#2106).
+            branch: placement.branch,
         });
         // Keep generated .gitnexus contents ignored without editing the user's root .gitignore.
         await ensureGitNexusIgnored(repoPath);
@@ -776,23 +921,28 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             }
             aggregatedClusterCount = Array.from(groups.values()).filter((count) => count >= 5).length;
         }
-        try {
-            await generateAIContextFiles(repoPath, storagePath, projectName, {
-                files: pipelineResult.totalFileCount,
-                nodes: stats.nodes,
-                edges: stats.edges,
-                communities: pipelineResult.communityResult?.stats.totalCommunities,
-                clusters: aggregatedClusterCount,
-                processes: pipelineResult.processResult?.stats.totalProcesses,
-            }, undefined, {
-                skipAgentsMd: options.skipAgentsMd,
-                skipSkills: options.skipSkills,
-                noStats: options.noStats,
-                defaultBranch: options.defaultBranch,
-            });
-        }
-        catch {
-            // Best-effort — don't fail the entire analysis for context file issues
+        // Only (re)generate the repo-root AI context files (AGENTS.md / CLAUDE.md /
+        // skills) for the primary/flat index (#2106). A non-primary branch analyze
+        // must not churn the repo's committed AGENTS.md with branch-specific stats.
+        if (!placement.branch) {
+            try {
+                await generateAIContextFiles(repoPath, storagePath, projectName, {
+                    files: pipelineResult.totalFileCount,
+                    nodes: stats.nodes,
+                    edges: stats.edges,
+                    communities: pipelineResult.communityResult?.stats.totalCommunities,
+                    clusters: aggregatedClusterCount,
+                    processes: pipelineResult.processResult?.stats.totalProcesses,
+                }, undefined, {
+                    skipAgentsMd: options.skipAgentsMd,
+                    skipSkills: options.skipSkills,
+                    noStats: options.noStats,
+                    defaultBranch: options.defaultBranch,
+                });
+            }
+            catch {
+                // Best-effort — don't fail the entire analysis for context file issues
+            }
         }
         // ── Close LadybugDB ──────────────────────────────────────────────
         // Stop the manual checkpoint driver before closeLbug so its
@@ -806,6 +956,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             stats: meta.stats,
             pipelineResult,
             ftsSkipped: !ftsAvailable,
+            isPrimaryBranch: !placement.branch,
         };
     }
     catch (err) {

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

@@ -2,6 +2,7 @@ import Parser from 'tree-sitter';
 import { createRequire } from 'node:module';
 import { SupportedLanguages } from '../../_shared/index.js';
 import { logger } from '../logger.js';
+import { requireVendoredGrammar } from './vendored-grammars.js';
 const _require = createRequire(import.meta.url);
 const ISSUES_URL = 'https://github.com/abhigyanpatwari/GitNexus/issues';
 const SOURCES = {
@@ -71,7 +72,7 @@ const SOURCES = {
     // user-opt-out grammar like Swift/Dart/Kotlin: a failure here is always an
     // install/platform problem the user needs to see.
     [SupportedLanguages.C]: {
-        load: () => _require('tree-sitter-c'),
+        load: () => requireVendoredGrammar('tree-sitter-c'),
         optional: true,
         severity: 'error',
         unavailableNote: 'C parsing disabled: vendored `tree-sitter-c` (under ' +
@@ -85,7 +86,7 @@ const SOURCES = {
     // optionalDependencies — may be absent on platforms without prebuilds
     // or when users skip optional installs.
     [SupportedLanguages.Swift]: {
-        load: () => _require('tree-sitter-swift'),
+        load: () => requireVendoredGrammar('tree-sitter-swift'),
         optional: true,
         userSkippable: true,
         unavailableNote: 'Swift parsing disabled: vendored `tree-sitter-swift` (under ' +
@@ -94,7 +95,7 @@ const SOURCES = {
             `See ${ISSUES_URL}/1130.`,
     },
     [SupportedLanguages.Dart]: {
-        load: () => _require('tree-sitter-dart'),
+        load: () => requireVendoredGrammar('tree-sitter-dart'),
         optional: true,
         userSkippable: true,
         unavailableNote: 'Dart parsing disabled: vendored `tree-sitter-dart` (under ' +
@@ -103,7 +104,7 @@ const SOURCES = {
             `See ${ISSUES_URL}/1125.`,
     },
     [SupportedLanguages.Kotlin]: {
-        load: () => _require('tree-sitter-kotlin'),
+        load: () => requireVendoredGrammar('tree-sitter-kotlin'),
         optional: true,
         userSkippable: true,
         unavailableNote: 'Kotlin parsing disabled: vendored `tree-sitter-kotlin` (under ' +

package/dist/core/tree-sitter/vendored-grammars.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Absolute path to the vendored grammar tree (`<pkg>/vendor`).
+ *
+ * This module compiles to `<pkg>/dist/core/tree-sitter/vendored-grammars.js`
+ * and runs from `<pkg>/src/core/tree-sitter/...` under tsx in dev — both sit
+ * three directories below the package root, and the build (`tsc`) never bundles,
+ * so `import.meta.url` resolves the same way in both. `vendor/` ships in the
+ * published package via package.json `files`.
+ */
+export declare const VENDOR_ROOT: string;
+/**
+ * The tree-sitter grammars GitNexus vendors inside its own package (NOT npm
+ * dependencies). Kept in one place so consumers (runtime loaders, the CLI
+ * availability probe, and the test grammar-introspection helper) agree on which
+ * grammars resolve from `vendor/` rather than `node_modules`.
+ */
+export declare const VENDORED_GRAMMAR_PACKAGES: ReadonlySet<string>;
+/** Absolute directory of a vendored grammar package under `vendor/`. */
+export declare const vendoredGrammarDir: (packageName: string) => string;
+/**
+ * Load a vendored tree-sitter grammar by its absolute path under `vendor/`.
+ *
+ * GitNexus vendors five grammars (c/dart/proto/swift/kotlin) inside its own
+ * package under `vendor/`, each shipping committed per-platform prebuilds. They
+ * are deliberately NOT npm dependencies and must NEVER be copied into
+ * `node_modules`: an undeclared package under `node_modules` is "extraneous" to
+ * every subsequent `npm`/`npx` arborist reify, which prunes or relocates it.
+ * That is the root cause of #2111 / #1728 — on Windows the relocation throws
+ * `EPERM: operation not permitted, symlink` (errno -4048) during the npx-cache
+ * reify Antigravity triggers when it launches the MCP server, and on every OS
+ * the second run silently deletes the materialized grammars.
+ *
+ * Resolving the grammar by absolute path runs its own `bindings/node` entry,
+ * which calls `node-gyp-build(<grammarDir>)` and loads
+ * `vendor/<name>/prebuilds/<platform>-<arch>/…` directly — no build, no write,
+ * no `node_modules` copy. (`node-gyp-build` itself IS an npm dependency and
+ * resolves normally from the grammar directory.)
+ */
+export declare const requireVendoredGrammar: (packageName: string) => unknown;

package/dist/core/tree-sitter/vendored-grammars.js

@@ -0,0 +1,57 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+const _require = createRequire(import.meta.url);
+/**
+ * Absolute path to the vendored grammar tree (`<pkg>/vendor`).
+ *
+ * This module compiles to `<pkg>/dist/core/tree-sitter/vendored-grammars.js`
+ * and runs from `<pkg>/src/core/tree-sitter/...` under tsx in dev — both sit
+ * three directories below the package root, and the build (`tsc`) never bundles,
+ * so `import.meta.url` resolves the same way in both. `vendor/` ships in the
+ * published package via package.json `files`.
+ */
+export const VENDOR_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'vendor');
+/**
+ * The tree-sitter grammars GitNexus vendors inside its own package (NOT npm
+ * dependencies). Kept in one place so consumers (runtime loaders, the CLI
+ * availability probe, and the test grammar-introspection helper) agree on which
+ * grammars resolve from `vendor/` rather than `node_modules`.
+ */
+export const VENDORED_GRAMMAR_PACKAGES = new Set([
+    'tree-sitter-c',
+    'tree-sitter-dart',
+    'tree-sitter-proto',
+    'tree-sitter-swift',
+    'tree-sitter-kotlin',
+]);
+/** Absolute directory of a vendored grammar package under `vendor/`. */
+export const vendoredGrammarDir = (packageName) => path.join(VENDOR_ROOT, packageName);
+/**
+ * Load a vendored tree-sitter grammar by its absolute path under `vendor/`.
+ *
+ * GitNexus vendors five grammars (c/dart/proto/swift/kotlin) inside its own
+ * package under `vendor/`, each shipping committed per-platform prebuilds. They
+ * are deliberately NOT npm dependencies and must NEVER be copied into
+ * `node_modules`: an undeclared package under `node_modules` is "extraneous" to
+ * every subsequent `npm`/`npx` arborist reify, which prunes or relocates it.
+ * That is the root cause of #2111 / #1728 — on Windows the relocation throws
+ * `EPERM: operation not permitted, symlink` (errno -4048) during the npx-cache
+ * reify Antigravity triggers when it launches the MCP server, and on every OS
+ * the second run silently deletes the materialized grammars.
+ *
+ * Resolving the grammar by absolute path runs its own `bindings/node` entry,
+ * which calls `node-gyp-build(<grammarDir>)` and loads
+ * `vendor/<name>/prebuilds/<platform>-<arch>/…` directly — no build, no write,
+ * no `node_modules` copy. (`node-gyp-build` itself IS an npm dependency and
+ * resolves normally from the grammar directory.)
+ */
+export const requireVendoredGrammar = (packageName) => {
+    // Fail loudly on a name that isn't actually vendored — a typo or a list that
+    // drifted out of sync (VENDORED_GRAMMAR_PACKAGES vs the CLI probe vs the build
+    // registry) would otherwise surface as a confusing absolute-path require miss.
+    if (!VENDORED_GRAMMAR_PACKAGES.has(packageName)) {
+        throw new Error(`'${packageName}' is not a vendored grammar (expected one of: ${[...VENDORED_GRAMMAR_PACKAGES].join(', ')}).`);
+    }
+    return _require(vendoredGrammarDir(packageName));
+};

package/dist/mcp/core/embedder.js

@@ -8,6 +8,7 @@ import { isHttpMode, getHttpDimensions, httpEmbedQuery, } from '../../core/embed
 import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
 import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry, } from '../../core/embeddings/hf-env.js';
 import { getLocalEmbeddingRuntimeBlocker } from '../../core/embeddings/runtime-support.js';
+import { ensureOnnxRuntimeCommonResolvable } from '../../core/embeddings/onnxruntime-common-resolver.js';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
 import { logger } from '../../core/logger.js';
 // Model config
@@ -43,6 +44,9 @@ export const initEmbedder = async () => {
         try {
             // Lazy-load transformers.js only after the runtime guard has passed, so
             // unsupported platforms never reach the native ONNX import (#1515).
+            // Under pnpm-strict / `pnpm dlx`, transformers' phantom `onnxruntime-common`
+            // import is unresolvable; register the fallback resolver first (#307).
+            ensureOnnxRuntimeCommonResolvable();
             const { pipeline, env } = await import('@huggingface/transformers');
             env.allowLocalModels = false;
             // Bridge user-controlled env vars to transformers.js: HF_HOME →

package/dist/mcp/local/local-backend.d.ts

@@ -5,7 +5,7 @@
  * Supports multiple indexed repositories via a global registry.
  * LadybugDB connections are opened lazily per repo on first query.
  */
-import { type RegistryEntry } from '../../storage/repo-manager.js';
+import { type RegistryEntry, type BranchSummary } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
 /**
  * Quick test-file detection for filtering impact results.
@@ -16,6 +16,15 @@ export declare function isTestFilePath(filePath: string): boolean;
 export declare const VALID_NODE_LABELS: Set<string>;
 /** Valid relation types for impact analysis filtering */
 export declare const VALID_RELATION_TYPES: Set<string>;
+/**
+ * Relation types the #1858 epistemic-boundary probe keys on. Kept as
+ * module-level `readonly` arrays (not Sets) because computeEpistemicBoundary
+ * binds them as Cypher query params (`r.type IN $heritage` / `IN $types`).
+ * The heritage set is exactly the IMPACT_RELATION_CONFIDENCE 0.85 tier —
+ * "statically verifiable, but the concrete binding past it is not".
+ */
+export declare const EPISTEMIC_HERITAGE_RELATION_TYPES: readonly string[];
+export declare const EPISTEMIC_CONSUMER_RELATION_TYPES: readonly string[];
 /**
  * Per-relation-type confidence floor for impact analysis.
  *
@@ -56,6 +65,10 @@ interface RepoHandle {
     lastCommit: string;
     remoteUrl?: string;
     stats?: RegistryEntry['stats'];
+    /** Primary/flat branch name, when known (#2106). */
+    branch?: string;
+    /** Non-primary branch indexes available for this repo (#2106). */
+    branches?: BranchSummary[];
 }
 /**
  * Resolve the git diff cwd for detect_changes, auto-detecting linked worktrees.
@@ -107,6 +120,10 @@ export interface RepoListing {
         path: string;
         lastCommit: string;
     }>;
+    /** Primary/flat branch name, when known (#2106). */
+    branch?: string;
+    /** Non-primary branch indexes available for this repo (#2106). */
+    branches?: Array<Omit<BranchSummary, 'stats'>>;
 }
 /** Continuation metadata for the paginated `list_repos` MCP tool (#2119). */
 export interface ListReposPagination {
@@ -153,6 +170,7 @@ export declare class LocalBackend {
     private initializedRepos;
     private reinitPromises;
     private lastStalenessCheck;
+    private lastObservedIndexedAt;
     private groupToolSvc;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by
@@ -214,7 +232,20 @@ export declare class LocalBackend {
      * On a miss, re-reads the registry once in case a new repo was indexed
      * while the MCP server was running.
      */
-    resolveRepo(repoParam?: string): Promise<RepoHandle>;
+    resolveRepo(repoParam?: string, branch?: string): Promise<RepoHandle>;
+    /**
+     * Re-point a resolved repo handle at a specific branch index (#2106).
+     *
+     * - No `branch` (default) → the primary/flat handle, unchanged (backward
+     *   compatible: every existing caller passes no branch).
+     * - `branch` equal to the known primary → the flat handle.
+     * - `branch` matching an indexed non-primary branch → a handle whose
+     *   `lbugPath` points at `branches/<slug>/lbug`; the connection pool keys by
+     *   `lbugPath`, so this is the only change needed to scope every tool.
+     * - `branch` that was never indexed → a clear error (never a silently-empty
+     *   result against the wrong DB).
+     */
+    private applyBranchScope;
     /**
      * Try to resolve a repo from the in-memory cache. Returns null on miss.
      * Throws {@link RegistryAmbiguousTargetError} when `repoParam` matches
@@ -409,6 +440,28 @@ export declare class LocalBackend {
     private rename;
     private impact;
     private _impactImpl;
+    /**
+     * #1858 — epistemic lower-bound detection.
+     *
+     * impact()/context() traverse only edges materialized in the graph. When the
+     * queried symbol sits on an interface / abstract boundary, callers that bind
+     * to the interface via DI, a container, or dynamic dispatch — rather than
+     * naming the concrete symbol — are not traced. The reported count is then a
+     * lower bound, not an exact figure. Instead of returning a confident count
+     * that silently omits those callers, annotate the result with
+     * `epistemic: 'lower-bound'` plus a human-readable boundary note. A fully
+     * resolved leaf with no indirection stays `epistemic: 'exact'`.
+     *
+     * Aligns with the numeric confidence model rather than the long-deleted
+     * TIER_CONFIDENCE enum: the heritage/indirection edges this keys on
+     * (IMPLEMENTS / METHOD_IMPLEMENTS / EXTENDS) carry the 0.85
+     * `IMPACT_RELATION_CONFIDENCE` floor — "statically verifiable, but the
+     * concrete binding past it is not".
+     *
+     * Never throws: on query error it returns 'exact', so it can only add signal,
+     * never suppress a result.
+     */
+    private computeEpistemicBoundary;
     /**
      * Shared BFS traversal for impact analysis (name-resolved or UID-resolved symbol).
      */