@colbymchenry/codegraph-darwin-x64 0.9.3 → 0.9.4

package/lib/dist/mcp/tools.js

@@ -49,6 +49,20 @@ const os_1 = require("os");
 const path_1 = require("path");
 /** Maximum output length to prevent context bloat (characters) */
 const MAX_OUTPUT_LENGTH = 15000;
+/**
+ * Maximum length for free-form string inputs (query, task, symbol).
+ * Bounds memory and CPU when a buggy or hostile MCP client sends a
+ * huge payload — without this an attacker could ship a 100MB string
+ * and force a full FTS5 scan / OOM the server. 10 000 characters is
+ * far beyond any realistic legitimate query.
+ */
+const MAX_INPUT_LENGTH = 10_000;
+/**
+ * Maximum length for path-like string inputs (projectPath, path
+ * filter, glob pattern). Paths beyond a few thousand chars are
+ * never legitimate and signal abuse or a bug upstream.
+ */
+const MAX_PATH_LENGTH = 4_096;
 /**
  * Rust path roots that have no file-system equivalent — `crate` is the
  * current crate, `super` is the parent module, `self` is the current
@@ -104,12 +118,17 @@ function getExploreOutputBudget(fileCount) {
     }
     if (fileCount < 5000) {
         return {
-            maxOutputChars: 13000,
-            defaultMaxFiles: 6,
-            maxCharsPerFile: 2500,
-            gapThreshold: 10,
-            maxSymbolsInFileHeader: 8,
-            maxEdgesPerRelationshipKind: 8,
+            // Sized so ONE explore can cover a flow that centers on a god-file (e.g.
+            // excalidraw's 415 KB App.tsx): the previous 2500/file returned <1% of such
+            // a file, forcing the agent to Read it anyway. Per-file must also stay ≥ the
+            // smaller <500 tier (3800) — the old 2500 was non-monotonic. Tokens are
+            // cheap relative to a 5–10 Read round-trip spiral; favor sufficiency.
+            maxOutputChars: 28000,
+            defaultMaxFiles: 10,
+            maxCharsPerFile: 6500,
+            gapThreshold: 12,
+            maxSymbolsInFileHeader: 10,
+            maxEdgesPerRelationshipKind: 10,
             includeRelationships: true,
             includeAdditionalFiles: true,
             includeCompletenessSignal: true,
@@ -191,6 +210,18 @@ function markSessionConsulted(sessionId) {
     try {
         const hash = (0, crypto_1.createHash)('md5').update(sessionId).digest('hex').slice(0, 16);
         const markerPath = (0, path_1.join)((0, os_1.tmpdir)(), `codegraph-consulted-${hash}`);
+        // Refuse to follow a pre-planted symlink at the marker path (CWE-59).
+        // O_NOFOLLOW (below) is the atomic, TOCTOU-free guard on POSIX, but it is
+        // `undefined` on Windows (libuv ignores it), so the bitwise-OR silently
+        // drops it and openSync would follow the link. This lstat check closes that
+        // gap cross-platform; ENOENT (path is free) falls through to create it.
+        try {
+            if ((0, fs_1.lstatSync)(markerPath).isSymbolicLink())
+                return;
+        }
+        catch {
+            // No existing entry (or stat failed) — nothing to refuse; proceed.
+        }
         // O_NOFOLLOW makes openSync throw ELOOP if markerPath is already a symlink.
         // O_CREAT + O_TRUNC keep the original "create-or-overwrite" semantics, and
         // mode 0o600 prevents readback by other local users (the marker payload is
@@ -338,7 +369,7 @@ exports.tools = [
     },
     {
         name: 'codegraph_node',
-        description: 'Get detailed info about ONE symbol (location, signature, docstring). Pass includeCode=true for source: a function/method returns its body; a class/interface/struct/enum returns a compact member OUTLINE (fields + method signatures + line numbers), not every method body — Read or codegraph_node a specific member for its body. Keep includeCode=false to minimize context. For SEVERAL related symbols, make ONE codegraph_explore (or codegraph_context) call instead of many node calls — repeated node calls each re-read the whole context and cost far more.',
+        description: 'Get ONE symbol\'s details (location, signature, docstring) PLUS its TRAIL — what it calls and what calls it, each with file:line. Pass includeCode=true for source (functions return their body; containers return a member outline). Use this to WALK the call graph hop-by-hop — node a symbol, then node one of its trail entries — the structural, no-Read way to follow "what calls/triggers/handles X" across files. For a broad first overview of many symbols at once use codegraph_explore; use node to drill along a specific path from there. (If a trail is empty on a non-leaf, that hop is likely dynamic dispatch — read just that line.) Source returned with includeCode is the verbatim live file content — identical to Read.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -358,7 +389,7 @@ exports.tools = [
     },
     {
         name: 'codegraph_explore',
-        description: 'Returns source for SEVERAL related symbols grouped by file, plus a relationship map, in ONE capped call. This is the efficient way to inspect many related symbols at once — strongly prefer it over a series of codegraph_node or Read calls (each separate call re-reads the whole context, so 8 node calls cost far more than 1 explore). Use it after codegraph_context when you need to see the actual source of several symbols. Query with specific symbol/file/code terms, NOT natural-language sentences — run codegraph_search first to find names. Bad: "how are agent prompts loaded and passed to the CLI". Good: "renderStaticScene drawElementOnCanvas ShapeCache renderElement.ts".',
+        description: 'Returns source for SEVERAL related symbols grouped by file, plus a relationship map, in ONE capped call. This is the efficient way to inspect many related symbols at once — strongly prefer it over a series of codegraph_node or Read calls (each separate call re-reads the whole context, so 8 node calls cost far more than 1 explore). Use it after codegraph_context when you need to see the actual source of several symbols. Query with specific symbol/file/code terms, NOT natural-language sentences — run codegraph_search first to find names. Bad: "how are agent prompts loaded and passed to the CLI". Good: "renderStaticScene drawElementOnCanvas ShapeCache renderElement.ts". The code it returns is the VERBATIM live file source (byte-for-byte identical to Read), line-numbered — not a summary; treat files it shows as already Read, no need to re-open them.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -419,6 +450,25 @@ exports.tools = [
             },
         },
     },
+    {
+        name: 'codegraph_trace',
+        description: 'Trace the CALL PATH between two symbols — "how does <from> reach/become <to>?" Returns the chain of functions from one to the other (each hop with file:line and its body inlined, plus the outgoing calls of the destination itself) in ONE call. This is something grep/Read structurally cannot do: there is no text pattern for "the path from A to B". Ideal for flow questions — how an update triggers a render, how a request reaches a handler, how a QuerySet becomes SQL. If no static path exists the chain likely breaks at dynamic dispatch (callbacks/descriptors/metaclasses); the tool says where and points you to codegraph_node to bridge it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from: {
+                    type: 'string',
+                    description: 'Symbol the flow starts at (e.g., "QuerySet", "handleRequest", "mutateElement")',
+                },
+                to: {
+                    type: 'string',
+                    description: 'Symbol the flow should reach (e.g., "execute_sql", "render", "setState")',
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['from', 'to'],
+        },
+    },
 ];
 /**
  * Tool handler that executes tools against a CodeGraph instance
@@ -455,18 +505,44 @@ class ToolHandler {
     hasDefaultCodeGraph() {
         return this.cg !== null;
     }
+    /**
+     * Optional allowlist of exposed tools, parsed from the CODEGRAPH_MCP_TOOLS
+     * env var (comma-separated short names, e.g. "trace,search,node,context").
+     * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
+     * trim the tool surface without rebuilding the client config; the ablated
+     * tool is then truly absent from ListTools rather than merely denied on call.
+     * Matching is on the short form, so "trace" and "codegraph_trace" both work.
+     */
+    toolAllowlist() {
+        const raw = process.env.CODEGRAPH_MCP_TOOLS;
+        if (!raw || !raw.trim())
+            return null;
+        const short = (s) => s.trim().replace(/^codegraph_/, '');
+        const set = new Set(raw.split(',').map(short).filter(Boolean));
+        return set.size ? set : null;
+    }
+    /** Whether a tool name passes the CODEGRAPH_MCP_TOOLS allowlist (if any). */
+    isToolAllowed(name) {
+        const allow = this.toolAllowlist();
+        return !allow || allow.has(name.replace(/^codegraph_/, ''));
+    }
     /**
      * Get tool definitions with dynamic descriptions based on project size.
      * The codegraph_explore tool description includes a budget recommendation
-     * scaled to the number of indexed files.
+     * scaled to the number of indexed files. Honors the CODEGRAPH_MCP_TOOLS
+     * allowlist so a trimmed surface is reflected in ListTools.
      */
     getTools() {
+        const allow = this.toolAllowlist();
+        const visible = allow
+            ? exports.tools.filter(t => allow.has(t.name.replace(/^codegraph_/, '')))
+            : exports.tools;
         if (!this.cg)
-            return exports.tools;
+            return visible;
         try {
             const stats = this.cg.getStats();
             const budget = getExploreBudget(stats.fileCount);
-            return exports.tools.map(tool => {
+            return visible.map(tool => {
                 if (tool.name === 'codegraph_explore') {
                     return {
                         ...tool,
@@ -477,7 +553,7 @@ class ToolHandler {
             });
         }
         catch {
-            return exports.tools;
+            return visible;
         }
     }
     /**
@@ -507,6 +583,17 @@ class ToolHandler {
         if (this.projectCache.has(projectPath)) {
             return this.projectCache.get(projectPath);
         }
+        // Reject sensitive system directories before opening. Only validate a
+        // path that actually exists — a nested or not-yet-created sub-path of a
+        // real project must still be allowed to resolve UP to its .codegraph/
+        // root below (issue #238), so we don't run the existence-checking
+        // validator on paths that are meant to walk up.
+        if ((0, fs_1.existsSync)(projectPath)) {
+            const pathError = (0, utils_1.validateProjectPath)(projectPath);
+            if (pathError) {
+                throw new Error(pathError);
+            }
+        }
         // Walk up parent directories to find nearest .codegraph/
         const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(projectPath);
         if (!resolvedRoot) {
@@ -547,12 +634,35 @@ class ToolHandler {
         this.projectCache.clear();
     }
     /**
-     * Validate that a value is a non-empty string
+     * Validate that a value is a non-empty string within length bounds.
+     *
+     * The `maxLength` cap protects against MCP clients that ship huge
+     * payloads (10MB+ query strings either by accident or maliciously).
+     * Without this, a single oversized input can pin the FTS5 index or
+     * exhaust memory before any real work runs.
      */
-    validateString(value, name) {
+    validateString(value, name, maxLength = MAX_INPUT_LENGTH) {
         if (typeof value !== 'string' || value.length === 0) {
             return this.errorResult(`${name} must be a non-empty string`);
         }
+        if (value.length > maxLength) {
+            return this.errorResult(`${name} exceeds maximum length of ${maxLength} characters (got ${value.length})`);
+        }
+        return value;
+    }
+    /**
+     * Validate an optional path-like string input. Returns the value if
+     * valid (or undefined), or a ToolResult with the error.
+     */
+    validateOptionalPath(value, name) {
+        if (value === undefined || value === null)
+            return undefined;
+        if (typeof value !== 'string') {
+            return this.errorResult(`${name} must be a string`);
+        }
+        if (value.length > MAX_PATH_LENGTH) {
+            return this.errorResult(`${name} exceeds maximum length of ${MAX_PATH_LENGTH} characters (got ${value.length})`);
+        }
         return value;
     }
     /**
@@ -560,6 +670,31 @@ class ToolHandler {
      */
     async execute(toolName, args) {
         try {
+            // Honor the optional tool allowlist (CODEGRAPH_MCP_TOOLS): a trimmed
+            // surface rejects ablated tools defensively even if a client cached them.
+            if (!this.isToolAllowed(toolName)) {
+                return this.errorResult(`Tool ${toolName} is disabled via CODEGRAPH_MCP_TOOLS`);
+            }
+            // Cross-cutting input validation. All tools accept an optional
+            // `projectPath` and most accept either `query`, `task`, or
+            // `symbol` — bound their lengths centrally so individual handlers
+            // can stay focused on tool-specific logic.
+            const pathCheck = this.validateOptionalPath(args.projectPath, 'projectPath');
+            if (typeof pathCheck === 'object' && pathCheck !== undefined) {
+                return pathCheck;
+            }
+            // The `path` and `pattern` properties used by codegraph_files are
+            // also path-shaped — apply the same cap.
+            if (args.path !== undefined) {
+                const check = this.validateOptionalPath(args.path, 'path');
+                if (typeof check === 'object' && check !== undefined)
+                    return check;
+            }
+            if (args.pattern !== undefined) {
+                const check = this.validateOptionalPath(args.pattern, 'pattern');
+                if (typeof check === 'object' && check !== undefined)
+                    return check;
+            }
             switch (toolName) {
                 case 'codegraph_search':
                     return await this.handleSearch(args);
@@ -579,6 +714,8 @@ class ToolHandler {
                     return await this.handleStatus(args);
                 case 'codegraph_files':
                     return await this.handleFiles(args);
+                case 'codegraph_trace':
+                    return await this.handleTrace(args);
                 default:
                     return this.errorResult(`Unknown tool: ${toolName}`);
             }
@@ -635,10 +772,10 @@ class ToolHandler {
             : '';
         // buildContext returns string when format is 'markdown'
         if (typeof context === 'string') {
-            return this.textResult(context + reminder);
+            return this.textResult(this.truncateOutput(context + reminder));
         }
         // If it returns TaskContext, format it
-        return this.textResult(this.formatTaskContext(context) + reminder);
+        return this.textResult(this.truncateOutput(this.formatTaskContext(context) + reminder));
     }
     /**
      * Heuristic to detect if a query looks like a feature request
@@ -764,6 +901,395 @@ class ToolHandler {
         const formatted = this.formatImpact(symbol, mergedImpact) + allMatches.note;
         return this.textResult(this.truncateOutput(formatted));
     }
+    /**
+     * Handle codegraph_trace — shortest CALL PATH between two symbols.
+     *
+     * Exposes GraphTraverser.findPath: the chain of functions from `from` to `to`,
+     * each hop annotated with file:line and the call-site line. This is the
+     * capability grep/Read structurally cannot provide. When no static path
+     * exists, the chain has almost certainly broken at dynamic dispatch
+     * (callbacks, descriptors, metaclasses) — we say so and surface the start
+     * symbol's outgoing calls so the agent bridges the one missing hop with
+     * codegraph_node rather than blindly reading.
+     */
+    async handleTrace(args) {
+        const from = this.validateString(args.from, 'from');
+        if (typeof from !== 'string')
+            return from;
+        const to = this.validateString(args.to, 'to');
+        if (typeof to !== 'string')
+            return to;
+        const cg = this.getCodeGraph(args.projectPath);
+        const fromMatches = this.findAllSymbols(cg, from);
+        if (fromMatches.nodes.length === 0)
+            return this.textResult(`Symbol "${from}" not found in the codebase`);
+        const toMatches = this.findAllSymbols(cg, to);
+        if (toMatches.nodes.length === 0)
+            return this.textResult(`Symbol "${to}" not found in the codebase`);
+        // Trace along call edges only — a true call path. Names can map to several
+        // nodes, so try a few from×to candidate pairs until a usable path turns up.
+        //
+        // MAX_HOPS guard: a BFS shortest path longer than this on a dense call graph
+        // is almost always a spurious wander through unrelated code (django's
+        // `_fetch_all → … → execute_sql` BFS detours through prefetch/filter), not
+        // the real execution flow — and a confident-but-wrong 15-hop trace is worse
+        // than none. Over-cap paths are rejected and reported as "no direct path"
+        // (which, on real code, means the flow breaks at dynamic dispatch).
+        const edgeKinds = ['calls'];
+        const MAX_HOPS = 7;
+        const fromTry = fromMatches.nodes.slice(0, 3);
+        const toTry = toMatches.nodes.slice(0, 3);
+        let path = null;
+        let overCap = null;
+        for (const f of fromTry) {
+            for (const t of toTry) {
+                const p = cg.findPath(f.id, t.id, edgeKinds);
+                if (!p || p.length <= 1)
+                    continue;
+                if (p.length <= MAX_HOPS) {
+                    path = p;
+                    break;
+                }
+                if (!overCap || p.length < overCap.length)
+                    overCap = p;
+            }
+            if (path)
+                break;
+        }
+        if (!path) {
+            // No static path — almost always a dynamic-dispatch break. Surface the
+            // start symbol's outgoing calls so the agent can bridge the gap.
+            const start = fromTry[0];
+            const callees = cg.getCallees(start.id).slice(0, 10)
+                .map(c => `${c.node.name} (${c.node.filePath}:${c.node.startLine})`);
+            const lines = [
+                `No direct call path from "${from}" to "${to}".`,
+                '',
+                (overCap
+                    ? `(Only a ${overCap.length}-hop indirect chain connects them — almost certainly a BFS wander through unrelated code, not the real flow.) `
+                    : '') +
+                    'The direct chain most likely breaks at **dynamic dispatch** (a callback, descriptor, ' +
+                    'metaclass, or attribute-as-callable) that static parsing cannot resolve into an edge. ' +
+                    `Inspect \`${start.name}\` (${start.filePath}:${start.startLine}) with codegraph_node ` +
+                    '(includeCode=true) — its body usually shows the dynamic call to follow next.',
+            ];
+            if (callees.length > 0) {
+                lines.push('', `**${start.name} statically calls:** ${callees.join(', ')}`);
+            }
+            return this.textResult(lines.join('\n') + fromMatches.note + toMatches.note);
+        }
+        const lines = [
+            `## Trace: ${from} → ${to}`,
+            '',
+            `Full execution path below — ${path.length} hops, each with its body, plus what the destination calls. This is the complete flow; answer from it.`,
+            '',
+            `${path.length} hops:`,
+            '',
+        ];
+        // Inline what each hop needs so the agent doesn't Read/Grep to get it: the
+        // call-site source line, the registration site for dynamic-dispatch hops, AND
+        // the hop's own body (capped per hop so the trace stays path-scoped). Earlier
+        // versions inlined only the call-site line, which left agents calling explore
+        // or Read for the bodies — the exact follow-up the ablation experiment measured.
+        const fileCache = new Map();
+        for (let i = 0; i < path.length; i++) {
+            const step = path[i];
+            if (step.edge) {
+                const synth = this.synthEdgeNote(step.edge);
+                if (synth) {
+                    lines.push(`   ↓ ${synth.label}`);
+                    if (synth.registeredAt) {
+                        const regSrc = this.sourceLineAt(cg, synth.registeredAt, fileCache);
+                        lines.push(`     ↳ registered at ${synth.registeredAt}${regSrc ? `   ${regSrc}` : ''}`);
+                    }
+                }
+                else {
+                    // The call happens in the PREVIOUS hop's file at edge.line.
+                    const prev = path[i - 1];
+                    const ref = prev && step.edge.line ? `${prev.node.filePath}:${step.edge.line}` : undefined;
+                    const callSrc = this.sourceLineAt(cg, ref, fileCache);
+                    lines.push(`   ↓ ${step.edge.kind}${step.edge.line ? `@${step.edge.line}` : ''}${callSrc ? `   ${callSrc}` : ''}`);
+                }
+            }
+            lines.push(`${i + 1}. ${step.node.name} (${step.node.filePath}:${step.node.startLine}-${step.node.endLine})`);
+            const body = this.sourceRangeAt(cg, step.node.filePath, step.node.startLine, step.node.endLine, fileCache, 60, 1800);
+            if (body)
+                lines.push(body);
+        }
+        // The "last mile": what the destination does next. Agents otherwise explore/Read
+        // for exactly this (e.g. renderStaticScene → _renderStaticScene → the canvas draw),
+        // so inlining the destination's callees is what actually stops the investigation —
+        // sufficiency, not a "don't explore" instruction.
+        const dest = path[path.length - 1].node;
+        const destCallees = cg.getCallees(dest.id)
+            .filter(c => !path.some(p => p.node.id === c.node.id))
+            .slice(0, 6);
+        if (destCallees.length > 0) {
+            lines.push('', `### \`${dest.name}\` then calls (the destination's immediate work):`);
+            for (const c of destCallees) {
+                lines.push('', `- ${c.node.name} (${c.node.filePath}:${c.node.startLine}-${c.node.endLine})`);
+                const body = this.sourceRangeAt(cg, c.node.filePath, c.node.startLine, c.node.endLine, fileCache, 16, 600);
+                if (body)
+                    lines.push(body);
+            }
+        }
+        lines.push('', '> Full path + every hop body + the destination\'s calls are inlined above — the complete flow. Answer from it; a Read is only needed to chase a specific local variable\'s data-flow.');
+        return this.textResult(this.truncateOutput(lines.join('\n')));
+    }
+    /**
+     * Describe a synthesized (dynamic-dispatch) edge for human output: how the
+     * callback was wired up — the bridge static parsing can't see. Returns null
+     * for ordinary static edges. Used by trace + the node trail so a synthesized
+     * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
+     */
+    synthEdgeNote(edge) {
+        if (!edge || edge.provenance !== 'heuristic')
+            return null;
+        const m = edge.metadata;
+        const registeredAt = typeof m?.registeredAt === 'string' ? m.registeredAt : undefined;
+        const at = registeredAt ? ` @${registeredAt}` : '';
+        if (m?.synthesizedBy === 'callback') {
+            const via = m.via ? `\`${String(m.via)}\`` : 'a registrar';
+            const field = m.field ? ` on .${String(m.field)}` : '';
+            return {
+                label: `callback — registered via ${via}${field} (dynamic dispatch)`,
+                compact: `dynamic: callback via ${via}${at}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'event-emitter') {
+            const ev = m.event ? `\`${String(m.event)}\`` : 'an event';
+            return {
+                label: `event ${ev} — emit → handler (dynamic dispatch)`,
+                compact: `dynamic: event ${ev}${at}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'react-render') {
+            return {
+                label: `React re-render — \`setState\` re-runs render() (dynamic dispatch)`,
+                compact: `dynamic: React re-render via setState${at}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'jsx-render') {
+            const child = m.via ? `<${String(m.via)}>` : 'a child component';
+            return {
+                label: `renders ${child} (JSX child — dynamic dispatch)`,
+                compact: `dynamic: renders ${child}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'vue-handler') {
+            const ev = m.event ? `@${String(m.event)}` : 'a template event';
+            return {
+                label: `Vue template handler — bound to ${ev} (dynamic dispatch)`,
+                compact: `dynamic: Vue ${ev} handler`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'interface-impl') {
+            return {
+                label: `interface/abstract dispatch — runs the implementation override (dynamic dispatch)`,
+                compact: `dynamic: interface → impl${at}`,
+                registeredAt,
+            };
+        }
+        return null;
+    }
+    /**
+     * Read one trimmed source line at "relpath:line" (relative to the project
+     * root). `cache` holds split file contents so a multi-hop trace reads each
+     * file at most once. Returns null if the file/line can't be resolved.
+     */
+    sourceLineAt(cg, ref, cache) {
+        if (!ref)
+            return null;
+        const i = ref.lastIndexOf(':');
+        if (i < 0)
+            return null;
+        const filePath = ref.slice(0, i);
+        const line = parseInt(ref.slice(i + 1), 10);
+        if (!Number.isFinite(line) || line < 1)
+            return null;
+        let fileLines = cache.get(filePath);
+        if (!fileLines) {
+            const abs = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), filePath);
+            if (!abs || !(0, fs_1.existsSync)(abs))
+                return null;
+            try {
+                fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+            }
+            catch {
+                return null;
+            }
+            cache.set(filePath, fileLines);
+        }
+        const raw = fileLines[line - 1];
+        if (raw == null)
+            return null;
+        const t = raw.trim();
+        return t.length > 160 ? t.slice(0, 157) + '…' : t;
+    }
+    /**
+     * Read a hop's body — filePath lines [startLine..endLine] — for inlining into
+     * a trace, capped (lines + chars) so the whole path stays path-scoped even on
+     * a 7-hop chain. Dedents to the body's own indentation and marks truncation.
+     * Shares `cache` with sourceLineAt so each file is read at most once per trace.
+     */
+    sourceRangeAt(cg, filePath, startLine, endLine, cache, maxLines = 28, maxChars = 1200) {
+        if (!Number.isFinite(startLine) || startLine < 1)
+            return null;
+        let fileLines = cache.get(filePath);
+        if (!fileLines) {
+            const abs = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), filePath);
+            if (!abs || !(0, fs_1.existsSync)(abs))
+                return null;
+            try {
+                fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+            }
+            catch {
+                return null;
+            }
+            cache.set(filePath, fileLines);
+        }
+        const end = Number.isFinite(endLine) && endLine >= startLine ? endLine : startLine;
+        let slice = fileLines.slice(startLine - 1, end);
+        if (slice.length === 0)
+            return null;
+        let omitted = 0;
+        if (slice.length > maxLines) {
+            omitted = slice.length - maxLines;
+            slice = slice.slice(0, maxLines);
+        }
+        const nonBlank = slice.filter(l => l.trim().length > 0);
+        const dedent = nonBlank.length ? Math.min(...nonBlank.map(l => l.length - l.trimStart().length)) : 0;
+        let text = slice.map((l, i) => `      ${startLine + i}\t${l.slice(dedent)}`).join('\n');
+        if (text.length > maxChars) {
+            text = text.slice(0, maxChars).replace(/\n[^\n]*$/, '');
+            omitted = Math.max(omitted, 1);
+        }
+        if (omitted > 0)
+            text += `\n      … (+${omitted} more line${omitted === 1 ? '' : 's'})`;
+        return text;
+    }
+    /**
+     * Flow-from-named-symbols: an agent's codegraph_explore query is a bag of
+     * symbol names that usually spans the flow it's investigating (e.g.
+     * "PmsProductController getList PmsProductService list PmsProductServiceImpl").
+     * Surface the longest call chain AMONG those named symbols — scoped to what the
+     * agent explicitly named, so (unlike a fuzzy relevance set) there's no
+     * wrong-feature wandering. Rides synthesized edges, so controller→service-
+     * interface→impl shows up. Returns '' if no chain of >=3 nodes exists.
+     *
+     * Ambiguous tokens (Java `list` → dozens of nodes) are disambiguated by
+     * CO-NAMING: the agent names the class too, so we keep only `list` candidates
+     * whose qualifiedName contains another named token (`PmsProductServiceImpl::list`),
+     * dropping unrelated `OmsOrderService::list`.
+     */
+    buildFlowFromNamedSymbols(cg, query) {
+        try {
+            const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
+            // Strip only a REAL file extension (Create.cs → Create); KEEP qualified
+            // 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 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);
+            if (tokens.length < 2)
+                return '';
+            // Pool of name SEGMENTS (Class + method from every token) used to
+            // disambiguate an ambiguous SIMPLE name: keep a candidate only if its
+            // CONTAINER class is itself named in the query.
+            const segPool = new Set();
+            for (const t of tokens)
+                for (const s of t.toLowerCase().split(/::|\./))
+                    if (s)
+                        segPool.add(s);
+            const named = 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
+                // ambiguous simple name keeps only candidates whose container is named.
+                const pick = cands.length <= 3
+                    ? cands
+                    : cands.filter((n) => {
+                        const segs = (n.qualifiedName || '').toLowerCase().split(/::|\./).filter(Boolean);
+                        const container = segs.length >= 2 ? segs[segs.length - 2] : '';
+                        return !!container && segPool.has(container);
+                    });
+                for (const n of pick.slice(0, 6))
+                    named.set(n.id, n);
+                if (named.size > 40)
+                    break;
+            }
+            if (named.size < 2)
+                return '';
+            const MAX_HOPS = 7;
+            let best = null;
+            // BFS the full call graph (incl. synth edges) from each named seed, but
+            // only ACCEPT a sink that is also named — both ends anchored to symbols the
+            // agent named, so the chain stays on-topic while bridging intermediates
+            // (e.g. the exact interface overload) that the token resolution missed.
+            for (const seed of [...named.values()].slice(0, 8)) {
+                const parent = new Map();
+                parent.set(seed.id, { prev: null, edge: null, node: seed });
+                const q = [{ id: seed.id, depth: 0, streak: 0 }];
+                let deep = null, deepDepth = 0;
+                const MAX_BRIDGE = 1; // ≤1 consecutive UNNAMED hop: bridge one missing intermediate, never wander a god-function's fan-out
+                for (let h = 0; h < q.length && parent.size < 1500; h++) {
+                    const { id, depth, streak } = q[h];
+                    if (id !== seed.id && named.has(id) && depth > deepDepth) {
+                        deep = id;
+                        deepDepth = depth;
+                    }
+                    if (depth >= MAX_HOPS - 1)
+                        continue;
+                    for (const c of cg.getCallees(id)) {
+                        if (c.edge.kind !== 'calls' || parent.has(c.node.id))
+                            continue;
+                        const newStreak = named.has(c.node.id) ? 0 : streak + 1;
+                        if (newStreak > MAX_BRIDGE)
+                            continue;
+                        parent.set(c.node.id, { prev: id, edge: c.edge, node: c.node });
+                        q.push({ id: c.node.id, depth: depth + 1, streak: newStreak });
+                    }
+                }
+                if (!deep)
+                    continue;
+                const chain = [];
+                let cur = deep;
+                while (cur) {
+                    const p = parent.get(cur);
+                    if (!p)
+                        break;
+                    chain.push({ node: p.node, edge: p.edge });
+                    cur = p.prev;
+                }
+                chain.reverse();
+                if (!best || chain.length > best.length)
+                    best = chain;
+            }
+            if (!best || best.length < 3)
+                return '';
+            const out = ['## Flow (call path among the symbols you queried)', ''];
+            for (let i = 0; i < best.length; i++) {
+                const step = best[i];
+                if (step.edge) {
+                    const sy = this.synthEdgeNote(step.edge);
+                    out.push(`   ↓ ${sy ? sy.compact : step.edge.kind}`);
+                }
+                out.push(`${i + 1}. ${step.node.name} (${step.node.filePath}:${step.node.startLine})`);
+            }
+            out.push('', '> Full source for these symbols is below; codegraph_trace(from,to) for the exact path between two endpoints.', '');
+            return out.join('\n');
+        }
+        catch {
+            return '';
+        }
+    }
     /**
      * Handle codegraph_explore — deep exploration in a single call
      *
@@ -805,6 +1331,43 @@ class ToolHandler {
         if (subgraph.nodes.size === 0) {
             return this.textResult(`No relevant code found for "${query}"`);
         }
+        // Graph-aware glue: findRelevantContext builds the subgraph from name/text
+        // search, so a method that BRIDGES named symbols — e.g. App.tsx's
+        // triggerRender, which calls the named triggerUpdate — is never a search hit
+        // and gets missed, forcing the agent to Read the file to trace it. Pull in
+        // the callers/callees of the entry (root) nodes, but ONLY those that live in
+        // files the subgraph already surfaces (where the agent reads to fill gaps),
+        // so we add wiring without dragging in unrelated files. These get an
+        // importance boost below so they survive the per-file cluster budget.
+        const glueNodeIds = new Set();
+        const subgraphFiles = new Set();
+        for (const n of subgraph.nodes.values())
+            subgraphFiles.add(n.filePath);
+        const GLUE_NODE_CAP = 60;
+        for (const rootId of subgraph.roots) {
+            if (glueNodeIds.size >= GLUE_NODE_CAP)
+                break;
+            let neighbors = [];
+            try {
+                neighbors = [
+                    ...cg.getCallers(rootId).map(c => c.node),
+                    ...cg.getCallees(rootId).map(c => c.node),
+                ];
+            }
+            catch {
+                continue;
+            }
+            for (const nb of neighbors) {
+                if (glueNodeIds.size >= GLUE_NODE_CAP)
+                    break;
+                if (subgraph.nodes.has(nb.id))
+                    continue;
+                if (!subgraphFiles.has(nb.filePath))
+                    continue;
+                subgraph.nodes.set(nb.id, nb);
+                glueNodeIds.add(nb.id);
+            }
+        }
         // Step 2: Group nodes by file, score by relevance
         const fileGroups = new Map();
         const entryNodeIds = new Set(subgraph.roots);
@@ -905,6 +1468,8 @@ class ToolHandler {
         // Step 4: Read contiguous file sections
         lines.push('### Source Code');
         lines.push('');
+        lines.push('> The code below is the **verbatim, current on-disk source** of these files — re-read from disk on this call and line-numbered, byte-for-byte identical to what the Read tool returns. It is NOT a summary, outline, or stale cache. Treat each block as a Read you have already performed: do not Read a file shown here.');
+        lines.push('');
         let totalChars = lines.join('\n').length;
         let filesIncluded = 0;
         let anyFileTrimmed = false;
@@ -925,6 +1490,35 @@ class ToolHandler {
             }
             const fileLines = fileContent.split('\n');
             const lang = group.nodes[0]?.language || '';
+            // Whole-small-file rule: if a relevant file is small enough to afford,
+            // return it ENTIRELY instead of clustering. Clustering exists to tame
+            // god-files (App.tsx ~13k lines); on a ~134-line component a cluster is a
+            // lossy subset of a file the agent will just Read in full anyway — costing
+            // a round-trip and a re-read every later turn. Reserve clustering for files
+            // too big to ship whole. Still bounded by the total maxOutputChars check.
+            const WHOLE_FILE_MAX_LINES = 220;
+            const WHOLE_FILE_MAX_CHARS = budget.maxCharsPerFile * 3;
+            if (fileLines.length <= WHOLE_FILE_MAX_LINES && fileContent.length <= WHOLE_FILE_MAX_CHARS) {
+                const body = fileContent.replace(/\n+$/, '');
+                let wholeSection = exploreLineNumbersEnabled() ? numberSourceLines(body, 1) : body;
+                const uniqSymbols = [...new Set(group.nodes
+                        .filter(n => n.kind !== 'import' && n.kind !== 'export')
+                        .map(n => `${n.name}(${n.kind})`))];
+                const headerNames = uniqSymbols.slice(0, budget.maxSymbolsInFileHeader);
+                const omitted = uniqSymbols.length - headerNames.length;
+                const wholeHeader = `#### ${filePath} — ${omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', ')}`;
+                if (totalChars + wholeSection.length + 200 > budget.maxOutputChars) {
+                    const remaining = budget.maxOutputChars - totalChars - 200;
+                    if (remaining < 500)
+                        break;
+                    wholeSection = wholeSection.slice(0, remaining) + '\n... (trimmed) ...';
+                    anyFileTrimmed = true;
+                }
+                lines.push(wholeHeader, '', '```' + lang, wholeSection, '```', '');
+                totalChars += wholeSection.length + 200;
+                filesIncluded++;
+                continue;
+            }
             // Cluster nearby symbols to avoid reading huge gaps between distant symbols.
             // Sort by start line, then merge overlapping/adjacent ranges (within the
             // adaptive gap threshold). Include both node ranges AND edge source
@@ -953,6 +1547,8 @@ class ToolHandler {
                 let importance = 1;
                 if (entryNodeIds.has(n.id))
                     importance = 10;
+                else if (glueNodeIds.has(n.id))
+                    importance = 6; // bridging caller/callee of an entry
                 else if (connectedToEntry.has(n.id))
                     importance = 3;
                 return { start: n.startLine, end: n.endLine, name: n.name, kind: n.kind, importance };
@@ -1145,7 +1741,7 @@ class ToolHandler {
                 .sort((a, b) => b[1].score - a[1].score);
             const remainingFiles = [...remainingRelevant, ...peripheralFiles];
             if (remainingFiles.length > 0) {
-                lines.push('### Additional relevant files (not shown)');
+                lines.push('### Not shown above — explore these names for their source');
                 lines.push('');
                 for (const [filePath, group] of remainingFiles.slice(0, 10)) {
                     const symbols = group.nodes.map(n => `${n.name}:${n.startLine}`).join(', ');
@@ -1163,11 +1759,11 @@ class ToolHandler {
         if (budget.includeCompletenessSignal) {
             lines.push('');
             lines.push('---');
-            lines.push(`> **Complete source code is included above for ${filesIncluded} files.** You do NOT need to re-read these files — the relevant sections are already shown in full. Only use Read/Grep for files listed under "Additional relevant files" if you need more detail.`);
+            lines.push(`> **Complete source for ${filesIncluded} files is included above — do NOT re-read them.** If your question also needs files/symbols listed under "Not shown above" (or any area this call didn't cover), make ANOTHER codegraph_explore targeting those names — it returns the same source with line numbers and is cheaper and more complete than reading. Reserve Read for a single specific line range explore can't surface.`);
         }
         else if (anyFileTrimmed) {
             lines.push('');
-            lines.push(`> Some file sections were trimmed for size. Use \`codegraph_node\` or Read for the full source if needed.`);
+            lines.push(`> Some file sections were trimmed for size. For a specific symbol you still need, run another \`codegraph_explore\` (or \`codegraph_node\`) with its exact name — line-numbered source, cheaper and more complete than Read.`);
         }
         // Add explore budget note based on project size
         if (budget.includeBudgetNote) {
@@ -1175,7 +1771,7 @@ class ToolHandler {
                 const stats = cg.getStats();
                 const callBudget = getExploreBudget(stats.fileCount);
                 lines.push('');
-                lines.push(`> **Explore budget: ${callBudget} calls max for this project (${stats.fileCount.toLocaleString()} files indexed).** Stop exploring and synthesize your answer once you've used ${callBudget} calls — do NOT make additional explore calls beyond this budget.`);
+                lines.push(`> **Explore budget: ${callBudget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).** Each call covers ~6 files; if your question spans more, spend your remaining calls on the uncovered area BEFORE falling back to Read — another explore is cheaper and more complete than reading those files. Synthesize once you've used ${callBudget}.`);
             }
             catch {
                 // Stats unavailable — skip budget note
@@ -1187,12 +1783,12 @@ class ToolHandler {
         // maxOutputChars (observed 30k against a 28k tier cap). A fat explore
         // payload persists in the agent's context and is re-read as cache-input
         // on every subsequent turn, so the overrun is paid many times over.
-        const output = lines.join('\n');
+        const output = this.buildFlowFromNamedSymbols(cg, query) + lines.join('\n');
         if (output.length > budget.maxOutputChars) {
             const cut = output.slice(0, budget.maxOutputChars);
             const lastNewline = cut.lastIndexOf('\n');
             const safe = lastNewline > budget.maxOutputChars * 0.8 ? cut.slice(0, lastNewline) : cut;
-            return this.textResult(safe + '\n\n... (explore output truncated to budget — use codegraph_node or Read for more)');
+            return this.textResult(safe + '\n\n... (output truncated to budget; the source above is complete and verbatim — treat it as already Read. For any area not covered, run another codegraph_explore with the specific names — do NOT Read these files.)');
         }
         return this.textResult(output);
     }
@@ -1226,9 +1822,50 @@ class ToolHandler {
                 code = await cg.getCode(match.node.id);
             }
         }
-        const formatted = this.formatNodeDetails(match.node, code, outline) + match.note;
+        const trail = this.formatTrail(cg, match.node);
+        const formatted = this.formatNodeDetails(match.node, code, outline) + trail + match.note;
         return this.textResult(this.truncateOutput(formatted));
     }
+    /**
+     * Build the "trail" for a symbol: its direct callees (what it calls) and
+     * callers (what calls it), each with file:line — so codegraph_node doubles as
+     * the structural Grep→Read→expand primitive: a spot PLUS where to go next.
+     * Capped to stay cheap. Walk the graph by calling codegraph_node on a trail
+     * entry; no Read needed for covered hops. Empty edges on a non-leaf often mean
+     * dynamic dispatch the static graph couldn't resolve — that absence is itself
+     * a signal (read that one hop) rather than a dead end.
+     */
+    formatTrail(cg, node) {
+        const TRAIL_CAP = 12;
+        const fmt = (e) => {
+            const base = `${e.node.name} (${e.node.filePath}:${e.node.startLine})`;
+            const synth = this.synthEdgeNote(e.edge);
+            return synth ? `${base} [${synth.compact}]` : base;
+        };
+        const collect = (edges) => {
+            const seen = new Set([node.id]);
+            const out = [];
+            for (const e of edges) {
+                if (seen.has(e.node.id))
+                    continue;
+                seen.add(e.node.id);
+                out.push(e);
+            }
+            return out;
+        };
+        const callees = collect(cg.getCallees(node.id));
+        const callers = collect(cg.getCallers(node.id));
+        if (callees.length === 0 && callers.length === 0)
+            return '';
+        const lines = ['', '### Trail — codegraph_node any of these to follow it (no Read needed)'];
+        if (callees.length > 0) {
+            lines.push(`**Calls →** ${callees.slice(0, TRAIL_CAP).map(fmt).join(', ')}${callees.length > TRAIL_CAP ? `, +${callees.length - TRAIL_CAP} more` : ''}`);
+        }
+        if (callers.length > 0) {
+            lines.push(`**Called by ←** ${callers.slice(0, TRAIL_CAP).map(fmt).join(', ')}${callers.length > TRAIL_CAP ? `, +${callers.length - TRAIL_CAP} more` : ''}`);
+        }
+        return lines.join('\n');
+    }
     /**
      * Handle codegraph_status
      */
@@ -1646,7 +2283,10 @@ class ToolHandler {
             lines.push('', outline, '', `> Structural outline only. Read \`${node.filePath}\` or call codegraph_node on a specific member for its body.`);
         }
         else if (code) {
-            lines.push('', '```' + node.language, code, '```');
+            // Line-numbered (cat -n style, like codegraph_explore and Read) so the
+            // agent can cite/edit exact lines without re-Reading the file for them.
+            const numbered = node.startLine ? numberSourceLines(code, node.startLine) : code;
+            lines.push('', '```' + node.language, numbered, '```');
         }
         return lines.join('\n');
     }