@colbymchenry/codegraph-darwin-x64 0.9.9 → 1.0.0

package/lib/dist/mcp/tools.js

@@ -5,7 +5,7 @@
  * Defines the tools exposed by the CodeGraph MCP server.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolHandler = exports.tools = void 0;
+exports.ToolHandler = exports.tools = exports.PathRefusalError = exports.NotIndexedError = void 0;
 exports.getExploreBudget = getExploreBudget;
 exports.getExploreOutputBudget = getExploreOutputBudget;
 exports.formatStaleBanner = formatStaleBanner;
@@ -23,6 +23,28 @@ const query_utils_1 = require("../search/query-utils");
 const fs_1 = require("fs");
 const utils_1 = require("../utils");
 const generated_detection_1 = require("../extraction/generated-detection");
+const dynamic_boundaries_1 = require("./dynamic-boundaries");
+/**
+ * An expected, recoverable "codegraph can't serve this" condition — most
+ * importantly a project with no index. The dispatch catch converts these to
+ * SUCCESS-shaped responses (guidance text, NO isError): an `isError: true`
+ * early in a session teaches the agent the toolset is broken and it stops
+ * calling codegraph entirely (observed repeatedly), which is exactly wrong
+ * for conditions the agent can simply work around (use built-in tools for
+ * that codebase / pass projectPath). isError is reserved for "stop trying"
+ * cases: security refusals ({@link PathRefusalError}) and genuine
+ * malfunctions.
+ */
+class NotIndexedError extends Error {
+}
+exports.NotIndexedError = NotIndexedError;
+/**
+ * A security refusal (sensitive system path). Stays `isError: true` WITHOUT
+ * retry guidance — abandoning this path is the desired agent reaction.
+ */
+class PathRefusalError extends Error {
+}
+exports.PathRefusalError = PathRefusalError;
 const path_1 = require("path");
 /** Maximum output length to prevent context bloat (characters) */
 const MAX_OUTPUT_LENGTH = 15000;
@@ -310,6 +332,10 @@ exports.tools = [
                     type: 'string',
                     description: 'Name of the function, method, or class to find callers for',
                 },
+                file: {
+                    type: 'string',
+                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist (e.g. one UserService per app in a monorepo)',
+                },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of callers to return (default: 20)',
@@ -330,6 +356,10 @@ exports.tools = [
                     type: 'string',
                     description: 'Name of the function, method, or class to find callees for',
                 },
+                file: {
+                    type: 'string',
+                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist',
+                },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of callees to return (default: 20)',
@@ -350,6 +380,10 @@ exports.tools = [
                     type: 'string',
                     description: 'Name of the symbol to analyze impact for',
                 },
+                file: {
+                    type: 'string',
+                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist',
+                },
                 depth: {
                     type: 'number',
                     description: 'How many levels of dependencies to traverse (default: 2)',
@@ -362,41 +396,54 @@ exports.tools = [
     },
     {
         name: 'codegraph_node',
-        description: 'SECONDARY (after codegraph_explore): get ONE symbol in full — its location, signature, callers/callees trail, and verbatim body (includeCode=true). When the name is AMBIGUOUS (an overloaded method, or the same method name on different types), it returns EVERY matching definition\'s full body in a single call — so you never need to Read a file to find the specific overload you want. For a heavily-overloaded name, pass `file` (and/or `line`) to pin the exact definition — e.g. the `file:line` a trail or another tool already showed you. Reach for this when explore trimmed a body you need. Use codegraph_explore for several related symbols or the full flow.',
+        description: 'Two modes. (1) READ A FILE — use INSTEAD of the Read tool: pass `file` (a path or basename) with no `symbol` and it returns that file\'s current on-disk source with line numbers, exactly the shape Read gives you (`<n>\\t<line>`, safe to Edit from), narrowable with `offset`/`limit` just like Read — PLUS a one-line note of which files depend on it. Same bytes as Read, faster (served from the index), with the blast radius attached. Use it whenever you would Read a source file. (2) ONE SYMBOL you can name — its location, signature, verbatim source (includeCode=true) and caller/callee trail in one call, so before changing it you see what calls it and what your edit would break. For an AMBIGUOUS name it returns EVERY matching definition\'s body in one call (so you never Read a file to find the right overload); pass `file`/`line` to pin one. Use codegraph_explore for several related symbols or the full flow.',
         inputSchema: {
             type: 'object',
             properties: {
                 symbol: {
                     type: 'string',
-                    description: 'Name of the symbol to get details for',
+                    description: 'Name of the symbol to read (symbol mode). Omit it and pass `file` alone to read a whole file like Read.',
                 },
                 includeCode: {
                     type: 'boolean',
-                    description: 'Include full source code (default: false to minimize context)',
+                    description: 'Symbol mode: include the symbol\'s full body (default: false). Ignored in file mode, which always returns source unless `symbolsOnly` is set.',
                     default: false,
                 },
                 file: {
                     type: 'string',
-                    description: 'Optional: disambiguate an overloaded name to the definition in this file (path or basename, e.g. "harness.rs").',
+                    description: 'A file path or basename (e.g. "harness.rs", "src/auth/session.ts"). Pass it ALONE (no symbol) to READ the file like the Read tool — its full source with line numbers + which files depend on it. Or pass it WITH a symbol to disambiguate an overloaded name to the definition in this file.',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'File mode: 1-based line to start reading from, exactly like Read\'s offset. Defaults to the start of the file.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'File mode: maximum number of lines to return, exactly like Read\'s limit. Defaults to the whole file (capped at 2000 lines, like Read).',
+                },
+                symbolsOnly: {
+                    type: 'boolean',
+                    description: 'File mode: return just the file\'s symbol map + dependents (a cheap structural overview) instead of its source.',
+                    default: false,
                 },
                 line: {
                     type: 'number',
-                    description: 'Optional: disambiguate to the definition at/around this line (use with the file:line a trail showed you).',
+                    description: 'Symbol mode only: disambiguate to the definition at/around this line (use with the file:line a trail showed you).',
                 },
                 projectPath: projectPathProperty,
             },
-            required: ['symbol'],
+            required: [],
         },
     },
     {
         name: 'codegraph_explore',
-        description: 'PRIMARY TOOL — call FIRST for almost any question: how does X work, architecture, a bug, where/what is X, or surveying an area. Returns the verbatim source of the relevant symbols grouped by file in ONE capped call (Read-equivalent — do NOT re-open shown files). Query can be a natural-language question OR a bag of symbol/file names. Usually the ONLY call you need — answers without further search/node/Read/Grep.',
+        description: 'PRIMARY TOOL — call FIRST for almost any question OR before an edit: how does X work, architecture, a bug, where/what is X, surveying an area, or the symbols you are about to change. Returns the verbatim source of the relevant symbols grouped by file in ONE capped call (Read-equivalent — treat the shown source as already Read; do NOT re-open those files), plus the call path among them. Query can be a natural-language question OR a bag of symbol/file names. Usually the ONLY call you need — more accurate context, in far fewer tokens and round-trips than a search/Read/Grep loop.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). Use codegraph_search first to find relevant names.',
+                    description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). For a flow question, name the symbols spanning the flow (e.g. "mutateElement renderScene"). A natural-language question works too — no prior codegraph_search needed.',
                 },
                 maxFiles: {
                     type: 'number',
@@ -460,11 +507,35 @@ exports.tools = [
  */
 function getStaticTools() {
     const raw = process.env.CODEGRAPH_MCP_TOOLS;
-    if (!raw || !raw.trim())
-        return exports.tools;
+    if (!raw || !raw.trim()) {
+        return exports.tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^codegraph_/, '')));
+    }
     const allow = new Set(raw.split(',').map(s => s.trim().replace(/^codegraph_/, '')).filter(Boolean));
     return allow.size ? exports.tools.filter(t => allow.has(t.name.replace(/^codegraph_/, ''))) : exports.tools;
 }
+/**
+ * The MCP tools served by DEFAULT (short names). The other defined tools
+ * (callees, impact, files, status) remain fully functional — handlers stay,
+ * the library API and CLI are untouched, and `CODEGRAPH_MCP_TOOLS` re-enables
+ * any of them — they just aren't LISTED to agents anymore.
+ *
+ * Evidence for the cut (the "adapt the tool to the agent" principle —
+ * fewer tools = fewer mis-picks, and presence itself steers):
+ * - `codegraph_impact` appears in ZERO recorded eval runs ever — its
+ *   blast-radius info already arrives inline on explore (the "Blast radius"
+ *   section) and node (the dependents note), so agents never need the
+ *   standalone tool.
+ * - `codegraph_callees` is redundant by construction: a symbol's body (which
+ *   node returns) IS its callee list, plus the caller/callee trail.
+ * - `codegraph_files` / `codegraph_status`: the tiny-repo audit (see
+ *   getTools) found they "reduce to one grep"; staleness banners already
+ *   inline the pending-sync info on every read tool, and the CLI covers
+ *   diagnostics.
+ * - `codegraph_callers` stays: exhaustive call-site enumeration (every
+ *   caller with file:line, callback registrations labeled, one section per
+ *   same-named definition) is the one job explore/node don't replicate.
+ */
+const DEFAULT_MCP_TOOLS = new Set(['explore', 'node', 'search', 'callers']);
 /**
  * Tool handler that executes tools against a CodeGraph instance
  *
@@ -553,18 +624,22 @@ class ToolHandler {
      */
     getTools() {
         const allow = this.toolAllowlist();
+        // No explicit allowlist → the default 4-tool surface (see
+        // DEFAULT_MCP_TOOLS for the evidence). An allowlist replaces the
+        // default entirely, so any defined tool can be re-enabled.
         let visible = allow
             ? exports.tools.filter(t => allow.has(t.name.replace(/^codegraph_/, '')))
-            : exports.tools;
+            : exports.tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^codegraph_/, '')));
         if (!this.cg)
             return visible;
         try {
             const stats = this.cg.getStats();
             const budget = getExploreBudget(stats.fileCount);
             // Tiny-repo tool gating: on projects under TINY_REPO_FILE_THRESHOLD
-            // files, only expose the 5 core tools (search, context, node,
-            // explore, trace). The 5 omitted tools (callers, callees, impact,
-            // status, files) reduce to one grep at this scale.
+            // files, only expose the core trio (search, node, explore) — one
+            // below even the 4-tool default: at this scale callers, too, reduces
+            // to one grep. (Historical note: the audit below ran when context and
+            // trace still existed; its "5 core tools" are today's trio.)
             //
             // n=2 audits ruled out cutting below 5 tools:
             // - 3-tool gate (search + context + trace): cost regressed on
@@ -619,13 +694,15 @@ class ToolHandler {
         if (!projectPath) {
             if (!this.cg) {
                 const searched = this.defaultProjectHint ?? process.cwd();
-                throw new Error('No CodeGraph project is loaded for this session.\n' +
+                throw new NotIndexedError('No CodeGraph project is loaded for this session.\n' +
                     `Searched for a .codegraph/ directory starting from: ${searched}\n` +
-                    'The index is likely fine — this is a working-directory detection issue: ' +
+                    'If this project IS indexed, this is a working-directory detection issue: ' +
                     "the MCP client launched the server outside your project and didn't report the " +
                     'workspace root. Fix it either way:\n' +
                     '  • Pass projectPath to the tool call, e.g. projectPath: "/absolute/path/to/your/project"\n' +
-                    '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]');
+                    '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]\n' +
+                    'If the project simply has no index, continue with your built-in tools (Read/Grep/Glob) ' +
+                    "and don't call codegraph again this session — the user can run 'codegraph init' to enable it.");
             }
             return this.cg;
         }
@@ -641,13 +718,16 @@ class ToolHandler {
         if ((0, fs_1.existsSync)(projectPath)) {
             const pathError = (0, utils_1.validateProjectPath)(projectPath);
             if (pathError) {
-                throw new Error(pathError);
+                throw new PathRefusalError(pathError);
             }
         }
         // Walk up parent directories to find nearest .codegraph/
         const resolvedRoot = (0, directory_1.findNearestCodeGraphRoot)(projectPath);
         if (!resolvedRoot) {
-            throw new Error(`CodeGraph not initialized in ${projectPath}. Run 'codegraph init' in that project first.`);
+            throw new NotIndexedError(`The project at ${projectPath} isn't indexed with codegraph (no .codegraph/ directory found ` +
+                'walking up from it), so codegraph cannot query it. Use your built-in tools (Read/Grep/Glob) ' +
+                "for that codebase instead, and don't call codegraph for it again this session. " +
+                "Indexing is the user's decision — they can run 'codegraph init' in that project to enable it.");
         }
         // If the path resolves to the default project, reuse the already-open
         // default instance rather than opening a SECOND connection to the same DB.
@@ -926,7 +1006,19 @@ class ToolHandler {
             return this.withStalenessNotice(withWorktree, args.projectPath);
         }
         catch (err) {
-            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}`);
+            // Expected condition, not a malfunction: answer as a SUCCESS so the
+            // agent keeps trusting the toolset for projects that ARE indexed.
+            // (An isError here teaches session-long abandonment — see NotIndexedError.)
+            if (err instanceof NotIndexedError) {
+                return this.textResult(err.message);
+            }
+            // Security refusal: a clean error, no retry encouragement.
+            if (err instanceof PathRefusalError) {
+                return this.errorResult(err.message);
+            }
+            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}. ` +
+                'This is an internal codegraph error — retry the call once; if it persists, ' +
+                'continue without codegraph for this task.');
         }
     }
     /**
@@ -937,7 +1029,11 @@ class ToolHandler {
         if (typeof query !== 'string')
             return query;
         const cg = this.getCodeGraph(args.projectPath);
-        const kind = args.kind;
+        const rawKind = args.kind;
+        // The schema enum says 'type' (what agents naturally reach for); the
+        // NodeKind is 'type_alias'. Without the mapping, kind: "type" silently
+        // matched nothing — a filter value we advertise must work.
+        const kind = rawKind === 'type' ? 'type_alias' : rawKind;
         const rawLimit = Number(args.limit) || 10;
         const limit = (0, utils_1.clamp)(rawLimit, 1, 100);
         const results = cg.searchNodes(query, {
@@ -958,6 +1054,43 @@ class ToolHandler {
         const formatted = this.formatSearchResults(ranked);
         return this.textResult(this.truncateOutput(formatted));
     }
+    /**
+     * Group symbol matches into DISTINCT DEFINITIONS — one group per
+     * (filePath, qualifiedName), so same-file overloads stay together while
+     * unrelated same-named classes across a monorepo's apps (#764: one
+     * `UserService` per NestJS app) are kept apart. Optionally narrowed by a
+     * `file` path/suffix first.
+     */
+    groupDefinitions(nodes, fileFilter) {
+        let pool = nodes;
+        let filteredOut = false;
+        if (fileFilter) {
+            const wanted = fileFilter.replace(/^\.\//, '');
+            const narrowed = pool.filter((n) => n.filePath === wanted || n.filePath.endsWith(wanted) || n.filePath.endsWith(`/${wanted}`));
+            if (narrowed.length > 0) {
+                pool = narrowed;
+            }
+            else {
+                filteredOut = true;
+            }
+        }
+        const byDef = new Map();
+        for (const n of pool) {
+            const key = `${n.filePath}|${n.qualifiedName}`;
+            const group = byDef.get(key);
+            if (group)
+                group.push(n);
+            else
+                byDef.set(key, [n]);
+        }
+        return { groups: [...byDef.values()], filteredOut };
+    }
+    /** Section heading for one distinct definition in grouped output. */
+    definitionHeading(group) {
+        const head = group[0];
+        const line = head.startLine ? `:${head.startLine}` : '';
+        return `### ${head.qualifiedName} (${head.kind}) — ${head.filePath}${line}`;
+    }
     /**
      * Handle codegraph_callers
      */
@@ -967,26 +1100,64 @@ class ToolHandler {
             return symbol;
         const cg = this.getCodeGraph(args.projectPath);
         const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
+        const fileFilter = typeof args.file === 'string' ? args.file : undefined;
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        // Aggregate callers across all matching symbols
-        const seen = new Set();
-        const allCallers = [];
-        for (const node of allMatches.nodes) {
-            for (const c of cg.getCallers(node.id)) {
-                if (!seen.has(c.node.id)) {
-                    seen.add(c.node.id);
-                    allCallers.push(c.node);
+        const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+        const filterNote = filteredOut
+            ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+            : '';
+        const collect = (defNodes) => {
+            const seen = new Set();
+            const callers = [];
+            const labels = new Map();
+            for (const node of defNodes) {
+                for (const c of cg.getCallers(node.id)) {
+                    if (!seen.has(c.node.id)) {
+                        seen.add(c.node.id);
+                        callers.push(c.node);
+                        const label = this.edgeLabel(c.edge);
+                        if (label)
+                            labels.set(c.node.id, label);
+                    }
                 }
             }
+            return { callers, labels };
+        };
+        // Single definition (or same-file overloads): the familiar flat list.
+        if (groups.length === 1) {
+            const { callers, labels } = collect(groups[0]);
+            if (callers.length === 0) {
+                return this.textResult(`No callers found for "${symbol}"${allMatches.note}${filterNote}`);
+            }
+            // A successful `file` narrowing makes the multi-symbol aggregation note
+            // stale — suppress it.
+            const note = fileFilter && !filteredOut ? '' : allMatches.note;
+            const formatted = this.formatNodeList(callers.slice(0, limit), `Callers of ${symbol}`, labels) + note + filterNote;
+            return this.textResult(this.truncateOutput(formatted));
+        }
+        // Multiple DISTINCT definitions (#764): one section per definition so an
+        // agent never mistakes one app's callers for another's. Narrow with
+        // `file` to focus a single definition.
+        const lines = [
+            `## Callers of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)`,
+        ];
+        for (const group of groups) {
+            const { callers, labels } = collect(group);
+            lines.push('', this.definitionHeading(group));
+            if (callers.length === 0) {
+                lines.push('- (no callers)');
+                continue;
+            }
+            for (const node of callers.slice(0, limit)) {
+                const location = node.startLine ? `:${node.startLine}` : '';
+                const label = labels.get(node.id);
+                lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
+            }
         }
-        if (allCallers.length === 0) {
-            return this.textResult(`No callers found for "${symbol}"${allMatches.note}`);
-        }
-        const formatted = this.formatNodeList(allCallers.slice(0, limit), `Callers of ${symbol}`) + allMatches.note;
-        return this.textResult(this.truncateOutput(formatted));
+        return this.textResult(this.truncateOutput(lines.join('\n') + filterNote));
     }
     /**
      * Handle codegraph_callees
@@ -997,26 +1168,61 @@ class ToolHandler {
             return symbol;
         const cg = this.getCodeGraph(args.projectPath);
         const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
+        const fileFilter = typeof args.file === 'string' ? args.file : undefined;
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        // Aggregate callees across all matching symbols
-        const seen = new Set();
-        const allCallees = [];
-        for (const node of allMatches.nodes) {
-            for (const c of cg.getCallees(node.id)) {
-                if (!seen.has(c.node.id)) {
-                    seen.add(c.node.id);
-                    allCallees.push(c.node);
+        const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+        const filterNote = filteredOut
+            ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+            : '';
+        const collect = (defNodes) => {
+            const seen = new Set();
+            const callees = [];
+            const labels = new Map();
+            for (const node of defNodes) {
+                for (const c of cg.getCallees(node.id)) {
+                    if (!seen.has(c.node.id)) {
+                        seen.add(c.node.id);
+                        callees.push(c.node);
+                        const label = this.edgeLabel(c.edge);
+                        if (label)
+                            labels.set(c.node.id, label);
+                    }
                 }
             }
+            return { callees, labels };
+        };
+        if (groups.length === 1) {
+            const { callees, labels } = collect(groups[0]);
+            if (callees.length === 0) {
+                return this.textResult(`No callees found for "${symbol}"${allMatches.note}${filterNote}`);
+            }
+            // A successful `file` narrowing makes the multi-symbol aggregation note
+            // stale — suppress it.
+            const note = fileFilter && !filteredOut ? '' : allMatches.note;
+            const formatted = this.formatNodeList(callees.slice(0, limit), `Callees of ${symbol}`, labels) + note + filterNote;
+            return this.textResult(this.truncateOutput(formatted));
+        }
+        // Multiple DISTINCT definitions (#764): per-definition sections.
+        const lines = [
+            `## Callees of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)`,
+        ];
+        for (const group of groups) {
+            const { callees, labels } = collect(group);
+            lines.push('', this.definitionHeading(group));
+            if (callees.length === 0) {
+                lines.push('- (no callees)');
+                continue;
+            }
+            for (const node of callees.slice(0, limit)) {
+                const location = node.startLine ? `:${node.startLine}` : '';
+                const label = labels.get(node.id);
+                lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
+            }
         }
-        if (allCallees.length === 0) {
-            return this.textResult(`No callees found for "${symbol}"${allMatches.note}`);
-        }
-        const formatted = this.formatNodeList(allCallees.slice(0, limit), `Callees of ${symbol}`) + allMatches.note;
-        return this.textResult(this.truncateOutput(formatted));
+        return this.textResult(this.truncateOutput(lines.join('\n') + filterNote));
     }
     /**
      * Handle codegraph_impact
@@ -1027,34 +1233,51 @@ class ToolHandler {
             return symbol;
         const cg = this.getCodeGraph(args.projectPath);
         const depth = (0, utils_1.clamp)(args.depth || 2, 1, 10);
+        const fileFilter = typeof args.file === 'string' ? args.file : undefined;
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        // Aggregate impact across all matching symbols
-        const mergedNodes = new Map();
-        const mergedEdges = [];
-        const seenEdges = new Set();
-        for (const node of allMatches.nodes) {
-            const impact = cg.getImpactRadius(node.id, depth);
-            for (const [id, n] of impact.nodes) {
-                mergedNodes.set(id, n);
-            }
-            for (const e of impact.edges) {
-                const key = `${e.source}->${e.target}:${e.kind}`;
-                if (!seenEdges.has(key)) {
-                    seenEdges.add(key);
-                    mergedEdges.push(e);
+        const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+        const filterNote = filteredOut
+            ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+            : '';
+        const impactOf = (defNodes) => {
+            const mergedNodes = new Map();
+            const mergedEdges = [];
+            const seenEdges = new Set();
+            for (const node of defNodes) {
+                const impact = cg.getImpactRadius(node.id, depth);
+                for (const [id, n] of impact.nodes) {
+                    mergedNodes.set(id, n);
+                }
+                for (const e of impact.edges) {
+                    const key = `${e.source}->${e.target}:${e.kind}`;
+                    if (!seenEdges.has(key)) {
+                        seenEdges.add(key);
+                        mergedEdges.push(e);
+                    }
                 }
             }
-        }
-        const mergedImpact = {
-            nodes: mergedNodes,
-            edges: mergedEdges,
-            roots: allMatches.nodes.map(n => n.id),
+            return { nodes: mergedNodes, edges: mergedEdges, roots: defNodes.map((n) => n.id) };
         };
-        const formatted = this.formatImpact(symbol, mergedImpact) + allMatches.note;
-        return this.textResult(this.truncateOutput(formatted));
+        // Single definition (or same-file overloads): the familiar merged report.
+        if (groups.length === 1) {
+            const formatted = this.formatImpact(symbol, impactOf(groups[0])) + (fileFilter && !filteredOut ? "" : allMatches.note) + filterNote;
+            return this.textResult(this.truncateOutput(formatted));
+        }
+        // Multiple DISTINCT definitions (#764): a blast radius PER definition —
+        // merging unrelated same-named classes (one UserService per monorepo app)
+        // overstated impact and confused agents. Narrow with `file`.
+        const sections = [
+            `## Impact of ${symbol} — ${groups.length} distinct definitions (each with its own blast radius; narrow with \`file\`)`,
+        ];
+        for (const group of groups) {
+            const head = group[0];
+            const line = head.startLine ? `:${head.startLine}` : '';
+            sections.push('', this.formatImpact(`${head.qualifiedName} (${head.filePath}${line})`, impactOf(group)));
+        }
+        return this.textResult(this.truncateOutput(sections.join('\n') + filterNote));
     }
     /**
      * Describe a synthesized (dynamic-dispatch) edge for human output: how the
@@ -1147,7 +1370,7 @@ class ToolHandler {
             // names (Class.method / Class::method) — the agent's most precise input,
             // resolved exactly by findAllSymbols. (The old strip mangled Class.method
             // into Class, throwing the method away.)
-            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte)$/i;
+            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
             const tokens = [...new Set(query.split(/[\s,()[\]]+/)
                     .map((t) => t.replace(FILE_EXT, '').trim())
                     .filter((t) => t.length >= 3 && /^[A-Za-z_$][\w$]*(?:(?:::|\.)[\w$]+)*$/.test(t)))].slice(0, 16);
@@ -1168,6 +1391,10 @@ class ToolHandler {
             // (`as_sql`, 110 defs across every Expression/Compiler subclass) is NOT here,
             // so naming it doesn't keep every backend variant full and flood the budget.
             const uniqueNamedNodeIds = new Set();
+            // token → resolved node ids: drives the token-coverage check that gates
+            // the dynamic-boundary scan (a token is covered when ANY of its nodes
+            // lands on the main chain — overloads off the chain don't count against).
+            const tokenNodes = new Map();
             for (const t of tokens) {
                 const cands = this.findAllSymbols(cg, t).nodes.filter((n) => CALLABLE.has(n.kind));
                 // A qualified or otherwise-specific name (<=3 hits) keeps all; an
@@ -1180,7 +1407,9 @@ class ToolHandler {
                         const container = segs.length >= 2 ? segs[segs.length - 2] : '';
                         return !!container && segPool.has(container);
                     });
-                for (const n of pick.slice(0, 6)) {
+                const kept = pick.slice(0, 6);
+                tokenNodes.set(t, kept.map((n) => n.id));
+                for (const n of kept) {
                     named.set(n.id, n);
                     if (specific)
                         uniqueNamedNodeIds.add(n.id);
@@ -1188,8 +1417,19 @@ class ToolHandler {
                 if (named.size > 40)
                     break;
             }
-            if (named.size < 2)
-                return EMPTY;
+            if (named.size < 2) {
+                // The agent named a flow but only one side resolved (the other end is
+                // anonymous / runtime-registered / not extracted). The resolved side's
+                // body may still hold the dynamic-dispatch site that EXPLAINS the gap —
+                // surface that instead of silently returning nothing.
+                if (named.size === 0)
+                    return EMPTY;
+                const boundaries = this.buildDynamicBoundaries(cg, [...named.values()], named);
+                if (!boundaries)
+                    return EMPTY;
+                const text = boundaries + '> Full source for these symbols is below.\n';
+                return { text, pathNodeIds: new Set(), namedNodeIds: new Set(named.keys()), uniqueNamedNodeIds };
+            }
             const MAX_HOPS = 7;
             let best = null;
             // BFS the full call graph (incl. synth edges) from each named seed, but
@@ -1237,6 +1477,43 @@ class ToolHandler {
             }
             const hasMain = !!best && best.length >= 3;
             const pathIds = new Set((best ?? []).map((s) => s.node.id));
+            // Dynamic-boundary scan (#687) — fires ONLY when the flow the agent
+            // asked about did not fully connect: some token resolved to nodes but
+            // none of them sit on the main chain (or there is no chain at all). A
+            // healthy flow skips this entirely. Scan order: the chain's dead end
+            // first (where the partial flow stops), then the disconnected symbols,
+            // agent-specific (unique-named) ones first.
+            let boundaryText = '';
+            {
+                const uncovered = [];
+                if (!hasMain) {
+                    // No rendered chain — but a 2-node chain still CONNECTS its two
+                    // endpoints (e.g. via one synthesized hop, surfaced below as a
+                    // dynamic-dispatch link). Only nodes off that short chain are
+                    // unexplained breaks worth scanning.
+                    for (const n of named.values())
+                        if (!pathIds.has(n.id))
+                            uncovered.push(n);
+                }
+                else {
+                    for (const ids of tokenNodes.values()) {
+                        if (ids.length === 0 || ids.some((id) => pathIds.has(id)))
+                            continue;
+                        for (const id of ids) {
+                            const n = named.get(id);
+                            if (n)
+                                uncovered.push(n);
+                        }
+                    }
+                }
+                if (uncovered.length > 0) {
+                    const scanList = [];
+                    if (hasMain)
+                        scanList.push(best[best.length - 1].node);
+                    scanList.push(...uncovered.sort((a, b) => (uniqueNamedNodeIds.has(b.id) ? 1 : 0) - (uniqueNamedNodeIds.has(a.id) ? 1 : 0)));
+                    boundaryText = this.buildDynamicBoundaries(cg, scanList, named);
+                }
+            }
             // Supplementary: dynamic-dispatch (synthesized) edges incident to a NAMED
             // symbol — the indirect hops an agent would otherwise grep/Read to
             // reconstruct ("where do the appended `validators` actually run?"). The
@@ -1255,8 +1532,13 @@ class ToolHandler {
                         break;
                     if (edge.provenance !== 'heuristic' || other.id === n.id)
                         continue;
-                    if (pathIds.has(edge.source) && pathIds.has(edge.target))
-                        continue; // already in the main chain
+                    // "Already in the main chain" only applies when a chain RENDERS
+                    // (hasMain). A 2-node chain populates pathIds but renders nothing,
+                    // so a direct synthesized hop between two named symbols (custom
+                    // EventBus emit→handler, #687) was invisible — too short for Flow,
+                    // skipped here as in-chain. Surface it.
+                    if (hasMain && pathIds.has(edge.source) && pathIds.has(edge.target))
+                        continue;
                     const src = edge.source === n.id ? n : other;
                     const tgt = edge.source === n.id ? other : n;
                     const key = `${src.name}>${tgt.name}`;
@@ -1267,7 +1549,7 @@ class ToolHandler {
                     synthLines.push(`- ${src.name} → ${tgt.name}   [${note ? note.compact : edge.kind}]`);
                 }
             }
-            if (!hasMain && synthLines.length === 0)
+            if (!hasMain && synthLines.length === 0 && !boundaryText)
                 return EMPTY;
             const out = [];
             if (hasMain) {
@@ -1285,6 +1567,8 @@ class ToolHandler {
             if (synthLines.length) {
                 out.push('## Dynamic-dispatch links among your symbols', '(synthesized — the indirect hops grep/Read would reconstruct; the `@file:line` is the wiring site)', '', ...synthLines, '');
             }
+            if (boundaryText)
+                out.push(boundaryText);
             out.push('> Full source for these symbols is below — the call flow among them, followed by their bodies.', '');
             // namedNodeIds = every callable the agent explicitly named (a superset of
             // the spine). A file holding one is something the agent asked to SEE, so it
@@ -1297,6 +1581,163 @@ class ToolHandler {
             return EMPTY;
         }
     }
+    /**
+     * Dynamic-boundary surfacing (#687): when the flow among the agent's named
+     * symbols does not fully connect, scan the disconnected symbols' bodies for
+     * dynamic-dispatch sites (computed member calls, getattr, reflection, typed
+     * message buses, runtime-keyed emits) and ANNOUNCE the boundary — the exact
+     * site, the form, and (when a key is statically visible) candidate targets —
+     * instead of guessing edges. The answer to "how does A reach B" when no
+     * static path exists IS the dispatch site: that's where the flow continues
+     * at runtime. Query-time, deterministic, zero graph mutation; a fully
+     * connected flow never reaches this method.
+     */
+    buildDynamicBoundaries(cg, scanList, named) {
+        const MAX_NOTES = 4; // boundary bullets per explore
+        const MAX_SCAN = 8; // bodies scanned
+        const MAX_TOTAL_CHARS = 200_000;
+        let projectRoot;
+        try {
+            projectRoot = cg.getProjectRoot();
+        }
+        catch {
+            return '';
+        }
+        const notes = [];
+        const seenNode = new Set();
+        const seenSite = new Set();
+        let scanned = 0, charsScanned = 0;
+        for (const node of scanList) {
+            if (notes.length >= MAX_NOTES || scanned >= MAX_SCAN || charsScanned > MAX_TOTAL_CHARS)
+                break;
+            if (seenNode.has(node.id) || !node.startLine || !node.endLine)
+                continue;
+            seenNode.add(node.id);
+            const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, node.filePath);
+            if (!absPath || !(0, fs_1.existsSync)(absPath))
+                continue;
+            let content;
+            try {
+                content = (0, fs_1.readFileSync)(absPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const body = content.split('\n').slice(node.startLine - 1, node.endLine).join('\n');
+            scanned++;
+            charsScanned += body.length;
+            for (const m of (0, dynamic_boundaries_1.scanDynamicDispatch)(body, node.language || '', node.startLine)) {
+                if (notes.length >= MAX_NOTES)
+                    break;
+                const siteKey = `${node.filePath}:${m.line}:${m.form}`;
+                if (seenSite.has(siteKey))
+                    continue;
+                seenSite.add(siteKey);
+                const more = m.moreSites ? ` (+${m.moreSites} more such site${m.moreSites > 1 ? 's' : ''} in this body)` : '';
+                notes.push(`- \`${node.name}\` (${node.filePath}:${m.line}) — ${m.label}: \`${m.snippet}\`${more}`);
+                if (m.key) {
+                    const cand = this.boundaryCandidates(cg, m.key, !!m.keyIsType, named, node.id);
+                    if (cand)
+                        notes.push(`  ${cand}`);
+                }
+            }
+        }
+        if (notes.length === 0)
+            return '';
+        return [
+            '## Dynamic boundaries (the static path ends at runtime dispatch)',
+            '',
+            ...notes,
+            '',
+            '> These sites choose their call target at runtime (registry / bus / reflection) — the site shown IS where the flow continues. To follow it, run codegraph_explore or codegraph_node on a candidate; source for the sites above is included below.',
+            '',
+        ].join('\n');
+    }
+    /**
+     * Shortlist candidate runtime targets for a dispatch key surfaced by
+     * {@link buildDynamicBoundaries}. Exact conventional names first (`save` →
+     * `onSave`/`handleSave`; `CreateCmd` → `CreateCmdHandler`), then FTS, with a
+     * normalized-containment post-filter (FTS camel-splitting is fuzzier than a
+     * candidate list should be). Symbols the agent already named sort first and
+     * are marked — that's the "you were right, here's the wiring" case.
+     */
+    boundaryCandidates(cg, key, keyIsType, named, selfId) {
+        const CALLABLE = new Set(['method', 'function', 'component', 'constructor', 'class']);
+        const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+        const keyNorm = norm(key);
+        if (keyNorm.length < 3)
+            return '';
+        const cands = new Map();
+        const consider = (n) => {
+            if (!n || n.id === selfId || !CALLABLE.has(n.kind) || cands.has(n.id))
+                return;
+            const nameNorm = norm(n.name || '');
+            if (nameNorm.length < 3)
+                return;
+            if (!nameNorm.includes(keyNorm) && !keyNorm.includes(nameNorm))
+                return;
+            cands.set(n.id, n);
+        };
+        const cap = key.charAt(0).toUpperCase() + key.slice(1);
+        const probes = keyIsType
+            ? [`${key}Handler`, key]
+            : [key, `on${cap}`, `handle${cap}`, `${key}Handler`, `handle_${key}`];
+        for (const p of probes) {
+            try {
+                for (const n of cg.getNodesByName(p))
+                    consider(n);
+            }
+            catch { /* exact probe miss is fine */ }
+        }
+        let raw = 0;
+        try {
+            const results = cg.searchNodes(key, { limit: 12 });
+            raw = results.length;
+            for (const r of results)
+                consider(r.node);
+        }
+        catch { /* FTS syntax edge — exact probes already ran */ }
+        if (cands.size === 0) {
+            return raw >= 12 && key.length < 5 ? `key \`${key}\` is too generic to shortlist (${raw}+ matches)` : '';
+        }
+        // A constructor candidate duplicates its class: extractors emit ctors as
+        // METHOD nodes named like the class (C#/Java `Foo::Foo`) — keep the class.
+        const all = [...cands.values()];
+        const classKey = new Set(all.filter((n) => n.kind === 'class').map((n) => `${n.name}|${n.filePath}`));
+        const namedNames = new Set([...named.values()].map((n) => n.name));
+        const isNamed = (n) => named.has(n.id) || namedNames.has(n.name); // the flow's named set holds callables only — transfer the mark to the class
+        const list = all
+            .filter((n) => !(n.kind !== 'class' && classKey.has(`${n.name}|${n.filePath}`)))
+            .sort((a, b) => (isNamed(b) ? 1 : 0) - (isNamed(a) ? 1 : 0))
+            .slice(0, 4)
+            .map((n) => {
+            // Typed-bus convention: the runtime target is the candidate class's
+            // Handle/Execute/Consume method — name the exact node, not just the class.
+            let display = n.qualifiedName || n.name;
+            let at = `${n.filePath}:${n.startLine}`;
+            if (keyIsType && n.kind === 'class') {
+                try {
+                    const HANDLER_METHODS = /^(handle|handleAsync|execute|executeAsync|consume|consumeAsync|run|__invoke)$/i;
+                    const method = cg.getOutgoingEdges(n.id)
+                        .filter((e) => e.kind === 'contains')
+                        .map((e) => { try {
+                        return cg.getNode(e.target);
+                    }
+                    catch {
+                        return null;
+                    } })
+                        .find((c) => !!c && c.kind === 'method' && HANDLER_METHODS.test(c.name));
+                    if (method) {
+                        display = `${n.name}.${method.name}`;
+                        at = `${method.filePath}:${method.startLine}`;
+                    }
+                }
+                catch { /* class without resolvable members — show the class itself */ }
+            }
+            return `\`${display}\` (${at})${isNamed(n) ? ' ← you named this' : ''}`;
+        });
+        return `candidates for key \`${key}\`: ${list.join(', ')}`;
+    }
     /**
      * Compact "blast radius" for the entry symbols of an explore result: who
      * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
@@ -1527,7 +1968,7 @@ class ToolHandler {
         // agent explicitly named is in the subgraph and its file is scored.
         const namedSeedIds = new Set();
         {
-            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte)$/i;
+            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
             const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
             const isTestPath = (p) => /(^|\/)(tests?|specs?|__tests__|testdata|mocks?|fixtures?)\//i.test(p) || /\.(test|spec)\.[a-z]+$/i.test(p);
             const bodyLines = (n) => Math.max(0, (n.endLine ?? n.startLine) - n.startLine);
@@ -1538,8 +1979,12 @@ class ToolHandler {
             // agent writes "DataRequest task validate", the `task`/`validate` it wants
             // are DataRequest's, NOT the same-named overloads in Validation.swift /
             // Concurrency.swift / the abstract base. Used below to bias overloaded
-            // names toward the file/class the query also names.
-            const typeTokens = tokens.filter((o) => /^[A-Z][A-Za-z0-9]{3,}/.test(o));
+            // names toward the file/class the query also names. EXCLUDE the project
+            // name (a PascalCase token a user naturally includes) — it names the whole
+            // repo, so biasing toward it just pulls overloads to whichever stack
+            // embeds it, re-burying the rest (#720).
+            const projectNameTokens = cg.getProjectNameTokens();
+            const typeTokens = tokens.filter((o) => /^[A-Z][A-Za-z0-9]{3,}/.test(o) && !projectNameTokens.has((0, query_utils_1.normalizeNameToken)(o)));
             const inNamedContext = (n) => typeTokens.some((ct) => {
                 const lc = ct.toLowerCase();
                 return n.filePath.toLowerCase().includes(lc) || n.qualifiedName.toLowerCase().includes(lc);
@@ -1596,6 +2041,12 @@ class ToolHandler {
             // Skip import/export nodes — they add noise without information
             if (node.kind === 'import' || node.kind === 'export')
                 continue;
+            // SECURITY (#383): never render the on-disk source of a config-leaf
+            // (Spring application.{yml,properties} key) — its line is `key = <secret>`,
+            // so whole-file/cluster rendering here would push secrets into context
+            // unbidden. The key still appears in the flow/symbol listing above.
+            if ((0, utils_1.isConfigLeafNode)(node))
+                continue;
             const group = fileGroups.get(node.filePath) || { nodes: [], score: 0 };
             group.nodes.push(node);
             // Score: a NAMED-SEED node (a symbol the agent named that FTS missed, now
@@ -2394,14 +2845,26 @@ class ToolHandler {
      * Handle codegraph_node
      */
     async handleNode(args) {
-        const symbol = this.validateString(args.symbol, 'symbol');
-        if (typeof symbol !== 'string')
-            return symbol;
         const cg = this.getCodeGraph(args.projectPath);
         // Default to false to minimize context usage
         const includeCode = args.includeCode === true;
         const fileHint = typeof args.file === 'string' && args.file.trim() ? args.file.trim() : undefined;
         const lineHint = typeof args.line === 'number' && args.line > 0 ? args.line : undefined;
+        const offset = typeof args.offset === 'number' && args.offset > 0 ? Math.floor(args.offset) : undefined;
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.floor(args.limit) : undefined;
+        const symbolsOnly = args.symbolsOnly === true;
+        const symbolRaw = typeof args.symbol === 'string' ? args.symbol.trim() : '';
+        // FILE READ MODE: a `file` with no `symbol` reads that file like the Read
+        // tool — its current on-disk source with line numbers, narrowable with
+        // `offset`/`limit` exactly as Read does — PLUS a one-line blast-radius
+        // header (which files depend on it). `symbolsOnly` returns just the
+        // structural map instead. Backed by the index: same bytes Read gives you.
+        if (!symbolRaw && fileHint) {
+            return this.handleFileView(cg, fileHint, { offset, limit, symbolsOnly });
+        }
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
         let matches = this.findSymbolMatches(cg, symbol);
         if (matches.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
@@ -2487,6 +2950,140 @@ class ToolHandler {
         }
         return this.textResult(this.truncateOutput(out.join('\n')));
     }
+    /**
+     * FILE READ MODE: resolve `fileArg` (path or basename) to an indexed file and
+     * read it like the Read tool — its current on-disk source with line numbers,
+     * narrowable with `offset`/`limit` exactly as Read's are — preceded by a
+     * one-line blast-radius header (which files depend on it). `symbolsOnly`
+     * returns just the structural map (symbols + dependents) instead of source.
+     *
+     * Parity goal: the numbered source block is byte-for-byte the shape Read
+     * returns (`<n>\t<line>`, no padding), so the agent treats it as a Read — only
+     * faster (served from the index) and with the blast radius attached. Security:
+     * yaml/properties files are summarized by key, never dumped (#383); reads go
+     * through validatePathWithinRoot (#527).
+     */
+    async handleFileView(cg, fileArg, opts = {}) {
+        const normalize = (p) => p.replace(/\\/g, '/').replace(/^(?:\.?\/+)+/, '').replace(/\/+$/, '');
+        const wantLower = normalize(fileArg).toLowerCase();
+        const allFiles = cg.getFiles();
+        if (allFiles.length === 0)
+            return this.textResult('No files indexed. Run `codegraph index` first.');
+        let resolved = allFiles.find((f) => f.path.toLowerCase() === wantLower);
+        let candidates = [];
+        if (!resolved) {
+            candidates = allFiles.filter((f) => f.path.toLowerCase().endsWith('/' + wantLower));
+            if (candidates.length === 1)
+                resolved = candidates[0];
+        }
+        if (!resolved && candidates.length === 0) {
+            candidates = allFiles.filter((f) => f.path.toLowerCase().includes(wantLower));
+            if (candidates.length === 1)
+                resolved = candidates[0];
+        }
+        if (!resolved && candidates.length > 1) {
+            return this.textResult([`"${fileArg}" matches ${candidates.length} indexed files — pass a longer path:`, '',
+                ...candidates.slice(0, 25).map((f) => `- ${f.path}`)].join('\n'));
+        }
+        if (!resolved) {
+            return this.textResult(`No indexed file matches "${fileArg}". Codegraph indexes source files; configs/docs it doesn't parse won't appear — Read those directly.`);
+        }
+        const filePath = resolved.path;
+        const nodes = cg.getNodesInFile(filePath)
+            .filter((n) => n.kind !== 'file' && n.kind !== 'import' && n.kind !== 'export')
+            .sort((a, b) => a.startLine - b.startLine);
+        const dependents = cg.getFileDependents(filePath);
+        // Compact, one-line blast radius (codegraph's value-add over a plain Read).
+        const depSummary = dependents.length
+            ? `used by ${dependents.length} file${dependents.length === 1 ? '' : 's'}: ${dependents.slice(0, 8).join(', ')}${dependents.length > 8 ? `, +${dependents.length - 8} more` : ''}`
+            : 'no other indexed file depends on it';
+        // Symbol-map renderer — for symbolsOnly, the config fallback, and read errors.
+        const symbolMap = (heading, limit = 200) => {
+            const lines = [heading];
+            for (const n of nodes.slice(0, limit)) {
+                const sig = n.signature ? ` ${n.signature.replace(/\s+/g, ' ').trim()}` : '';
+                lines.push(`- \`${n.name}\` (${n.kind})${sig} — :${n.startLine}`);
+            }
+            if (nodes.length > limit)
+                lines.push(`- … +${nodes.length - limit} more`);
+            return lines;
+        };
+        // symbolsOnly → the cheap structural overview, no source.
+        if (opts.symbolsOnly) {
+            const out = [`**${filePath}** — ${nodes.length} symbol${nodes.length === 1 ? '' : 's'}, ${depSummary}`, ''];
+            if (nodes.length)
+                out.push(...symbolMap('### Symbols'));
+            else
+                out.push('_No indexed symbols in this file._');
+            out.push('', '> Drop `symbolsOnly` (or pass `offset`/`limit`) to read the source, like Read.');
+            return this.textResult(this.truncateOutput(out.join('\n')));
+        }
+        // SECURITY (#383): never dump a raw config/data file — a yaml/properties
+        // line is `key: <secret>`. Summarize by key and point to a real Read.
+        if (utils_1.CONFIG_LEAF_LANGUAGES.has(resolved.language)) {
+            const out = [`**${filePath}** — configuration/data file, ${depSummary}`, ''];
+            if (nodes.length)
+                out.push(...symbolMap('### Keys (values withheld for safety)'));
+            out.push('', '> Values may be secrets, so codegraph indexes keys only. Read the file directly if you need a value.');
+            return this.textResult(this.truncateOutput(out.join('\n')));
+        }
+        // Read the current bytes from disk through the security chokepoint
+        // (validatePathWithinRoot: blocks `../` traversal and symlink escapes, #527).
+        const abs = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), filePath);
+        let content = null;
+        if (abs) {
+            try {
+                content = (0, fs_1.readFileSync)(abs, 'utf-8');
+            }
+            catch {
+                content = null;
+            }
+        }
+        if (content === null) {
+            const out = [`**${filePath}** — could not read from disk (it may have moved since indexing). ${depSummary}`, ''];
+            if (nodes.length)
+                out.push(...symbolMap('### Symbols'));
+            out.push('', `> Read \`${filePath}\` directly for its current content.`);
+            return this.textResult(this.truncateOutput(out.join('\n')));
+        }
+        // Split exactly as Read does — keep the trailing empty line a final newline
+        // produces (Read numbers it too), so line numbers line up byte-for-byte.
+        const fileLines = content.split('\n');
+        const total = fileLines.length;
+        // Read-parity windowing: `offset`/`limit` mean exactly what they do on Read
+        // (1-based start line; max line count). Default: the whole file, capped like
+        // Read at 2000 lines and bounded by a char budget that tracks explore's
+        // proven-safe ~38k response ceiling. Overflow is stated explicitly (Read
+        // paginates too) — never the silent 15k truncateOutput chop.
+        const CHAR_BUDGET = 38000;
+        const DEFAULT_LIMIT = 2000;
+        const offset = Math.max(1, opts.offset ?? 1);
+        if (offset > total) {
+            return this.textResult(`**${filePath}** has ${total} line${total === 1 ? '' : 's'} — offset ${offset} is past the end. ${depSummary}`);
+        }
+        const maxLines = Math.max(1, opts.limit ?? DEFAULT_LIMIT);
+        const start = offset - 1; // 0-based
+        const header = `**${filePath}** — ${total} lines, ${nodes.length} symbol${nodes.length === 1 ? '' : 's'} · ${depSummary}`;
+        // Numbered lines, byte-for-byte Read's shape: `<n>\t<line>`, no left-pad.
+        const numbered = [];
+        let used = header.length + 8;
+        let i = start;
+        for (; i < total && numbered.length < maxLines; i++) {
+            const ln = `${i + 1}\t${fileLines[i]}`;
+            if (used + ln.length + 1 > CHAR_BUDGET && numbered.length > 0)
+                break;
+            numbered.push(ln);
+            used += ln.length + 1;
+        }
+        const shownEnd = start + numbered.length;
+        const complete = offset === 1 && shownEnd >= total;
+        const out = [header, '', ...numbered];
+        if (!complete) {
+            out.push('', `(lines ${offset}–${shownEnd} of ${total} — pass \`offset\`/\`limit\` for another range, or \`codegraph_node <symbol>\` for one symbol in full)`);
+        }
+        // Self-bounded to CHAR_BUDGET — do NOT route through truncateOutput (15k).
+        return this.textResult(out.join('\n'));
+    }
     /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
     async renderNodeSection(cg, node, includeCode) {
         let code = null;
@@ -2955,15 +3552,36 @@ class ToolHandler {
         }
         return lines.join('\n');
     }
-    formatNodeList(nodes, title) {
+    formatNodeList(nodes, title, labels) {
         const lines = [`## ${title} (${nodes.length} found)`, ''];
         for (const node of nodes) {
             const location = node.startLine ? `:${node.startLine}` : '';
-            // Compact: just name, kind, location
-            lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}`);
+            // Compact: just name, kind, location — plus the relationship when it
+            // isn't a plain call (callback registration, instantiation, …).
+            const label = labels?.get(node.id);
+            lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
         }
         return lines.join('\n');
     }
+    /**
+     * Relationship label for a non-`calls` edge in callers/callees lists. A
+     * function-as-value edge (#756) is the high-signal one: `callers(cb)`
+     * showing "via callback registration" tells the agent this is where the
+     * callback is WIRED, not where it's invoked.
+     */
+    edgeLabel(edge) {
+        if (edge.kind === 'calls')
+            return null;
+        if (edge.metadata?.fnRef === true)
+            return 'callback registration';
+        if (edge.kind === 'instantiates')
+            return 'instantiation';
+        if (edge.kind === 'imports')
+            return 'import';
+        if (edge.kind === 'references')
+            return 'reference';
+        return edge.kind;
+    }
     formatImpact(symbol, impact) {
         const nodeCount = impact.nodes.size;
         // Compact format: just list affected symbols grouped by file