gitnexus 1.6.7 → 1.6.8-rc.10

package/dist/mcp/local/local-backend.js

@@ -17,7 +17,7 @@ import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/l
 // import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
 import { parseDiffHunks, getCanonicalRepoRoot, getGitRoot, } from '../../storage/git.js';
 import { realpathSync } from 'fs';
-import { listRegisteredRepos, cleanupOldKuzuFiles, canonicalizePath, RegistryAmbiguousTargetError, } from '../../storage/repo-manager.js';
+import { listRegisteredRepos, cleanupOldKuzuFiles, canonicalizePath, getStoragePaths, loadMeta, RegistryAmbiguousTargetError, } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
@@ -96,12 +96,32 @@ export const VALID_RELATION_TYPES = new Set([
     'OVERRIDES', // Legacy alias — dual-read for pre-rename indexes
     'METHOD_IMPLEMENTS',
     'ACCESSES',
+    // Emitted by emit-references.ts / scope-resolution/graph-bridge/edges.ts and
+    // already part of the default impact relTypes + context() incoming queries.
+    // It was missing from this allowlist, so `impact({relationTypes:['USES']})`
+    // silently filtered to [] and fell back to the full default traversal
+    // (#2129/#1858 review F5). No IMPACT_RELATION_CONFIDENCE floor → 0.5 fallback,
+    // matching the FETCHES / WRAPS / HANDLES_ROUTE precedent below.
+    'USES',
     'HANDLES_ROUTE',
     'FETCHES',
     'HANDLES_TOOL',
     'ENTRY_POINT_OF',
     'WRAPS',
 ]);
+/**
+ * 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 const EPISTEMIC_HERITAGE_RELATION_TYPES = [
+    'IMPLEMENTS',
+    'METHOD_IMPLEMENTS',
+    'EXTENDS',
+];
+export const EPISTEMIC_CONSUMER_RELATION_TYPES = ['CALLS', 'USES', 'ACCESSES'];
 /**
  * Per-relation-type confidence floor for impact analysis.
  *
@@ -315,6 +335,12 @@ export class LocalBackend {
     initializedRepos = new Set();
     reinitPromises = new Map();
     lastStalenessCheck = new Map();
+    // Last meta.indexedAt observed for an open pool, keyed by lbugPath. Keyed by
+    // pool (not stored on the handle) because branch handles are produced fresh
+    // by applyBranchScope on every resolveRepo call, so mutating the handle would
+    // not persist across calls and the staleness check would reinit forever
+    // (#2106).
+    lastObservedIndexedAt = new Map();
     groupToolSvc = null;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by
@@ -410,6 +436,8 @@ export class LocalBackend {
                 lastCommit: entry.lastCommit,
                 remoteUrl: entry.remoteUrl,
                 stats: entry.stats,
+                branch: entry.branch,
+                branches: entry.branches,
             };
             nextRepos.set(id, handle);
             // Build lightweight context (no LadybugDB needed)
@@ -432,13 +460,31 @@ export class LocalBackend {
         // the resolve→query wrong-clone window for good (#2067). Only a path that
         // dropped out of the registry must release its pooled connection + state.
         const liveLbugPaths = new Set([...nextRepos.values()].map((h) => h.lbugPath));
-        for (const prev of this.repos.values()) {
-            if (liveLbugPaths.has(prev.lbugPath))
+        // Branch pools (opened on demand by applyBranchScope) are NOT in this.repos
+        // — branch handles are minted fresh and discarded — so add every registered
+        // branch's lbugPath to the live set. Pure string work over the already-in-
+        // memory registry snapshot; no disk I/O on this hot path (#2106 R3).
+        for (const entry of entries) {
+            for (const b of entry.branches ?? []) {
+                liveLbugPaths.add(getStoragePaths(entry.path, b.branch).lbugPath);
+            }
+        }
+        // initializedRepos is the authoritative set of OPENED pool keys (flat AND
+        // branch); union it with the previously-known flat handles so an orphaned
+        // branch pool (e.g. after `clean --branch` removes its summary) is closed
+        // and forgotten too, not just flat handles.
+        const knownKeys = new Set([
+            ...[...this.repos.values()].map((h) => h.lbugPath),
+            ...this.initializedRepos,
+        ]);
+        for (const key of knownKeys) {
+            if (liveLbugPaths.has(key))
                 continue;
-            this.initializedRepos.delete(prev.lbugPath);
-            this.lastStalenessCheck.delete(prev.lbugPath);
-            this.reinitPromises.delete(prev.lbugPath);
-            closeLbug(prev.lbugPath).catch(() => { });
+            this.initializedRepos.delete(key);
+            this.lastStalenessCheck.delete(key);
+            this.lastObservedIndexedAt.delete(key);
+            this.reinitPromises.delete(key);
+            closeLbug(key).catch(() => { });
         }
         this.repos = nextRepos;
         this.contextCache = nextContext;
@@ -507,7 +553,7 @@ export class LocalBackend {
      * On a miss, re-reads the registry once in case a new repo was indexed
      * while the MCP server was running.
      */
-    async resolveRepo(repoParam) {
+    async resolveRepo(repoParam, branch) {
         let refreshedAfterAmbiguity = false;
         let result;
         try {
@@ -532,7 +578,7 @@ export class LocalBackend {
             this.maybeWarnSiblingDrift(result).catch(() => {
                 /* best-effort; never throw from resolveRepo */
             });
-            return result;
+            return this.applyBranchScope(result, branch);
         }
         // Miss — refresh registry and try once more (skip if already refreshed above)
         if (!refreshedAfterAmbiguity) {
@@ -541,7 +587,7 @@ export class LocalBackend {
         const retried = this.resolveRepoFromCache(repoParam);
         if (retried) {
             this.maybeWarnSiblingDrift(retried).catch(() => { });
-            return retried;
+            return this.applyBranchScope(retried, branch);
         }
         // Still no match — throw with helpful message
         if (this.repos.size === 0) {
@@ -562,6 +608,49 @@ export class LocalBackend {
         }
         throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${labels.join(', ')}`);
     }
+    /**
+     * 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).
+     */
+    async applyBranchScope(handle, branch) {
+        if (!branch)
+            return handle;
+        if (handle.branch && handle.branch === branch)
+            return handle;
+        const summary = handle.branches?.find((b) => b.branch === branch);
+        if (summary) {
+            const { lbugPath } = getStoragePaths(handle.repoPath, branch);
+            return {
+                ...handle,
+                lbugPath,
+                indexedAt: summary.indexedAt,
+                lastCommit: summary.lastCommit,
+                stats: summary.stats,
+            };
+        }
+        // Legacy entry (pre-#2106): the registry has no recorded primary `branch`,
+        // so a `--branch <primary>` request misses the checks above. Read the flat
+        // meta.json (next to the flat handle's lbug) to learn the primary and serve
+        // the flat handle only when it actually matches — never serve flat for an
+        // arbitrary unindexed branch (#2106 R4).
+        if (!handle.branch) {
+            const flatMeta = await loadMeta(path.dirname(handle.lbugPath));
+            if (flatMeta?.branch && flatMeta.branch === branch)
+                return handle;
+        }
+        const indexed = [handle.branch, ...(handle.branches?.map((b) => b.branch) ?? [])].filter(Boolean);
+        const available = indexed.length > 0 ? indexed.join(', ') : '(primary only)';
+        throw new Error(`Branch "${branch}" is not indexed for "${handle.name}". ` +
+            `Indexed branches: ${available}. Run: gitnexus analyze --branch ${branch}`);
+    }
     /**
      * Try to resolve a repo from the in-memory cache. Returns null on miss.
      * Throws {@link RegistryAmbiguousTargetError} when `repoParam` matches
@@ -681,10 +770,19 @@ export class LocalBackend {
                 return; // Checked recently — skip
             this.lastStalenessCheck.set(poolKey, now);
             try {
-                const metaPath = path.join(repo.storagePath, 'meta.json');
+                // Read the meta.json that sits next to THIS handle's lbug. For the
+                // flat/primary handle this is `<storagePath>/meta.json` (unchanged);
+                // for a branch handle it is `<storagePath>/branches/<slug>/meta.json`.
+                // Reading the flat meta for a branch handle would compare the branch
+                // index's indexedAt against the primary's and thrash the pool (#2106).
+                const metaPath = path.join(path.dirname(repo.lbugPath), 'meta.json');
                 const metaRaw = await fs.readFile(metaPath, 'utf-8');
                 const meta = JSON.parse(metaRaw);
-                if (meta.indexedAt && meta.indexedAt !== repo.indexedAt) {
+                // Compare against the last indexedAt OBSERVED for this pool (keyed by
+                // lbugPath), not the handle's — branch handles are fresh spreads so a
+                // handle mutation would not persist and would reinit on every check.
+                const observed = this.lastObservedIndexedAt.get(poolKey) ?? repo.indexedAt;
+                if (meta.indexedAt && meta.indexedAt !== observed) {
                     // Index was rebuilt — close stale connection and re-init.
                     // Wrap in reinitPromises to prevent TOCTOU race where concurrent
                     // callers both detect staleness and double-close the pool.
@@ -692,7 +790,7 @@ export class LocalBackend {
                         try {
                             await closeLbug(poolKey);
                             this.initializedRepos.delete(poolKey);
-                            repo.indexedAt = meta.indexedAt;
+                            this.lastObservedIndexedAt.set(poolKey, meta.indexedAt);
                             await initLbug(poolKey, repo.lbugPath);
                             this.initializedRepos.add(poolKey);
                         }
@@ -714,6 +812,7 @@ export class LocalBackend {
         try {
             await initLbug(poolKey, repo.lbugPath);
             this.initializedRepos.add(poolKey);
+            this.lastObservedIndexedAt.set(poolKey, repo.indexedAt);
         }
         catch (err) {
             // If lock error, mark as not initialized so next call retries
@@ -792,6 +891,14 @@ export class LocalBackend {
                         lastCommit: s.lastCommit,
                     }))
                     : undefined,
+                branch: h.branch,
+                branches: h.branches && h.branches.length > 0
+                    ? h.branches.map((b) => ({
+                        branch: b.branch,
+                        indexedAt: b.indexedAt,
+                        lastCommit: b.lastCommit,
+                    }))
+                    : undefined,
             };
         });
     }
@@ -913,8 +1020,10 @@ export class LocalBackend {
             p.repo.startsWith('@')) {
             return this.callToolAtGroupRepo(method, p);
         }
-        // Resolve repo from optional param (re-reads registry on miss)
-        const repo = await this.resolveRepo(params?.repo);
+        // Resolve repo from optional param (re-reads registry on miss). An optional
+        // `branch` param scopes the resolved handle to that branch's index (#2106).
+        const repoParams = params;
+        const repo = await this.resolveRepo(repoParams?.repo, repoParams?.branch);
         switch (method) {
             case 'query':
                 return this.query(repo, params);
@@ -2011,6 +2120,23 @@ export class LocalBackend {
         // Method/Function/Constructor enrichment: fetch method-specific properties
         const symKind = isClassLike ? resolvedLabel || 'Class' : sym.type || sym[2];
         const isMethodLike = symKind === 'Method' || symKind === 'Function' || symKind === 'Constructor';
+        // #1858 review F2 — start the epistemic boundary probe here (right after
+        // `symKind` is known) so it runs CONCURRENTLY with the methodMetadata fetch
+        // below, mirroring how _runImpactBFS overlaps it with the BFS. It is awaited
+        // at result assembly. (It cannot start earlier — `symKind` is only computed
+        // on this line, after the incoming/outgoing round-trips.)
+        //
+        // #1858 review F3 — pass an interface-preserving type, NOT `symKind`.
+        // `symKind` collapses a single-resolved Interface to 'Class' (resolvedLabel
+        // is '' on the single-candidate path), which would skip computeEpistemicBoundary's
+        // `symType === 'Interface'` self-boundary branch and under-report a leaf
+        // interface as 'exact'. `enrichCandidateLabels` runs BEFORE the single-candidate
+        // early return and patches `sym.type` from '' to 'Interface' (LadybugDB returns
+        // '' for labels()[0] on Interface/Class), so `sym.type` is the reliable signal
+        // here — mirroring impact()'s `resolvedLabel || symbol.type` derivation. Do not
+        // "fix" enrichment ordering; F3 depends on enrichment-before-early-return.
+        const epistemicSymType = (resolvedLabel || sym.type || symKind || '');
+        const epistemicPromise = this.computeEpistemicBoundary(repo, symId, epistemicSymType, (sym.name || sym[1]));
         let methodMetadata;
         if (isMethodLike) {
             try {
@@ -2041,6 +2167,12 @@ export class LocalBackend {
                 /* method metadata unavailable — omit silently */
             }
         }
+        // #1858 — same epistemic boundary signal as impact(): when this symbol sits
+        // behind an interface / indirection boundary, callers binding via DI or
+        // dynamic dispatch are not reflected in `incoming`, so the view is a lower
+        // bound. Additive; never suppresses a field. Resolved from the probe started
+        // above (concurrent with methodMetadata).
+        const epistemic = await epistemicPromise;
         return {
             status: 'found',
             symbol: {
@@ -2053,6 +2185,7 @@ export class LocalBackend {
                 ...(include_content && (sym.content || sym[6]) ? { content: sym.content || sym[6] } : {}),
                 ...(methodMetadata ? { methodMetadata } : {}),
             },
+            ...epistemic,
             incoming: categorize(incomingRows),
             outgoing: categorize(outgoingRows),
             ...(typedPropertyRows.length > 0
@@ -2586,21 +2719,103 @@ export class LocalBackend {
             };
         }
         if (outcome.kind === 'ambiguous') {
-            return {
-                status: 'ambiguous',
-                message: `Found ${outcome.candidates.length} symbols matching '${target}'. Use target_uid, file_path, or kind to disambiguate.`,
-                target: { name: target },
-                direction,
-                impactedCount: 0,
-                risk: 'UNKNOWN',
-                candidates: outcome.candidates.map((c) => ({
+            // #2129 — a bare name that collides with several symbols must NOT report a
+            // bare `impactedCount: 0`. The real blast radius lives under whichever
+            // candidate the caller meant; a flat zero here is precisely the silent
+            // under-report the "run impact before editing" workflow exists to prevent
+            // (the dropped caller calls a *different* same-name node, so it never shows
+            // up against the one the resolver happened to pick). Run a bounded,
+            // summary-only BFS per candidate so each one's true count + risk is
+            // visible, and surface the maximum at the top level so the headline can
+            // never read as "safe to refactor". Candidates arrive sorted by score.
+            const AMBIGUOUS_MAX_CANDIDATES = 6;
+            const probed = outcome.candidates.slice(0, AMBIGUOUS_MAX_CANDIDATES);
+            // `partialProbe` is intentionally a SECOND incompleteness flag, distinct
+            // from the traversal-interrupted `partial` flag used elsewhere: it means
+            // one or more per-candidate probes threw, so maxRisk / maxImpactedCount
+            // are lower bounds over the probes that succeeded (a failed candidate must
+            // not be masked by a benign sibling success).
+            let probeFailed = false;
+            const candidateSummaries = await Promise.all(probed.map(async (c) => {
+                const cType = c.type || '';
+                const cRelTypes = (cType === 'Class' || cType === 'Interface') &&
+                    !hasExplicitRelationTypes &&
+                    !relationTypes.includes('ACCESSES')
+                    ? [...relationTypes, 'ACCESSES']
+                    : relationTypes;
+                // #1858/#2129 review F8 — name the shape the probe summary is read
+                // through (`_runImpactBFS` returns `Promise<any>`, so this is the
+                // narrowing cast) so a future rename of those fields fails tsc instead
+                // of silently zeroing candidate counts.
+                let summary = null;
+                try {
+                    summary = await this._runImpactBFS(repo, { id: c.id, name: c.name, filePath: c.filePath }, cType, direction, {
+                        maxDepth,
+                        relationTypes: cRelTypes,
+                        includeTests,
+                        minConfidence,
+                        summaryOnly: true,
+                        skipEpistemic: true,
+                        skipEnrichment: true,
+                    });
+                }
+                catch (e) {
+                    probeFailed = true;
+                    logQueryError('impact:ambiguous-candidate', e);
+                }
+                return {
                     uid: c.id,
                     name: c.name,
                     kind: c.type,
                     filePath: c.filePath,
                     line: c.startLine,
                     score: Number(c.score.toFixed(2)),
-                })),
+                    impactedCount: summary?.impactedCount ?? 0,
+                    risk: summary?.risk ?? 'UNKNOWN',
+                    direct: summary?.summary?.direct ?? 0,
+                };
+            }));
+            // Rank by blast radius so the most-impactful interpretation is first, and
+            // hoist the maximum count/risk to the top level so the response cannot be
+            // misread as "no impact".
+            candidateSummaries.sort((a, b) => b.impactedCount - a.impactedCount);
+            const maxImpactedCount = candidateSummaries.reduce((m, c) => Math.max(m, c.impactedCount), 0);
+            const RISK_ORDER = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+            // If EVERY candidate probe failed (all 'UNKNOWN' — e.g. pool exhaustion
+            // under the fan-out), the worst real risk is genuinely unknown, not LOW.
+            // Reporting LOW here would re-introduce the false-safe signal. Only fall to
+            // the LOW seed when at least one candidate produced a real risk.
+            const anyKnownRisk = candidateSummaries.some((c) => RISK_ORDER.includes(c.risk));
+            const maxRisk = anyKnownRisk
+                ? candidateSummaries.reduce((worst, c) => (RISK_ORDER.indexOf(c.risk) > RISK_ORDER.indexOf(worst) ? c.risk : worst), 'LOW')
+                : 'UNKNOWN';
+            const truncated = outcome.candidates.length > probed.length;
+            return {
+                status: 'ambiguous',
+                message: `Found ${outcome.candidates.length} symbols matching '${target}'` +
+                    (truncated
+                        ? ` (showing ${candidateSummaries.length} of ${outcome.candidates.length})`
+                        : '') +
+                    `. Blast radius differs per candidate (max ${maxImpactedCount} impacted at risk ${maxRisk}). ` +
+                    `Disambiguate with target_uid (or file_path/kind) for a single authoritative result.`,
+                target: { name: target },
+                direction,
+                // Full match count — `candidates[]` is truncated to AMBIGUOUS_MAX_CANDIDATES,
+                // so consumers (CLI formatter) need this to report "N of M" honestly (#2129
+                // review F11; the CLI previously read the truncated array length).
+                totalCandidates: outcome.candidates.length,
+                // `impactedCount` stays 0 and `risk` stays UNKNOWN — there is no single
+                // resolved symbol, and UNKNOWN must NOT read as "safe to refactor". The
+                // real blast radius is surfaced per-candidate plus `maxImpactedCount` /
+                // `maxRisk` so a real caller can never hide behind the ambiguous zero
+                // (#2129).
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+                maxImpactedCount,
+                maxRisk,
+                ...(probeFailed ? { partialProbe: true } : {}),
+                ...(truncated && { candidatesTruncated: true }),
+                candidates: candidateSummaries,
             };
         }
         const sym = {
@@ -2624,12 +2839,109 @@ export class LocalBackend {
             summaryOnly: params.summaryOnly,
         });
     }
+    /**
+     * #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.
+     */
+    async computeEpistemicBoundary(repo, symId, symType, symName) {
+        const HERITAGE_TYPES = EPISTEMIC_HERITAGE_RELATION_TYPES;
+        const CONSUMER_TYPES = EPISTEMIC_CONSUMER_RELATION_TYPES;
+        try {
+            // Discover the interface / abstract supertypes on the target's boundary.
+            // If the target is itself an interface, it is its own boundary node.
+            const boundary = new Map();
+            if (symType === 'Interface') {
+                boundary.set(symId, { name: symName || '', label: 'Interface' });
+            }
+            const ifaceRows = await executeParameterized(repo.lbugPath, `MATCH (x)-[r:CodeRelation]->(iface)
+         WHERE x.id = $symId AND r.type IN $heritage
+         RETURN DISTINCT iface.id AS id, iface.name AS name, labels(iface)[0] AS label
+         LIMIT 25`, { symId, heritage: HERITAGE_TYPES }).catch(() => []);
+            for (const r of ifaceRows) {
+                const id = (r.id ?? r[0]);
+                if (id && !boundary.has(id)) {
+                    boundary.set(id, {
+                        name: (r.name ?? r[1] ?? ''),
+                        label: (r.label ?? r[2] ?? 'Interface'),
+                    });
+                }
+            }
+            if (boundary.size === 0)
+                return { epistemic: 'exact' };
+            const ifaceIds = Array.from(boundary.keys());
+            // Count per interface id with scalar equality. A parameterized
+            // `iface.id IN $ids` combined with `COUNT(DISTINCT ...)` + implicit
+            // group-by returns no rows under the LadybugDB cypher subset, so query
+            // each boundary node individually (boundary is small — capped at 25).
+            const countByType = async (types) => {
+                const m = new Map();
+                await Promise.all(ifaceIds.map(async (ifaceId) => {
+                    const rows = await executeParameterized(repo.lbugPath, `MATCH (other)-[r:CodeRelation]->(iface)
+               WHERE iface.id = $ifaceId AND r.type IN $types
+               RETURN COUNT(DISTINCT other.id) AS cnt`, { ifaceId, types }).catch(() => []);
+                    const cnt = rows.length > 0 ? Number(rows[0].cnt ?? rows[0][0] ?? 0) : 0;
+                    m.set(ifaceId, cnt);
+                }));
+                return m;
+            };
+            const [implCounts, consumerCounts] = await Promise.all([
+                countByType(HERITAGE_TYPES),
+                countByType(CONSUMER_TYPES),
+            ]);
+            const boundaries = [];
+            for (const [id, info] of boundary) {
+                const impls = implCounts.get(id) ?? 0;
+                const consumers = consumerCounts.get(id) ?? 0;
+                // Flag only a genuine indirection risk: an interface that is actually
+                // consumed (callers bind to it) or that has multiple implementations
+                // (runtime dispatch is ambiguous). A concrete type implementing an
+                // interface nothing references is fully traced → stays exact.
+                if (consumers >= 1 || impls >= 2) {
+                    const label = (info.label || 'Interface').toLowerCase();
+                    const name = info.name || '(unnamed)';
+                    const article = /^[aeiou]/.test(label) ? 'an' : 'a';
+                    const parts = [];
+                    if (impls >= 1)
+                        parts.push(`${impls} ${impls === 1 ? 'implementation' : 'implementations'}`);
+                    if (consumers >= 1)
+                        parts.push(`${consumers} interface-level ${consumers === 1 ? 'consumer' : 'consumers'}`);
+                    boundaries.push(`${name} is ${article} ${label} with ${parts.join(' and ')}; callers that bind via the ${label} ` +
+                        `(e.g. a DI container or dynamic dispatch) are not traced to the concrete symbol — ` +
+                        `actual impact may be higher.`);
+                }
+            }
+            if (boundaries.length === 0)
+                return { epistemic: 'exact' };
+            return { epistemic: 'lower-bound', boundaries };
+        }
+        catch {
+            return { epistemic: 'exact' };
+        }
+    }
     /**
      * Shared BFS traversal for impact analysis (name-resolved or UID-resolved symbol).
      */
     async _runImpactBFS(repo, sym, symType, direction, opts) {
         const { maxDepth, relationTypes, includeTests, minConfidence } = opts;
         const skipPerSymbolEnrichment = opts.skipPerSymbolEnrichment ?? false;
+        const skipEnrichment = opts.skipEnrichment ?? false;
         const hasExplicitLimit = typeof opts.limit === 'number' && Number.isFinite(opts.limit);
         const paginationLimit = hasExplicitLimit
             ? Math.max(1, Math.min(Math.trunc(opts.limit), 10000))
@@ -2646,6 +2958,18 @@ export class LocalBackend {
         const safeMinConfidence = Number.isFinite(minConfidence) ? minConfidence : 0;
         const confidenceFilter = safeMinConfidence > 0 ? ' AND r.confidence >= $minConfidence' : '';
         const symId = sym.id || sym[0];
+        // #1858 — kick off the epistemic boundary probe concurrently with the BFS.
+        // It depends only on symId/symType/symName (all known now) and touches no
+        // shared state, so its extra round-trip overlaps the traversal instead of
+        // adding to the serial path. `skipEpistemic` (ambiguous #2129 candidate
+        // probes, group fan-out) resolves to no field, preserving prior behavior.
+        // #1858/#2129 review F8 — the skip case adds no field, so `epistemic` is
+        // optional here (the union's `{}` subtype). computeEpistemicBoundary's own
+        // return keeps `epistemic` REQUIRED — only this promise widens to the skip
+        // subtype.
+        const epistemicPromise = opts.skipEpistemic
+            ? Promise.resolve({})
+            : this.computeEpistemicBoundary(repo, symId, symType, (sym.name || sym[1]));
         const impacted = [];
         const visited = new Set([symId]);
         let frontier = [symId];
@@ -2783,7 +3107,13 @@ export class LocalBackend {
         // Max number of chunks to process to avoid unbounded DB round-trips.
         // Configurable via env IMPACT_MAX_CHUNKS, default 10 => max items = 1000
         const MAX_CHUNKS = parseInt(process.env.IMPACT_MAX_CHUNKS || '10', 10);
-        if (impacted.length > 0) {
+        // `skipEnrichment` (ambiguous #2129 per-candidate probes) bypasses the
+        // process/module aggregation passes entirely — those probes need only the
+        // count + a count-based risk, so paying the bounded-but-real enrichment cost
+        // ~6× per ambiguous call is wasted. risk then derives from directCount /
+        // total only (processCount/moduleCount stay 0), an acceptable approximation
+        // for a disambiguation aid.
+        if (impacted.length > 0 && !skipEnrichment) {
             // ── Process enrichment: batched chunking (bounded by MAX_CHUNKS) ─
             // Uses merged Cypher query (WITH + OPTIONAL MATCH) to fetch
             // process + entry point info in 1 round-trip per chunk. Converted to
@@ -3004,6 +3334,9 @@ export class LocalBackend {
         for (const [depth, items] of Object.entries(grouped)) {
             byDepthCounts[Number(depth)] = items.length;
         }
+        // #1858 — await the epistemic boundary probe kicked off alongside the BFS
+        // above. Additive: leaves impactedCount and every existing field untouched.
+        const epistemic = await epistemicPromise;
         const base = {
             target: {
                 id: symId,
@@ -3014,6 +3347,7 @@ export class LocalBackend {
             direction,
             impactedCount: impacted.length,
             risk,
+            ...epistemic,
             ...(!traversalComplete && { partial: true }),
             summary: {
                 direct: directCount,
@@ -3203,6 +3537,10 @@ export class LocalBackend {
                 includeTests: opts.includeTests,
                 minConfidence: opts.minConfidence,
                 skipPerSymbolEnrichment: true,
+                // Group cross-repo fan-out consumes only byDepth (cross-impact.ts), not
+                // the #1858 epistemic/boundaries fields — computing them per neighbor is
+                // dead work on the highest-volume path, so suppress them here too.
+                skipEpistemic: true,
             });
         }
         catch {

package/dist/mcp/tools.js

@@ -560,3 +560,35 @@ WHEN TO USE: After changing group.yaml or re-indexing member repos.`,
         },
     },
 ];
+/**
+ * Per-repo tools that accept an optional `branch` scope (#2106). Single source
+ * of truth: the schema property is injected here so it cannot drift from the
+ * server-side default in `local-backend.ts` (`resolveRepo(repo, branch)`).
+ * `list_repos` and the `group_*` tools are intentionally excluded — they are
+ * not single-repo, single-branch operations.
+ */
+const BRANCH_SCOPED_TOOLS = new Set([
+    'query',
+    'cypher',
+    'context',
+    'detect_changes',
+    'impact',
+    'rename',
+    'route_map',
+    'tool_map',
+    'shape_check',
+    'api_impact',
+]);
+for (const tool of GITNEXUS_TOOLS) {
+    if (!BRANCH_SCOPED_TOOLS.has(tool.name))
+        continue;
+    if (tool.inputSchema.properties.branch)
+        continue;
+    // Optional — `required` is left unchanged so omitting `branch` keeps today's
+    // default/primary-branch behavior. Ignored in group mode (repo starts "@").
+    tool.inputSchema.properties.branch = {
+        type: 'string',
+        description: 'Optional: scope to a specific branch index (multi-branch repos, #2106). ' +
+            'Omit for the default/primary branch. Ignored in group mode.',
+    };
+}