gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/mcp/server.js

@@ -14,9 +14,12 @@ import { createRequire } from 'module';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CompatibleStdioServerTransport } from './compatible-stdio-transport.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { GITNEXUS_TOOLS } from './tools.js';
+import { GITNEXUS_TOOLS, REPO_SCOPED_TOOLS } from './tools.js';
 import { installGlobalStdoutSentinel } from './stdio-context.js';
 import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
+import { assertMcpReadOnlyResource, assertMcpReadOnlyToolCall, filterMcpReadOnlyResourceContent, MCP_READ_ONLY_TOOLS, readOnlyResourceTemplateAllowed, resolveMcpReadOnlyMode, toolForReadOnlyMcp, } from './read-only-policy.js';
+import { createMcpRepositoryPolicy, McpRepositoryPolicy, mcpRepositoryPolicyConfigured, } from './repository-policy.js';
+import { applyMcpMaxTokens, resolveMcpMaxTokens, withoutMcpBudgetArg } from './output-budget.js';
 /**
  * Next-step hints appended to tool responses.
  *
@@ -60,7 +63,13 @@ function getNextStepHint(toolName, args) {
  * Create a configured MCP Server with all handlers registered.
  * Transport-agnostic — caller connects the desired transport.
  */
-export function createMCPServer(backend) {
+export function createMCPServer(backend, options = {}) {
+    const readOnly = resolveMcpReadOnlyMode();
+    if (!options.repositoryPolicy && mcpRepositoryPolicyConfigured()) {
+        throw new Error('Configured MCP repository policy must be validated before server creation.');
+    }
+    const repositoryPolicy = options.repositoryPolicy ?? McpRepositoryPolicy.unrestricted();
+    const scopedBackend = repositoryPolicy.scopeBackend(backend);
     const require = createRequire(import.meta.url);
     const pkgVersion = require('../../package.json').version;
     const server = new Server({
@@ -87,7 +96,8 @@ export function createMCPServer(backend) {
     });
     // Handle list resource templates request (for dynamic resources)
     server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
-        const templates = getResourceTemplates();
+        const templates = getResourceTemplates().filter((template) => readOnlyResourceTemplateAllowed(template.uriTemplate, readOnly) &&
+            repositoryPolicy.resourceTemplateAllowed(template.uriTemplate));
         return {
             resourceTemplates: templates.map((t) => ({
                 uriTemplate: t.uriTemplate,
@@ -101,7 +111,9 @@ export function createMCPServer(backend) {
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const { uri } = request.params;
         try {
-            const content = await readResource(uri, backend);
+            assertMcpReadOnlyResource(uri, readOnly);
+            repositoryPolicy.assertResourceUri(uri);
+            const content = filterMcpReadOnlyResourceContent(await readResource(uri, scopedBackend), readOnly);
             return {
                 contents: [
                     {
@@ -124,27 +136,44 @@ export function createMCPServer(backend) {
             };
         }
     });
-    // Handle list tools request
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: GITNEXUS_TOOLS.map((tool) => ({
-            name: tool.name,
-            description: tool.description,
-            inputSchema: tool.inputSchema,
-            annotations: tool.annotations,
-        })),
-    }));
+    // With multiple visible repositories and no process-wide default, make the
+    // routing requirement machine-readable. Agents then supply `repo` before the
+    // call instead of discovering the ambiguity through a failed tool response.
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const requireRepo = await repositoryPolicy.requiresExplicitRepo(backend);
+        return {
+            tools: GITNEXUS_TOOLS.filter((tool) => (!readOnly || MCP_READ_ONLY_TOOLS.has(tool.name)) &&
+                repositoryPolicy.toolAllowed(tool.name))
+                .map((tool) => toolForReadOnlyMcp(repositoryPolicy.toolForMcp(tool), readOnly))
+                .map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: requireRepo && REPO_SCOPED_TOOLS.has(tool.name)
+                    ? {
+                        ...tool.inputSchema,
+                        required: [...new Set([...tool.inputSchema.required, 'repo'])],
+                    }
+                    : tool.inputSchema,
+                annotations: tool.annotations,
+            })),
+        };
+    });
     // Handle tool calls — append next-step hints to guide agent workflow
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
+        let maxTokens;
         try {
-            const result = await backend.callTool(name, args);
+            const typedArgs = args;
+            assertMcpReadOnlyToolCall(name, typedArgs, readOnly);
+            maxTokens = resolveMcpMaxTokens(name, typedArgs);
+            const result = await scopedBackend.callTool(name, withoutMcpBudgetArg(typedArgs));
             const resultText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
             const hint = getNextStepHint(name, args);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: resultText + hint,
+                        text: applyMcpMaxTokens(resultText + hint, maxTokens),
                     },
                 ],
             };
@@ -155,7 +184,7 @@ export function createMCPServer(backend) {
                 content: [
                     {
                         type: 'text',
-                        text: `Error: ${message}`,
+                        text: applyMcpMaxTokens(`Error: ${message}`, maxTokens),
                     },
                 ],
                 isError: true,
@@ -265,8 +294,9 @@ export function installSignalShutdown(shutdown, on = (event, listener) => {
     on('SIGINT', () => void shutdown(SHUTDOWN_EXIT_CODES.SIGINT));
     on('SIGTERM', () => void shutdown(SHUTDOWN_EXIT_CODES.SIGTERM));
 }
-export async function startMCPServer(backend) {
-    const server = createMCPServer(backend);
+export async function startMCPServer(backend, repositoryPolicy) {
+    const validatedRepositoryPolicy = repositoryPolicy ?? (await createMcpRepositoryPolicy(backend));
+    const server = createMCPServer(backend, { repositoryPolicy: validatedRepositoryPolicy });
     // Idempotent global sentinel install. cli/mcp.ts calls this first thing
     // (before warnMissingOptionalGrammars / backend.init can emit to stdout);
     // calling again here is a safety net for direct callers of startMCPServer

package/dist/mcp/tools.d.ts

@@ -24,14 +24,6 @@ export interface ToolDefinition {
             minLength?: number;
         }>;
         required: string[];
-        /**
-         * JSON-Schema `anyOf` for cross-property constraints `required` cannot express
-         * — e.g. "at least one of route/file". Forwarded verbatim to clients by the
-         * server's ListTools handler, so MCP clients see the constraint.
-         */
-        anyOf?: Array<{
-            required: string[];
-        }>;
     };
 }
 /**
@@ -57,3 +49,11 @@ export declare const PDG_QUERY_DEFAULT_LIMIT = 50;
 export declare const PDG_QUERY_MAX_LIMIT = 200;
 export declare const IMPACT_MAX_DEPTH = 32;
 export declare const GITNEXUS_TOOLS: ToolDefinition[];
+/**
+ * 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.
+ */
+export declare const REPO_SCOPED_TOOLS: Set<string>;

package/dist/mcp/tools.js

@@ -141,6 +141,11 @@ SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). W
                     description: 'Include full symbol source code (default: false)',
                     default: false,
                 },
+                maxTokens: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Maximum estimated tokens in the complete formatted MCP response. Explicit request overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.',
+                },
                 repo: {
                     type: 'string',
                     description: 'Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>" (member path keys from group.yaml). Omit when only one indexed repo exists.',
@@ -190,8 +195,8 @@ EXAMPLES:
 • Find method overrides (MRO resolution):
   MATCH (winner:Method)-[r:CodeRelation {type: 'METHOD_OVERRIDES'}]->(loser:Method) RETURN winner.name, winner.filePath, loser.filePath, r.reason
 
-• Find DI-injected implementations (beans injected into a consumer class):
-  MATCH (c:Class {name: 'OrderService'})-[r:CodeRelation]->(impl:Class) WHERE r.type = 'INJECTS' RETURN impl.name, r.reason
+• Find DI-injected providers (provider Classes or synthetic factory declarations):
+  MATCH (c:Class {name: 'OrderService'})-[r:CodeRelation]->(provider) WHERE r.type = 'INJECTS' RETURN provider.name, r.reason
 
 • Detect diamond inheritance:
   MATCH (d:Class)-[:CodeRelation {type: 'EXTENDS'}]->(b1), (d)-[:CodeRelation {type: 'EXTENDS'}]->(b2), (b1)-[:CodeRelation {type: 'EXTENDS'}]->(a), (b2)-[:CodeRelation {type: 'EXTENDS'}]->(a) WHERE b1 <> b2 RETURN d.name, b1.name, b2.name, a.name
@@ -236,10 +241,20 @@ Shows categorized incoming/outgoing references (calls, imports, extends, impleme
 WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
 AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
 
-Handles disambiguation: if multiple symbols share the same name, returns ranked candidates (each with a relevance score) for you to pick from. Use uid for zero-ambiguity lookup, or narrow the search with file_path and/or kind hints.
+Handles disambiguation: if multiple symbols share the same name, returns ranked candidates (each with a relevance score) for you to pick from. Use uid for zero-ambiguity lookup, or narrow the search with file_path and/or kind hints. The ambiguous response carries totalCandidates — the TRUE match count, not candidates[].length — plus candidatesTruncated:true and a "(showing M)" suffix on message when candidates[] is the shorter window.
 
 NOTE: ACCESSES edges (field read/write tracking) are included in context results with reason 'read' or 'write'. CALLS edges resolve through field access chains and method-call chains (e.g., user.address.getCity().save() produces CALLS edges at each step).
 
+COMPLETENESS OF incoming: alongside symbol/incoming/outgoing the result carries the same epistemic envelope impact() returns:
+- epistemic: 'exact' | 'lower-bound' — 'lower-bound' means callers exist that this view provably does not list.
+- boundaries: string[] — one plain-language sentence per reason. Prose for humans; branch on causes instead.
+- causes: { receiverTyping, dispatchBoundary, externalBoundary, undecidedSatisfaction } — machine-readable WHY. Every field counts MISSING THINGS, never sentences:
+  - causes.receiverTyping (unit: call sites) > 0 — RESOLVER GAP: the analyzer dropped that many call sites on this name because it could not type the receiver, so they are missing from incoming. Do not read an absent caller as proof none exists.
+  - causes.externalBoundary (unit: call sites) > 0 — the calls left the indexed program (System.out.println, fetch(...)). NOT a defect: no in-graph node could have been reached. An epistemic:'exact' result can carry this.
+  - causes.dispatchBoundary (unit: symbols) > 0 — DI / interface dispatch: implementations plus interface-level consumers behind a boundary static analysis cannot cross. Irreducible.
+
+REQUIRES RE-INDEX: causes.receiverTyping and causes.externalBoundary come from index-time metadata only a current analyzer writes; against an older index they read as absent/0, which is indistinguishable from "nothing was dropped". Re-run \`gitnexus analyze\` before trusting a zero there.
+
 GROUP MODE: set "repo" to "@<groupName>" to run context in each member repo (aggregated list), or "@<groupName>/<groupRepoPath>" for one member. If you use "@<groupName>" only, the member defaults to the lexicographically first key in group.yaml "repos".
 
 SERVICE: optional monorepo path prefix (case-sensitive path segments). When "repo" starts with "@", prefix-matches resolved symbol file paths; when a hit is outside the prefix, that member returns an empty payload for the symbol. Ignored for a normal indexed repo name.`,
@@ -253,6 +268,10 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup)',
                 },
                 file_path: { type: 'string', description: 'File path to disambiguate common names' },
+                file: {
+                    type: 'string',
+                    description: 'Compatibility alias for file_path; values must agree when both are present',
+                },
                 kind: {
                     type: 'string',
                     description: "Kind filter to disambiguate common names (e.g. 'Function', 'Class', 'Method', 'Interface', 'Constructor')",
@@ -262,6 +281,11 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     description: 'Include full symbol source code (default: false)',
                     default: false,
                 },
+                maxTokens: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Maximum estimated tokens in the complete formatted MCP response. Explicit request overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.',
+                },
                 repo: {
                     type: 'string',
                     description: 'Indexed repository name or path, or group mode "@<groupName>" / "@<groupName>/<memberPath>". Omit if only one repo is indexed.',
@@ -285,7 +309,9 @@ AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ
 
 GIT WORKTREE SUPPORT: GitNexus automatically detects when the MCP server was launched from inside a linked git worktree and runs git diff against that worktree — no extra parameters needed in the common case. Pass "worktree" explicitly only when the server was started from a different directory than the worktree you are editing (e.g., the server runs from the canonical root but your changes are in a linked worktree at a different path).
 
-Returns: changed symbols, affected processes, and a risk summary.`,
+Returns: changed symbols, affected processes, and a risk summary.
+- partial: true — a step failed and was swallowed, so the result is incomplete and risk_level is "unknown" instead of a ranked level. Two causes, with different blast radii: the symbol query (or an unparseable diff) degrades everything — changed_symbols, both counts, and the processes derived from them — while a failed process lookup degrades only affected_processes and the risk read off it, leaving the changed-symbol counts sound. changed_count:0 with partial:true is NOT a clean pre-commit check; re-run before treating the diff as safe.
+- truncated: true — the changed_symbols LISTING was capped for this response. summary.changed_count counts every symbol the run observed: the true total normally, a LOWER BOUND when partial:true. Compare it with the array length rather than trusting the array.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -316,8 +342,24 @@ Returns: changed symbols, affected processes, and a risk summary.`,
         name: 'check',
         description: `Run read-only structural checks against the indexed graph.
 
-Currently detects directed cycles between File nodes connected by IMPORTS edges.
-Returns deterministic cycle paths and a cycle count suitable for CI automation.`,
+Currently detects directed cycles between File nodes connected by IMPORTS edges, counting only
+edges that force a module-initialization order — a deferred import (\`import()\`, or one written
+inside a function body) and a TypeScript \`import type\` are excluded, because neither can make the
+modules impossible to initialize.
+
+READ \`enumeration\` BEFORE \`cycleCount\`:
+- \`enumeration: 'complete'\` — every elementary cycle is listed; \`cycleCount\` is their number.
+- \`enumeration: 'component-representatives'\` — the full enumeration exceeded a safety limit, so
+  \`cycles\` holds ONE representative per circular component, \`truncated\` is true, and
+  \`cycleCount\` is **null**. Do not compare \`cycleCount\` numerically here: \`null > 0\` is false,
+  so a caller keying on it alone concludes "clean" on exactly the most tangled repositories. Use
+  \`status === 'cycles_found'\`.
+
+\`componentCount\` (independent circular components) is present in both modes and is the number to
+act on and to trend: cutting one import can remove thousands of elementary cycles at once, so
+\`cycleCount\` swings wildly for small changes while \`componentCount\` stays stable.
+
+A graph too large to analyze at all returns \`{ error, truncated: true }\` with no \`status\`.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -345,7 +387,9 @@ AFTER THIS: Run detect_changes() to verify no unexpected side effects.
 
 Each edit is tagged with confidence:
 - "graph": found via knowledge graph relationships (high confidence, safe to accept)
-- "text_search": found via regex text search (lower confidence, review carefully)`,
+- "text_search": found via regex text search (lower confidence, review carefully)
+
+Handles disambiguation via context()'s payload verbatim: an ambiguous symbol_name returns status "ambiguous" with ranked candidates and totalCandidates — the TRUE match count, not candidates[].length — plus candidatesTruncated:true and a "(showing M)" suffix on message when candidates[] is the shorter window. Re-call with symbol_uid.`,
         annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -379,17 +423,28 @@ MODE (opt-in): "callgraph" (default) walks symbol→symbol edges (CALLS/IMPORTS/
 
 STATEMENT-ANCHORED PDG SLICE: with mode:'pdg', pass "line" (1-based source line within the target symbol) to seed the dependence slice on the statement at that line and return what depends on it in affectedStatements (line + text). Inter-procedural symbols are still reported through interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket. Without "line", pdg returns whole-symbol inter-procedural reach plus local whole-symbol PDG diagnostics.
 
-PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:2 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:2, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar.
+PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:2 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:2, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar. Return-value-ascent coverage is published structurally at pdgEvidence.ascent — present iff the inter-procedural descent ran, including on an empty slice — with referencesScanned (DISTINCT callees scanned for a CALL_SUMMARY: a distinct-id tally, not a call-site count — two call sites to the same callee count once), returnFlowFound (whether the ascent fired anywhere in the slice), undecodableSummaryCount, examinedComplete (whether that scan covered every callee the index recorded a resolved id for on the visited blocks), incompleteReasons ('traversal-truncated' | 'callee-list-capped' | 'callee-ids-unrecorded'), and callSummaryLayerPresent. Read callSummaryLayerPresent FIRST: false ⇒ a pre-CALL_SUMMARY index, so {referencesScanned:N>0, returnFlowFound:false} is self-consistent and says nothing about the callees — the scan ran, but no layer existed in which a return-flow could be recorded (remedy: re-run gitnexus analyze --pdg). Branch on those fields; the note narrates the same facts in prose for humans and is not a stable contract.
 
 WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
 AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
 
 Output includes:
-- risk: LOW / MEDIUM / HIGH / CRITICAL / UNKNOWN
+- risk: LOW / MEDIUM / HIGH / CRITICAL / UNKNOWN. An upstream walk that resolved ZERO callers reports UNKNOWN, never LOW, and carries riskNote: "safe to change" is a claim about callers and there were none to reason about, so the symbol is either genuinely unused OR reached only through a reference class the index does not record (plain-object property access, a bare-identifier read of a module-scope const). Confirm with a text search before acting on it. Downstream walks are unaffected — an empty downstream result reports resolved callees, not safety.
+- riskNote: string — present only when risk is UNKNOWN; states why the verdict is withheld.
 - summary: direct callers, processes affected, modules affected
 - affected_processes: which execution flows break and at which step
 - affected_modules: which functional areas are hit (direct vs indirect)
 - byDepth: affected symbols grouped by traversal depth (paginated by limit/offset; omitted when summaryOnly:true — use byDepthCounts for totals per depth, pagination object when truncated). Each item includes a processes:[{id,label,processType,step}] field listing the execution flows that symbol participates in. Empty when the symbol has no process membership. Can ALSO be empty when partial:true is set — either the process-aggregation pass hit its cap before detecting affected processes, or per-symbol enrichment was capped on a very large page. When partial:true, do NOT treat processes:[] as proof of no participation; cross-check the top-level affected_processes list.
+- epistemic: 'exact' | 'lower-bound' — whether impactedCount is the whole story. 'lower-bound' means the walk provably missed callers, so the count is a floor. Absent only on skipped probes (ambiguous-candidate lists, group fan-out).
+- boundaries: string[] — one plain-language sentence per reason the count is short. Prose for humans; branch on causes instead.
+- causes: { receiverTyping, dispatchBoundary, externalBoundary, undecidedSatisfaction } — the machine-readable split of WHY, so an agent gating its own edits can tell a fixable analyzer gap from an irreducible one. Every field counts MISSING THINGS, never sentences:
+  - causes.receiverTyping (unit: call sites) > 0 — the RESOLVER GAP signal: the analyzer dropped that many call sites because it could not establish the receiver's type (unresolved constructor, factory, chained expression). Those callers are absent from byDepth. Treat the result as incomplete: grep the symbol name before deleting or renaming.
+  - causes.externalBoundary (unit: call sites) > 0 — those calls left the indexed program (System.out.println, fetch(...), os.environ.*). NOT a defect and NOT a reason the count is short: there is no in-graph node any edge could have reached. An epistemic:'exact' result can carry this.
+  - causes.dispatchBoundary (unit: symbols) > 0 — DI / interface dispatch: that many implementations plus interface-level consumers sit on the far side of a boundary a static walk cannot cross. Irreducible; a compiler refuses here too. A symbol count, not a site count — per-site multiplicity is not retained for these edges — so compare its magnitude with receiverTyping, not its exact value.
+
+  - causes.undecidedSatisfaction (unit: unjudged interface/type pairs) > 0 — the analyzer could not DECIDE whether a type satisfies an interface (a type in a required signature named a package it could not resolve), so no IMPLEMENTS edge exists and no dispatch boundary was left for the walk to notice. Distinct from every cause above, which count decided facts that could not be attributed; this one counts questions never answered. It is the only cause that shortens a result WITHOUT leaving a trace in the graph, so an unhedged zero on a symbol reached only through such an interface would otherwise read as 'nobody calls this'. Usually fixable: it most often means a dependency is missing from the analyzed tree.
+
+REQUIRES RE-INDEX: causes.receiverTyping, causes.externalBoundary and causes.undecidedSatisfaction are read from index-time metadata that only a current analyzer writes. Against an older index they read as absent/0, which is indistinguishable from "nothing was dropped" — re-run \`gitnexus analyze\` before trusting a zero there.
 
 Depth groups:
 - d=1: WILL BREAK (direct callers/importers)
@@ -400,12 +455,12 @@ TIP: For hub symbols (base error classes, shared utilities) with many direct cal
 
 TIP: Default traversal uses CALLS/IMPORTS/EXTENDS/IMPLEMENTS. For class members, include HAS_METHOD and HAS_PROPERTY in relationTypes. For field access analysis, include ACCESSES in relationTypes.
 
-Handles disambiguation: when multiple symbols share the target name, returns ranked candidates (each with a relevance score) instead of silently picking one. Use target_uid for zero-ambiguity lookup, or narrow with file_path and/or kind hints.
+Handles disambiguation: when multiple symbols share the target name, returns ranked candidates (each with a relevance score) instead of silently picking one. Use target_uid for zero-ambiguity lookup, or narrow with file_path and/or kind hints. totalCandidates is the TRUE match count — it reported the capped resolver window before #2787, so it can now exceed candidates.length; candidatesTruncated:true and a "(showing M of N)" suffix on message mark the shorter window.
 
 EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, METHOD_OVERRIDES, METHOD_IMPLEMENTS, ACCESSES
 Confidence: 1.0 = certain, <0.8 = fuzzy match
 
-GROUP MODE: set "repo" to "@<groupName>" for cross-repo impact anchored at the default member (lexicographically first key in group.yaml "repos"), or "@<groupName>/<groupRepoPath>" to choose the member (same path keys as in group.yaml). Phase-1 walk runs in that member; cross-boundary fan-out uses the group bridge.
+GROUP MODE: set "repo" to "@<groupName>" for cross-repo impact anchored at the default member (lexicographically first key in group.yaml "repos"), or "@<groupName>/<groupRepoPath>" to choose the member (same path keys as in group.yaml). Phase-1 walk runs in that member; cross-boundary fan-out uses the group bridge. A cross entry with fanout_status:"not_attempted" proves the declared repository boundary, but its far endpoint has no graph symbol; do not interpret empty by_depth or affected_processes on that entry as a completed zero-impact walk. The fan-out attempts at most 50 neighbour crossings, strongest-confidence first; when it stops early the response carries truncated:true, truncatedRepos, and riskEpistemic:"lower-bound" — dropping a crossing can only move risk DOWN, so treat that risk as a floor, never as a verdict.
 
 SERVICE: optional monorepo path prefix (case-sensitive path segments). When "repo" starts with "@", scopes the local impact walk and cross-repo symbol paths to files under that prefix; ignored for a normal indexed repo name.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
@@ -413,6 +468,14 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
             type: 'object',
             properties: {
                 target: { type: 'string', description: 'Name of function, class, or file to analyze' },
+                name: {
+                    type: 'string',
+                    description: 'Compatibility alias for target; all supplied target aliases must agree',
+                },
+                symbol: {
+                    type: 'string',
+                    description: 'Compatibility alias for target; all supplied target aliases must agree',
+                },
                 target_uid: {
                     type: 'string',
                     description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup, skips target resolution)',
@@ -462,7 +525,7 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                 relationTypes: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, METHOD_OVERRIDES, METHOD_IMPLEMENTS, ACCESSES (default: usage-based, ACCESSES excluded by default). DI fan-out (consumer→implementer) requires explicitly including INJECTS.',
+                    description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, METHOD_OVERRIDES, METHOD_IMPLEMENTS, ACCESSES (default: usage-based, ACCESSES excluded by default). DI edges require INJECTS; Spring proxy/advice edges require ADVISED_BY.',
                 },
                 includeTests: { type: 'boolean', description: 'Include test files (default: false)' },
                 minConfidence: {
@@ -503,6 +566,11 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     description: 'When true, returns target, summary, risk, byDepthCounts, affected_processes, and affected_modules — omits byDepth. Single-repo only; ignored in group mode (@groupName). Use for hub symbols to get actionable signal without output explosion.',
                     default: false,
                 },
+                maxTokens: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Maximum estimated tokens in the complete formatted MCP response. Explicit request overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.',
+                },
                 timeoutMs: {
                     type: 'number',
                     description: 'Wall-clock budget in milliseconds for the Phase-1 local impact leg (default 30000)',
@@ -516,7 +584,7 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     maximum: 3600000,
                 },
             },
-            required: ['target', 'direction'],
+            required: ['direction'],
         },
     },
     {
@@ -528,7 +596,7 @@ Each finding carries the sink category (command-injection, code-injection, path-
 WHEN TO USE: Security review — "what taint findings exist in this repo / file / function?". Requires the repo to be indexed with \`gitnexus analyze --pdg\`; without that layer the tool returns a clear "no taint layer" note, not an error.
 
 ANCHORLESS (no "target"): enumerates all persisted findings for the repo — bounded ("limit", deterministic order), with "totalFindings" and a "truncated" flag.
-ANCHORED ("target" = file path or symbol/function name): full hop detail for that anchor. A file-ish target (contains "/" or an extension) filters by file; a symbol name resolves like context() — ambiguous names return ranked candidates, unknown names return not-found. Symbol anchoring is line-range granular for intra-procedural findings; cross-function findings match when the symbol is the source OR sink function.
+ANCHORED ("target" = file path or symbol/function name): full hop detail for that anchor. A file-ish target (contains "/" or an extension) filters by file; a symbol name resolves like context() — ambiguous names return ranked candidates plus totalCandidates (the TRUE match count, not candidates[].length), candidatesTruncated:true and a "(showing M)" suffix on message when candidates[] is the shorter window; unknown names return not-found. Symbol anchoring is line-range granular for intra-procedural findings; cross-function findings match when the symbol is the source OR sink function.
 
 CONTRACT CAVEATS (absent flows are NOT proof of safety):
 - Cross-function flows ARE modeled (#2084 M4): a source flowing through helper functions into a sink is found, via summary composition over the call graph (context-insensitive — return/call-site merging is accepted).
@@ -573,7 +641,7 @@ MODES:
 
 WHEN TO USE: comprehension ("what guards this statement?"), data-flow tracing within a function, guard-clause discovery. Requires \`gitnexus analyze --pdg\`; without that layer the tool returns a clear "no PDG layer" note, not an error.
 
-ANCHORING (required): \`target\` is a file path or a symbol/function name (resolved like context()). PDG queries are ALWAYS anchored — there is no whole-repo enumeration (an unanchored basic-block path scan is unbounded; LadybugDB has no rel-property index). A symbol target is line-range granular; an ambiguous name returns ranked candidates, unknown returns not-found.
+ANCHORING (required): \`target\` is a file path or a symbol/function name (resolved like context()). PDG queries are ALWAYS anchored — there is no whole-repo enumeration (an unanchored basic-block path scan is unbounded; LadybugDB has no rel-property index). A symbol target is line-range granular; an ambiguous name returns ranked candidates plus totalCandidates (the TRUE match count, not candidates[].length), candidatesTruncated:true and a "(showing M)" suffix on message when candidates[] is the shorter window; unknown returns not-found.
 
 CONTRACT CAVEATS:
 - CDG labels are binary 'T'/'F' in M5/M6; per-case \`switch\` arm conditions are not yet distinguished (every case dispatch is 'T').
@@ -699,9 +767,6 @@ Response shape is keyed on how many routes match, not on the data: exactly one m
                 repo: { type: 'string', description: 'Repository name or path.' },
             },
             required: [],
-            // Exactly one lookup key is needed, but either works (route wins if both
-            // are passed) — so the structural constraint is "at least one of route/file".
-            anyOf: [{ required: ['route'] }, { required: ['file'] }],
         },
     },
     {
@@ -749,6 +814,8 @@ Traverses CALLS edges plus HAS_METHOD (class → member) edges, so a trace can d
 
 Returns: ordered hops with file:line, and an aligned edges[] of edge type + confidence. When no path exists, reports the furthest reachable node so you know where the chain breaks (and truncated: true if a traversal cap was hit first).
 
+Handles disambiguation: an ambiguous from/to name returns status "ambiguous" with role ("from" or "to"), ranked candidates and totalCandidates — the TRUE match count, not candidates[].length — plus candidatesTruncated:true and a "(showing M)" suffix on message when candidates[] is the shorter window. Re-call with from_uid/to_uid.
+
 CROSS-REPO (experimental): pass repo as "@groupName" to trace across repositories in a group. When from/to live in different member repos, the trace stitches the two repo-local segments across a single ContractLink boundary (e.g. an HTTP consumer→provider link), clamped to one crossing. The result adds crossings[] (the bridged contract with matchType/confidence), tags each hop with its member repo, and a notes[] channel for degraded states. The boundary hop is reported with edge type CONTRACT_LINK. Pass pdg:true to also attach the intra-procedural data-flow (REACHING_DEF) for boundary-adjacent segments when those repos were indexed with --pdg; absent a PDG layer it degrades to call-level hops with a note.
 
 DESTINATION TRACE (cross-repo): for an "@groupName" trace, OMIT to/to_uid/to_file to trace 'from' to wherever its outgoing HTTP call lands. The result ends at the provider endpoint (reported by route + file even when the handler is an anonymous function with no nameable symbol). This is the way to follow a client call to a backend handler you cannot name.`,
@@ -758,6 +825,10 @@ DESTINATION TRACE (cross-repo): for an "@groupName" trace, OMIT to/to_uid/to_fil
             properties: {
                 from: { type: 'string', description: 'Source symbol name' },
                 from_uid: { type: 'string', description: 'Source symbol UID (zero-ambiguity)' },
+                file: {
+                    type: 'string',
+                    description: 'Source file path hint for disambiguation (alias for from_file)',
+                },
                 from_file: { type: 'string', description: 'Source file path hint for disambiguation' },
                 to: {
                     type: 'string',
@@ -812,7 +883,7 @@ DESTINATION TRACE (cross-repo): for an "@groupName" trace, OMIT to/to_uid/to_fil
  * `list_repos` and the `group_*` tools are intentionally excluded — they are
  * not single-repo, single-branch operations.
  */
-const BRANCH_SCOPED_TOOLS = new Set([
+export const REPO_SCOPED_TOOLS = new Set([
     'query',
     'cypher',
     'context',
@@ -829,7 +900,7 @@ const BRANCH_SCOPED_TOOLS = new Set([
     'trace',
 ]);
 for (const tool of GITNEXUS_TOOLS) {
-    if (!BRANCH_SCOPED_TOOLS.has(tool.name))
+    if (!REPO_SCOPED_TOOLS.has(tool.name))
         continue;
     if (tool.inputSchema.properties.branch)
         continue;

package/dist/server/analyze-job.d.ts

@@ -14,14 +14,49 @@ export interface AnalyzeJobProgress {
     percent: number;
     message: string;
 }
+export type AnalyzeJobStatus = 'queued' | 'cloning' | 'analyzing' | 'loading' | 'complete' | 'failed';
+/**
+ * A job's outcome is settled — `complete` and `failed` are the only two states
+ * from which nothing more is emitted (see `updateJob`'s immutability guard).
+ *
+ * Exported because terminality is a property of the JOB, and every consumer
+ * that has to decide "is this stream over?" must ask the same question of the
+ * same field. The SSE relay used to decide from the PHASE STRING of a progress
+ * event instead, which let a mid-run `phase: 'complete'` close the stream
+ * before the route had decided the actual outcome (#2790).
+ */
+export declare const isTerminalJobStatus: (status: AnalyzeJobStatus) => boolean;
+/**
+ * Structured detail for a job that ended `failed` while its work PARTIALLY
+ * succeeded — an embedding run that persisted most nodes and dropped a few to
+ * endpoint failures is not the same event as one that produced nothing.
+ *
+ * `AnalyzeJob.status` deliberately gains no `partial` member: the status union
+ * is consumed by the web app, the CLI and every poller, and a new member would
+ * be an unhandled value in each of them. This is additive and optional instead
+ * — absent on every job that is not a partial embedding run, so `JSON.stringify`
+ * omits it and existing payloads stay byte-identical — while giving a client
+ * that wants to distinguish "retry these N nodes" from "nothing worked" enough
+ * to do it (#2790 review). A UI that ignores it still sees the honest `failed`.
+ */
+export interface AnalyzeJobPartialOutcome {
+    /** Which kind of partial result this is; only embedding runs produce one today. */
+    kind: 'embedding-partial';
+    /** Nodes whose rows were dropped and are checkpointed for retry. */
+    pendingNodeCount: number;
+    /** Nodes that completed; their rows are durable. */
+    nodesProcessed: number;
+}
 export interface AnalyzeJob {
     id: string;
-    status: 'queued' | 'cloning' | 'analyzing' | 'loading' | 'complete' | 'failed';
+    status: AnalyzeJobStatus;
     repoUrl?: string;
     repoPath?: string;
     repoName?: string;
     progress: AnalyzeJobProgress;
     error?: string;
+    /** Set only when a terminal `failed` job still persisted usable work. */
+    partial?: AnalyzeJobPartialOutcome;
     startedAt: number;
     completedAt?: number;
     /** Number of times the worker has been retried after a crash. */
@@ -30,6 +65,7 @@ export interface AnalyzeJob {
 export declare class JobManager {
     private jobs;
     private children;
+    private abortControllers;
     private timeouts;
     private emitter;
     private cleanupTimer;
@@ -42,9 +78,11 @@ export declare class JobManager {
     getJob(id: string): AnalyzeJob | undefined;
     /** Return a snapshot of all tracked jobs for inspection. */
     listJobs(): AnalyzeJob[];
-    updateJob(id: string, update: Partial<Pick<AnalyzeJob, 'status' | 'progress' | 'error' | 'repoPath' | 'repoName' | 'completedAt'>>): void;
+    updateJob(id: string, update: Partial<Pick<AnalyzeJob, 'status' | 'progress' | 'error' | 'partial' | 'repoPath' | 'repoName' | 'completedAt'>>): void;
     /** Register a child process for a job — enables cancellation and timeout. */
     registerChild(jobId: string, child: ChildProcess): void;
+    /** Register cancellable in-process work for a job. */
+    registerAbortController(jobId: string, controller: AbortController): void;
     /** Cancel a running job — sends SIGTERM to child process. */
     cancelJob(jobId: string, reason?: string): boolean;
     /** Subscribe to progress events for a job. Returns unsubscribe function. */

package/dist/server/analyze-job.js

@@ -10,12 +10,24 @@
  */
 import { randomUUID } from 'crypto';
 import { EventEmitter } from 'events';
+/**
+ * A job's outcome is settled — `complete` and `failed` are the only two states
+ * from which nothing more is emitted (see `updateJob`'s immutability guard).
+ *
+ * Exported because terminality is a property of the JOB, and every consumer
+ * that has to decide "is this stream over?" must ask the same question of the
+ * same field. The SSE relay used to decide from the PHASE STRING of a progress
+ * event instead, which let a mid-run `phase: 'complete'` close the stream
+ * before the route had decided the actual outcome (#2790).
+ */
+export const isTerminalJobStatus = (status) => status === 'complete' || status === 'failed';
 const JOB_TTL_MS = 60 * 60 * 1000; // 1 hour
 const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 const JOB_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 export class JobManager {
     jobs = new Map();
     children = new Map();
+    abortControllers = new Map();
     timeouts = new Map();
     emitter = new EventEmitter();
     cleanupTimer;
@@ -72,9 +84,10 @@ export class JobManager {
         Object.assign(job, update);
         if (this.isTerminal(job.status)) {
             job.completedAt = job.completedAt ?? Date.now();
+            this.abortControllers.delete(id);
         }
         // Emit exactly one event per updateJob call to prevent SSE double-write
-        if (update.status === 'complete' || update.status === 'failed') {
+        if (update.status !== undefined && isTerminalJobStatus(update.status)) {
             // Terminal event takes precedence — don't also emit the progress event
             this.emitter.emit(`progress:${id}`, {
                 phase: update.status,
@@ -107,6 +120,15 @@ export class JobManager {
             }
         });
     }
+    /** Register cancellable in-process work for a job. */
+    registerAbortController(jobId, controller) {
+        const job = this.jobs.get(jobId);
+        if (!job || this.isTerminal(job.status)) {
+            controller.abort();
+            return;
+        }
+        this.abortControllers.set(jobId, controller);
+    }
     /** Cancel a running job — sends SIGTERM to child process. */
     cancelJob(jobId, reason) {
         const job = this.jobs.get(jobId);
@@ -116,6 +138,8 @@ export class JobManager {
         if (child) {
             child.kill('SIGTERM');
         }
+        this.abortControllers.get(jobId)?.abort();
+        this.abortControllers.delete(jobId);
         this.updateJob(jobId, {
             status: 'failed',
             error: reason || 'Analysis cancelled',
@@ -134,6 +158,9 @@ export class JobManager {
             child.kill('SIGTERM');
         }
         this.children.clear();
+        for (const controller of this.abortControllers.values())
+            controller.abort();
+        this.abortControllers.clear();
         // Clear all timeouts
         for (const timer of this.timeouts.values()) {
             clearTimeout(timer);
@@ -143,13 +170,14 @@ export class JobManager {
         this.emitter.removeAllListeners();
     }
     isTerminal(status) {
-        return status === 'complete' || status === 'failed';
+        return isTerminalJobStatus(status);
     }
     cleanup() {
         const now = Date.now();
         for (const [id, job] of this.jobs) {
             if (this.isTerminal(job.status) && job.completedAt && now - job.completedAt > JOB_TTL_MS) {
                 this.jobs.delete(id);
+                this.abortControllers.delete(id);
             }
         }
     }

package/dist/server/analyze-launch.d.ts

@@ -9,7 +9,7 @@
  * NOTE: this module must live alongside analyze-worker.{ts,js} — the worker
  * path is resolved relative to `import.meta.url`.
  */
-import type { JobManager } from './analyze-job.js';
+import { type JobManager } from './analyze-job.js';
 export interface LaunchDeps {
     jobManager: JobManager;
     backend: {