@agentllm/codegraph-arkts 0.7.12 → 0.9.4-arkts.0

package/dist/mcp/tools.js

@@ -47,9 +47,22 @@ const fs_1 = require("fs");
 const utils_1 = require("../utils");
 const os_1 = require("os");
 const path_1 = require("path");
-const db_1 = require("../db");
 /** 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
@@ -58,6 +71,18 @@ const MAX_OUTPUT_LENGTH = 15000;
  * same as `configurator::stage_apply::run`.
  */
 const RUST_PATH_PREFIXES = new Set(['crate', 'super', 'self']);
+/**
+ * Node kinds that contain other symbols. For these, `codegraph_node` with
+ * `includeCode=true` returns a structural outline (member names + signatures
+ * + line numbers) instead of the full body, which for a large class is a
+ * multi-thousand-character wall of source that bloats the agent's context.
+ */
+const CONTAINER_NODE_KINDS = new Set([
+    'class', 'struct', 'interface', 'trait', 'protocol', 'enum', 'namespace', 'module',
+]);
+const TASK_MAP_TRACE_EDGE_KINDS = ['calls', 'references', 'want_ipc', 'instantiates'];
+const TASK_MAP_BACKTRACE_EDGE_KINDS = ['calls', 'references', 'want_ipc', 'contains'];
+const TASK_MAP_NATIVE_LANGUAGES = new Set(['rust', 'c', 'cpp']);
 /** Last `::` / `.` / `/`-separated segment of a qualified symbol. */
 function lastQualifierPart(symbol) {
     const parts = symbol.split(/::|[./]/).filter((p) => p.length > 0);
@@ -96,9 +121,14 @@ function getExploreOutputBudget(fileCount) {
     }
     if (fileCount < 5000) {
         return {
+            // 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: 9,
-            maxCharsPerFile: 5000,
+            defaultMaxFiles: 10,
+            maxCharsPerFile: 6500,
             gapThreshold: 12,
             maxSymbolsInFileHeader: 10,
             maxEdgesPerRelationshipKind: 10,
@@ -168,15 +198,50 @@ function numberSourceLines(slice, firstLineNumber) {
 /**
  * Mark a Claude session as having consulted MCP tools.
  * This enables Grep/Glob/Bash commands that would otherwise be blocked.
+ *
+ * Why the explicit openSync + O_NOFOLLOW dance instead of plain writeFileSync:
+ * tmpdir() is world-writable on Linux (mode 1777), so on a shared multi-user
+ * machine any other local user can pre-create `codegraph-consulted-<hash>` as
+ * a symlink pointing at a file the victim owns. The old `writeFileSync` would
+ * happily follow that link and overwrite the target's contents with the ISO
+ * timestamp string (CWE-59). The session-id hash provides the predictability
+ * gate, but it's defense-in-depth: if a session id ever surfaces in logs,
+ * argv, or telemetry the attack becomes trivial, and the right fix is to not
+ * follow links from /tmp paths in the first place.
  */
 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}`);
-        (0, fs_1.writeFileSync)(markerPath, new Date().toISOString(), 'utf8');
+        // 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
+        // benign, but narrowing the exposure costs nothing).
+        const flags = fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_TRUNC | fs_1.constants.O_NOFOLLOW;
+        const fd = (0, fs_1.openSync)(markerPath, flags, 0o600);
+        try {
+            (0, fs_1.writeSync)(fd, new Date().toISOString());
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
     }
     catch {
-        // Silently fail - don't break MCP on marker write failure
+        // Silently fail - don't break MCP on marker write failure. ELOOP from a
+        // planted symlink lands here too, which is the intended behavior: refuse
+        // to write rather than overwrite an attacker-chosen target.
     }
 }
 /**
@@ -222,7 +287,7 @@ exports.tools = [
     },
     {
         name: 'codegraph_context',
-        description: 'PRIMARY TOOL: Build comprehensive context for a task. Returns entry points, related symbols, and key code - often enough to understand the codebase without additional tool calls. NOTE: This provides CODE context, not product requirements. For new features, still clarify UX/behavior questions with the user before implementing.',
+        description: 'PRIMARY TOOL — call this FIRST for any "how does X work", architecture, feature, or bug-context question. Composes search + node + callers + callees and returns entry points, related symbols, and key code in ONE call — usually enough to answer with no further search/Read/Grep. Prefer this over chaining codegraph_search + codegraph_node, and over codegraph_explore. NOTE: provides CODE context, not product requirements; for new features still clarify UX/edge cases with the user.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -246,8 +311,8 @@ exports.tools = [
         },
     },
     {
-        name: 'codegraph_repo_map_slice',
-        description: 'Return a navigation-only repo map slice for a task. It narrows to relevant entry points, related symbols, and files without becoming a planner or assigning work.',
+        name: 'codegraph_task_map',
+        description: 'Return a navigation-only task map for a task. It narrows to relevant entry points, related symbols, and files without becoming a planner or assigning work.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -327,7 +392,7 @@ exports.tools = [
     },
     {
         name: 'codegraph_node',
-        description: 'Get detailed information about a specific code symbol. Use includeCode=true only when you need the full source code - otherwise just get location and signature to minimize context usage.',
+        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: {
@@ -347,7 +412,7 @@ exports.tools = [
     },
     {
         name: 'codegraph_explore',
-        description: 'Deep exploration tool — returns comprehensive context for a topic in a SINGLE call. Groups all relevant source code by file (contiguous sections, not snippets), includes a relationship map, and uses deeper graph traversal. Designed to replace multiple codegraph_node + file Read calls. Use this instead of codegraph_context when you need thorough understanding. IMPORTANT: Use specific symbol names, file names, or short code terms in your query — NOT natural language sentences. Before calling this, use codegraph_search to discover relevant symbol names, then include those names in your query. Bad: "how are agent prompts loaded and passed to the CLI". Good: "readAgentsFromDirectory createClaudeSession chat-manager agents.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: {
@@ -408,6 +473,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
@@ -419,6 +503,9 @@ class ToolHandler {
     cg;
     // Cache of opened CodeGraph instances for cross-project queries
     projectCache = new Map();
+    // The directory the server last searched for a default project. Surfaced in
+    // the "not initialized" error so users can see why detection missed.
+    defaultProjectHint = null;
     constructor(cg) {
         this.cg = cg;
     }
@@ -428,24 +515,57 @@ class ToolHandler {
     setDefaultCodeGraph(cg) {
         this.cg = cg;
     }
+    /**
+     * Record the directory the server tried to resolve the default project from.
+     * Used only to make the "no default project" error actionable.
+     */
+    setDefaultProjectHint(searchedPath) {
+        this.defaultProjectHint = searchedPath;
+    }
     /**
      * Whether a default CodeGraph instance is available
      */
     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,
@@ -456,7 +576,7 @@ class ToolHandler {
             });
         }
         catch {
-            return exports.tools;
+            return visible;
         }
     }
     /**
@@ -471,7 +591,14 @@ class ToolHandler {
     getCodeGraph(projectPath) {
         if (!projectPath) {
             if (!this.cg) {
-                throw new Error('CodeGraph not initialized for this project. Run \'codegraph init\' first.');
+                const searched = this.defaultProjectHint ?? process.cwd();
+                throw new Error('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: ' +
+                    "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"]');
             }
             return this.cg;
         }
@@ -479,11 +606,32 @@ 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) {
             throw new Error(`CodeGraph not initialized in ${projectPath}. Run 'codegraph init' in that project first.`);
         }
+        // If the path resolves to the default project, reuse the already-open
+        // default instance rather than opening a SECOND connection to the same DB.
+        // A duplicate connection serializes reads against the watcher's auto-sync
+        // writes; on the wasm backend (no WAL) that surfaces as intermittent
+        // "database is locked" on concurrent tool calls. See issue #238. Deliberately
+        // not cached under projectPath — the server owns and closes the default
+        // instance, so routing it through projectCache.closeAll() would double-close it.
+        if (this.cg && this.cg.getProjectRoot() === resolvedRoot) {
+            return this.cg;
+        }
         // Check if we already have this resolved root cached (different path, same project)
         if (this.projectCache.has(resolvedRoot)) {
             const cg = this.projectCache.get(resolvedRoot);
@@ -509,12 +657,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;
     }
     /**
@@ -522,13 +693,38 @@ 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);
                 case 'codegraph_context':
                     return await this.handleContext(args);
-                case 'codegraph_repo_map_slice':
-                    return await this.handleRepoMapSlice(args);
+                case 'codegraph_task_map':
+                    return await this.handleTaskMap(args);
                 case 'codegraph_callers':
                     return await this.handleCallers(args);
                 case 'codegraph_callees':
@@ -543,6 +739,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}`);
             }
@@ -599,15 +797,15 @@ 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));
     }
     /**
-     * Handle codegraph_repo_map_slice
+     * Handle codegraph_task_map
      */
-    async handleRepoMapSlice(args) {
+    async handleTaskMap(args) {
         const task = this.validateString(args.task, 'task');
         if (typeof task !== 'string')
             return task;
@@ -622,13 +820,13 @@ class ToolHandler {
         if (typeof context === 'string') {
             try {
                 const parsed = JSON.parse(context);
-                return this.textResult(this.formatTaskContext(this.deserializeTaskContext(parsed)));
+                return this.textResult(this.truncateOutput(this.formatTaskMapOutput(this.deserializeTaskContext(parsed), cg)));
             }
             catch {
-                return this.textResult(context);
+                return this.textResult(this.truncateOutput(context));
             }
         }
-        return this.textResult(this.formatTaskContext(context));
+        return this.textResult(this.truncateOutput(this.formatTaskMapOutput(context, cg)));
     }
     /**
      * Heuristic to detect if a query looks like a feature request
@@ -754,6 +952,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
      *
@@ -795,6 +1382,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);
@@ -895,6 +1519,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;
@@ -915,6 +1541,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
@@ -943,6 +1598,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 };
@@ -1135,7 +1792,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(', ');
@@ -1153,11 +1810,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) {
@@ -1165,13 +1822,26 @@ 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
             }
         }
-        return this.textResult(lines.join('\n'));
+        // Hard-cap to the adaptive budget. The per-file loop bounds the source
+        // sections, but the relationship map, additional-files list, and
+        // completeness/budget notes can still push the assembled output past
+        // 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 = 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... (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);
     }
     /**
      * Handle codegraph_node
@@ -1188,14 +1858,65 @@ class ToolHandler {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
         let code = null;
-        let usages = [];
+        let outline = null;
         if (includeCode) {
-            code = await cg.getCode(match.node.id);
+            // For container symbols (class/interface/struct/…), the full body is the
+            // sum of every method body — a wall of source (e.g. a 10k-char class)
+            // that bloats context and is rarely needed in full. Return a structural
+            // outline (members + signatures + line numbers) instead; the agent can
+            // Read or codegraph_node a specific method for its body. Leaf symbols
+            // (function/method/etc.) return their full body as before.
+            if (CONTAINER_NODE_KINDS.has(match.node.kind)) {
+                outline = this.buildContainerOutline(cg, match.node);
+            }
+            if (!outline) {
+                code = await cg.getCode(match.node.id);
+            }
         }
-        usages = cg.findUsages(match.node.id).slice(0, 5);
-        const formatted = this.formatNodeDetails(match.node, code, usages) + 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
      */
@@ -1210,16 +1931,20 @@ class ToolHandler {
             `**Total edges:** ${stats.edgeCount}`,
             `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`,
         ];
-        // Surface the active SQLite backend. Without this, users on the
-        // silent WASM fallback (better-sqlite3 install failed) see "slow"
-        // indexing and DB-lock errors with no signal of why.
-        const backend = cg.getBackend();
-        if (backend === 'native') {
-            lines.push(`**Backend:** native (better-sqlite3)`);
+        // Surface the active SQLite backend (node:sqlite, Node's built-in real
+        // SQLite — full WAL + FTS5, no native build).
+        lines.push(`**Backend:** node:sqlite (Node built-in) — full WAL + FTS5`);
+        // Effective journal mode. 'wal' ⇒ concurrent reads never block on a writer;
+        // anything else ⇒ they can ("database is locked"). node:sqlite supports WAL
+        // everywhere, so a non-wal mode means the filesystem can't (network/
+        // virtualized mounts, WSL2 /mnt). See issue #238.
+        const journalMode = cg.getJournalMode();
+        if (journalMode === 'wal') {
+            lines.push(`**Journal mode:** wal (concurrent reads safe)`);
         }
         else {
-            lines.push(`**Backend:** ⚠ wasm (better-sqlite3 unavailable) — ` +
-                `5-10x slower than native. Fix: ${db_1.WASM_FALLBACK_FIX_RECIPE}`);
+            lines.push(`**Journal mode:** ⚠ ${journalMode || 'unknown'} — WAL not active, so reads ` +
+                `can block on a concurrent write (WAL appears unsupported on this filesystem)`);
         }
         lines.push('', '### Nodes by Kind:');
         for (const [kind, count] of Object.entries(stats.nodesByKind)) {
@@ -1589,7 +2314,28 @@ class ToolHandler {
         }
         return lines.join('\n');
     }
-    formatNodeDetails(node, code, usages = []) {
+    /**
+     * Build a compact structural outline of a container symbol from its
+     * indexed children (methods, fields, properties, …) — name, kind,
+     * line number, and signature — so the agent gets the shape of a class
+     * without the full source of every method. Returns '' when the container
+     * has no indexed children, so the caller can fall back to full source.
+     */
+    buildContainerOutline(cg, node) {
+        const children = cg.getChildren(node.id)
+            .filter(c => c.kind !== 'import' && c.kind !== 'export')
+            .sort((a, b) => (a.startLine ?? 0) - (b.startLine ?? 0));
+        if (children.length === 0)
+            return '';
+        const lines = [`**Members (${children.length}):**`, ''];
+        for (const c of children) {
+            const loc = c.startLine ? `:${c.startLine}` : '';
+            const sig = c.signature ? ` — \`${c.signature}\`` : '';
+            lines.push(`- ${c.name} (${c.kind})${loc}${sig}`);
+        }
+        return lines.join('\n');
+    }
+    formatNodeDetails(node, code, outline) {
         const location = node.startLine ? `:${node.startLine}` : '';
         const lines = [
             `## ${node.name} (${node.kind})`,
@@ -1603,31 +2349,39 @@ class ToolHandler {
         if (node.docstring && node.docstring.length < 200) {
             lines.push('', node.docstring);
         }
-        if (usages.length > 0) {
-            lines.push('', '### Usages');
-            for (const usage of usages) {
-                const usageLoc = usage.node.startLine ? `:${usage.node.startLine}` : '';
-                lines.push(`- ${usage.node.name} (${usage.edge.kind}) - ${usage.node.filePath}${usageLoc}`);
-            }
+        if (outline) {
+            lines.push('', outline, '', `> Structural outline only. Read \`${node.filePath}\` or call codegraph_node on a specific member for its body.`);
         }
-        if (code) {
-            lines.push('', '```' + node.language, code, '```');
+        else if (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');
     }
-    formatTaskContext(context) {
+    formatTaskContext(context, cg) {
+        const insights = cg ? this.collectTaskMapInsights(cg, context) : null;
+        const displayEntryPoints = insights && insights.displayEntryPoints.length > 0
+            ? insights.displayEntryPoints
+            : context.entryPoints;
+        const summary = insights
+            ? this.buildTaskMapSummary(context, insights, displayEntryPoints)
+            : context.summary;
         const lines = [];
-        lines.push(`## Repo Map Slice`);
+        lines.push('## Repo Map Slice');
         lines.push('');
         lines.push(`**Query:** ${context.query}`);
-        lines.push(`**Summary:** ${context.summary}`);
+        lines.push(`**Summary:** ${summary}`);
         lines.push('');
         lines.push('### Entry Points');
-        for (const node of context.entryPoints.slice(0, 8)) {
+        for (const node of displayEntryPoints.slice(0, 8)) {
             const loc = node.startLine ? `:${node.startLine}` : '';
             lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${loc}`);
         }
-        const keyLinks = this.collectKeyLinks(context);
+        const keyLinks = insights && insights.keyLinks.length > 0
+            ? insights.keyLinks
+            : this.collectKeyLinks(context);
         if (keyLinks.length > 0) {
             lines.push('');
             lines.push('### Key Links');
@@ -1635,7 +2389,30 @@ class ToolHandler {
                 lines.push(`- ${link}`);
             }
         }
-        const nextHops = this.collectNextHops(context);
+        if (insights && insights.convergencePoints.length > 0) {
+            lines.push('');
+            lines.push('### Convergence Points');
+            for (const point of insights.convergencePoints) {
+                lines.push(`- ${point}`);
+            }
+        }
+        if (insights && insights.traceHints.length > 0) {
+            lines.push('');
+            lines.push('### Trace Hints');
+            for (const hint of insights.traceHints) {
+                lines.push(`- ${hint}`);
+            }
+        }
+        if (insights && insights.confirmedPath.length > 0) {
+            lines.push('');
+            lines.push('### Confirmed Path');
+            for (const pathLine of insights.confirmedPath) {
+                lines.push(`- ${pathLine}`);
+            }
+        }
+        const nextHops = insights && insights.nextHops.length > 0
+            ? insights.nextHops
+            : this.collectNextHops(context);
         if (nextHops.length > 0) {
             lines.push('');
             lines.push('### Next Hops');
@@ -1643,7 +2420,9 @@ class ToolHandler {
                 lines.push(`- ${hop}`);
             }
         }
-        const whyIncluded = this.collectWhyIncluded(context);
+        const whyIncluded = insights && insights.whyIncluded.length > 0
+            ? insights.whyIncluded
+            : this.collectWhyIncluded(context);
         if (whyIncluded.length > 0) {
             lines.push('');
             lines.push('### Why Included');
@@ -1653,6 +2432,9 @@ class ToolHandler {
         }
         return lines.join('\n');
     }
+    formatTaskMapOutput(context, cg) {
+        return this.formatTaskContext(context, cg).replace(/^## Repo Map Slice$/m, '## Task Map');
+    }
     collectKeyLinks(context) {
         const links = [];
         const seen = new Set();
@@ -1713,6 +2495,470 @@ class ToolHandler {
         }
         return reasons;
     }
+    collectTaskMapInsights(cg, context) {
+        const pathCandidates = this.findBoundedTaskMapPaths(cg, context.entryPoints)
+            .map((candidate) => this.extendTaskMapPathCandidate(cg, candidate));
+        const bestConfirmedPath = pathCandidates.find((candidate) => candidate.legacyPenalty === 0 && candidate.nativeCount > 0) ?? pathCandidates.find((candidate) => candidate.legacyPenalty === 0) ?? null;
+        return {
+            displayEntryPoints: this.collectTaskMapDisplayEntryPoints(context, bestConfirmedPath, pathCandidates),
+            keyLinks: this.collectTaskMapKeyLinks(context, pathCandidates),
+            convergencePoints: this.collectTaskMapConvergencePoints(cg, pathCandidates),
+            traceHints: this.collectTaskMapTraceHints(pathCandidates),
+            confirmedPath: bestConfirmedPath ? [this.formatTaskMapPath(bestConfirmedPath.steps)] : [],
+            nextHops: this.collectTaskMapNextHops(context, bestConfirmedPath),
+            whyIncluded: this.collectTaskMapWhyIncluded(cg, context, bestConfirmedPath, pathCandidates),
+        };
+    }
+    findBoundedTaskMapPaths(cg, entryPoints) {
+        const candidates = [];
+        const seenPaths = new Set();
+        const cappedEntries = entryPoints.slice(0, 6);
+        for (const start of cappedEntries) {
+            const queue = [{
+                    current: start,
+                    steps: [{ node: start, edge: null }],
+                    score: this.getTaskMapNodeScore(start),
+                    legacyPenalty: this.isTaskMapLegacyNode(start) ? 1 : 0,
+                    bridgeCount: this.isTaskMapBridgeNode(start) ? 1 : 0,
+                    nativeCount: this.isTaskMapNativeNode(start) ? 1 : 0,
+                    crossLanguageTransitions: 0,
+                }];
+            let expansions = 0;
+            while (queue.length > 0 && expansions < 80) {
+                const state = queue.shift();
+                const hopCount = state.steps.length - 1;
+                if (hopCount >= 5) {
+                    continue;
+                }
+                expansions++;
+                const outgoingEdges = cg
+                    .getOutgoingEdges(state.current.id)
+                    .filter((edge) => TASK_MAP_TRACE_EDGE_KINDS.includes(edge.kind))
+                    .sort((a, b) => {
+                    const aNode = cg.getNode(a.target);
+                    const bNode = cg.getNode(b.target);
+                    return this.getTaskMapEdgeScore(b, state.current, bNode) - this.getTaskMapEdgeScore(a, state.current, aNode);
+                })
+                    .slice(0, 8);
+                for (const edge of outgoingEdges) {
+                    const nextNode = cg.getNode(edge.target);
+                    if (!nextNode)
+                        continue;
+                    if (state.steps.some((step) => step.node.id === nextNode.id))
+                        continue;
+                    const nextSteps = [...state.steps, { node: nextNode, edge }];
+                    const nextLegacyPenalty = state.legacyPenalty + (this.isTaskMapLegacyNode(nextNode) ? 1 : 0);
+                    const nextBridgeCount = state.bridgeCount + (this.isTaskMapBridgeNode(nextNode) ? 1 : 0);
+                    const nextNativeCount = state.nativeCount + (this.isTaskMapNativeNode(nextNode) ? 1 : 0);
+                    const nextCrossLanguageTransitions = state.crossLanguageTransitions +
+                        (state.current.language !== nextNode.language ? 1 : 0);
+                    const nextScore = state.score
+                        + this.getTaskMapEdgeScore(edge, state.current, nextNode)
+                        + this.getTaskMapNodeScore(nextNode)
+                        + (state.current.language !== nextNode.language ? 2 : 0);
+                    if (this.isTaskMapTerminalCandidate(cg, nextNode, nextSteps)) {
+                        const signature = nextSteps.map((step) => step.node.id).join('>');
+                        if (!seenPaths.has(signature)) {
+                            seenPaths.add(signature);
+                            candidates.push({
+                                start,
+                                end: nextNode,
+                                steps: nextSteps,
+                                score: nextScore,
+                                legacyPenalty: nextLegacyPenalty,
+                                bridgeCount: nextBridgeCount,
+                                nativeCount: nextNativeCount,
+                                crossLanguageTransitions: nextCrossLanguageTransitions,
+                            });
+                        }
+                    }
+                    queue.push({
+                        current: nextNode,
+                        steps: nextSteps,
+                        score: nextScore,
+                        legacyPenalty: nextLegacyPenalty,
+                        bridgeCount: nextBridgeCount,
+                        nativeCount: nextNativeCount,
+                        crossLanguageTransitions: nextCrossLanguageTransitions,
+                    });
+                }
+            }
+        }
+        return candidates.sort((a, b) => {
+            if (a.legacyPenalty !== b.legacyPenalty)
+                return a.legacyPenalty - b.legacyPenalty;
+            if (a.nativeCount !== b.nativeCount)
+                return b.nativeCount - a.nativeCount;
+            if (a.crossLanguageTransitions !== b.crossLanguageTransitions) {
+                return b.crossLanguageTransitions - a.crossLanguageTransitions;
+            }
+            if (a.bridgeCount !== b.bridgeCount)
+                return b.bridgeCount - a.bridgeCount;
+            if (a.steps.length !== b.steps.length)
+                return a.steps.length - b.steps.length;
+            return b.score - a.score;
+        });
+    }
+    collectTaskMapConvergencePoints(cg, pathCandidates) {
+        const scores = new Map();
+        const candidates = pathCandidates
+            .filter((candidate) => candidate.legacyPenalty === 0)
+            .slice(0, 4);
+        for (const candidate of candidates) {
+            for (const step of candidate.steps.slice(1, -1)) {
+                const outgoingRelevant = cg
+                    .getOutgoingEdges(step.node.id)
+                    .filter((edge) => TASK_MAP_TRACE_EDGE_KINDS.includes(edge.kind)).length;
+                const incomingRelevant = cg
+                    .getIncomingEdges(step.node.id)
+                    .filter((edge) => TASK_MAP_TRACE_EDGE_KINDS.includes(edge.kind)).length;
+                const score = this.getTaskMapNodeScore(step.node)
+                    + incomingRelevant
+                    + outgoingRelevant
+                    + (this.isTaskMapBridgeNode(step.node) ? 3 : 0)
+                    + (this.isTaskMapNativeNode(step.node) ? 2 : 0);
+                const existing = scores.get(step.node.id);
+                if (!existing || score > existing.score) {
+                    scores.set(step.node.id, { node: step.node, score });
+                }
+            }
+        }
+        return [...scores.values()]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 3)
+            .map(({ node }) => this.formatTaskMapNode(node));
+    }
+    extendTaskMapPathCandidate(cg, candidate) {
+        let steps = candidate.steps.map((step) => ({ ...step }));
+        let score = candidate.score;
+        let legacyPenalty = candidate.legacyPenalty;
+        let bridgeCount = candidate.bridgeCount;
+        let nativeCount = candidate.nativeCount;
+        let crossLanguageTransitions = candidate.crossLanguageTransitions;
+        let start = candidate.start;
+        const seen = new Set(steps.map((step) => step.node.id));
+        for (let depth = 0; depth < 4; depth++) {
+            const head = steps[0].node;
+            if (this.isTaskMapBacktraceRoot(head)) {
+                break;
+            }
+            const incomingEdges = cg
+                .getIncomingEdges(head.id)
+                .map((edge) => ({ edge, source: cg.getNode(edge.source) }))
+                .filter((item) => item.source !== null)
+                .filter(({ edge }) => TASK_MAP_BACKTRACE_EDGE_KINDS.includes(edge.kind))
+                .filter(({ source }) => !seen.has(source.id))
+                .sort((a, b) => this.getTaskMapBacktraceScore(b.edge, b.source, head) - this.getTaskMapBacktraceScore(a.edge, a.source, head));
+            const next = incomingEdges[0];
+            if (!next || this.getTaskMapBacktraceScore(next.edge, next.source, head) <= 0) {
+                break;
+            }
+            const shiftedHead = { ...steps[0], edge: next.edge };
+            steps = [{ node: next.source, edge: null }, shiftedHead, ...steps.slice(1)];
+            seen.add(next.source.id);
+            score += this.getTaskMapBacktraceScore(next.edge, next.source, head) + this.getTaskMapNodeScore(next.source);
+            legacyPenalty += this.isTaskMapLegacyNode(next.source) ? 1 : 0;
+            bridgeCount += this.isTaskMapBridgeNode(next.source) ? 1 : 0;
+            nativeCount += this.isTaskMapNativeNode(next.source) ? 1 : 0;
+            crossLanguageTransitions += next.source.language !== head.language ? 1 : 0;
+            start = next.source;
+        }
+        return {
+            ...candidate,
+            start,
+            steps,
+            score,
+            legacyPenalty,
+            bridgeCount,
+            nativeCount,
+            crossLanguageTransitions,
+        };
+    }
+    collectTaskMapTraceHints(pathCandidates) {
+        const hints = [];
+        const seen = new Set();
+        for (const candidate of pathCandidates) {
+            if (candidate.legacyPenalty > 0)
+                continue;
+            const intermediates = candidate.steps.slice(1, -1).map((step) => step.node.name);
+            const core = intermediates.length > 0 ? ` via ${intermediates.join(' -> ')}` : '';
+            const hint = `${candidate.start.name} -> ${candidate.end.name}${core}`;
+            if (seen.has(hint))
+                continue;
+            seen.add(hint);
+            hints.push(hint);
+            if (hints.length >= 3)
+                break;
+        }
+        return hints;
+    }
+    collectTaskMapDisplayEntryPoints(context, bestPath, pathCandidates) {
+        const result = [];
+        const seen = new Set();
+        const pushNode = (node) => {
+            if (!node || seen.has(node.id) || this.isTaskMapLegacyNode(node))
+                return;
+            seen.add(node.id);
+            result.push(node);
+        };
+        if (bestPath) {
+            for (const step of this.compactTaskMapSteps(bestPath.steps)) {
+                pushNode(step.node);
+                if (result.length >= 8) {
+                    return result;
+                }
+            }
+        }
+        for (const candidate of pathCandidates) {
+            if (candidate.legacyPenalty > 0)
+                continue;
+            pushNode(candidate.start);
+            if (result.length >= 8) {
+                return result;
+            }
+        }
+        for (const node of context.entryPoints) {
+            pushNode(node);
+            if (result.length >= 8) {
+                break;
+            }
+        }
+        return result;
+    }
+    buildTaskMapSummary(context, insights, displayEntryPoints) {
+        const visibleNames = displayEntryPoints.slice(0, 3).map((node) => node.name).join(', ');
+        if (insights.confirmedPath.length > 0) {
+            const visibleCount = displayEntryPoints.length;
+            const edgeCount = context.subgraph.edges.length;
+            return `Bounded first-hop chain recovered. Visible anchors: ${visibleNames || 'none'}. ${visibleCount} prioritized symbols, ${edgeCount} relationships retained.`;
+        }
+        return `Navigation-only slice recovered ${displayEntryPoints.length} prioritized symbols across ${context.relatedFiles.length} files. Visible anchors: ${visibleNames || 'none'}.`;
+    }
+    collectTaskMapKeyLinks(context, pathCandidates) {
+        const links = [];
+        const seen = new Set();
+        const appendLink = (source, edge, target) => {
+            const key = `${source.id}->${target.id}:${edge.kind}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            links.push(`${source.name} --${edge.kind}--> ${target.name}`);
+        };
+        const bestPath = pathCandidates.find((candidate) => candidate.legacyPenalty === 0) ?? pathCandidates[0];
+        if (bestPath) {
+            let previousNode = bestPath.steps[0]?.node;
+            for (const step of bestPath.steps.slice(1)) {
+                const edge = step.edge;
+                if (!edge || !previousNode)
+                    continue;
+                appendLink(previousNode, edge, step.node);
+                previousNode = step.node;
+            }
+        }
+        const scoredEdges = context.subgraph.edges
+            .map((edge) => {
+            const source = context.subgraph.nodes.get(edge.source);
+            const target = context.subgraph.nodes.get(edge.target);
+            if (!source || !target)
+                return null;
+            return {
+                edge,
+                source,
+                target,
+                score: this.getTaskMapEdgeScore(edge, source, target),
+            };
+        })
+            .filter((value) => value !== null)
+            .sort((a, b) => b.score - a.score);
+        for (const item of scoredEdges) {
+            if (links.length >= 6)
+                break;
+            appendLink(item.source, item.edge, item.target);
+        }
+        return links.slice(0, 6);
+    }
+    collectTaskMapNextHops(context, bestPath) {
+        if (!bestPath) {
+            return this.collectNextHops(context);
+        }
+        const hops = [];
+        const seen = new Set();
+        for (const step of bestPath.steps.slice(1)) {
+            if (seen.has(step.node.id))
+                continue;
+            seen.add(step.node.id);
+            hops.push(this.formatTaskMapNode(step.node));
+            if (hops.length >= 3)
+                break;
+        }
+        return hops;
+    }
+    collectTaskMapWhyIncluded(cg, context, bestPath, pathCandidates) {
+        const reasons = [];
+        if (bestPath) {
+            const intermediates = bestPath.steps.slice(1, -1).map((step) => step.node.name).join(' -> ');
+            reasons.push(intermediates.length > 0
+                ? `path: ${bestPath.start.name} reaches ${bestPath.end.name} through ${intermediates}`
+                : `path: ${bestPath.start.name} reaches ${bestPath.end.name}`);
+            const bridgeNode = bestPath.steps.map((step) => step.node).find((node) => this.isTaskMapBridgeNode(node));
+            if (bridgeNode) {
+                reasons.push(`bridge: ${bridgeNode.name} is a bridge-adjacent hop on the shortest clean chain`);
+            }
+            if (this.isTaskMapNativeNode(bestPath.end)) {
+                reasons.push(`native: ${bestPath.end.name} is the terminal implementation node`);
+            }
+        }
+        const wantIpcEdge = context.subgraph.edges.find((edge) => edge.kind === 'want_ipc');
+        if (wantIpcEdge) {
+            const source = context.subgraph.nodes.get(wantIpcEdge.source) ?? cg.getNode(wantIpcEdge.source);
+            const target = context.subgraph.nodes.get(wantIpcEdge.target) ?? cg.getNode(wantIpcEdge.target);
+            if (source && target) {
+                reasons.push(`want_ipc: ${source.name} links to ${target.name}`);
+            }
+        }
+        if (pathCandidates.some((candidate) => candidate.legacyPenalty > 0)) {
+            reasons.push('decoy: legacy bridge variants were deprioritized below the clean native chain');
+        }
+        return reasons.slice(0, 6);
+    }
+    formatTaskMapPath(steps) {
+        return this.compactTaskMapSteps(steps).map((step) => step.node.name).join(' -> ');
+    }
+    formatTaskMapNode(node) {
+        const loc = node.startLine ? `:${node.startLine}` : '';
+        return `${node.name} (${node.kind}) - ${node.filePath}${loc}`;
+    }
+    compactTaskMapSteps(steps) {
+        if (steps.length < 3)
+            return steps;
+        const compacted = [];
+        for (let index = 0; index < steps.length; index++) {
+            const current = steps[index];
+            const previous = compacted[compacted.length - 1];
+            const next = steps[index + 1];
+            const shouldSkipArkTsBuild = current.node.name === 'build'
+                && current.node.kind === 'method'
+                && current.node.language === 'arkts'
+                && previous?.node.language === 'arkts'
+                && (previous.node.kind === 'component' || previous.node.kind === 'class')
+                && next?.edge?.kind === 'calls';
+            if (shouldSkipArkTsBuild) {
+                continue;
+            }
+            compacted.push(current);
+        }
+        return compacted;
+    }
+    getTaskMapNodeScore(node) {
+        let score = 1;
+        if (node.kind === 'function' || node.kind === 'method' || node.kind === 'class' || node.kind === 'component') {
+            score += 2;
+        }
+        else if (node.kind === 'module' || node.kind === 'struct' || node.kind === 'route') {
+            score += 1;
+        }
+        if (this.isTaskMapBridgeNode(node))
+            score += 3;
+        if (this.isTaskMapNativeNode(node))
+            score += 4;
+        if (node.language === 'arkts')
+            score += 1;
+        if (node.decorators && node.decorators.length > 0)
+            score += 1;
+        if (this.isTaskMapLegacyNode(node))
+            score -= 8;
+        return score;
+    }
+    getTaskMapEdgeScore(edge, source, target) {
+        const baseByKind = {
+            calls: 6,
+            want_ipc: 5,
+            references: 3,
+            imports: 2,
+            contains: 1,
+            exports: 1,
+            extends: 1,
+            implements: 1,
+            type_of: 1,
+            returns: 1,
+            instantiates: 2,
+            overrides: 1,
+            decorates: 2,
+        };
+        let score = baseByKind[edge.kind] ?? 1;
+        if (this.isTaskMapBridgeNode(source))
+            score += 2;
+        if (target && this.isTaskMapBridgeNode(target))
+            score += 2;
+        if (target && this.isTaskMapNativeNode(target))
+            score += 3;
+        if (this.isTaskMapLegacyNode(source))
+            score -= 6;
+        if (target && this.isTaskMapLegacyNode(target))
+            score -= 6;
+        return score;
+    }
+    getTaskMapBacktraceScore(edge, source, target) {
+        let score = 0;
+        if (edge.kind === 'calls') {
+            score += 7;
+        }
+        else if (edge.kind === 'contains') {
+            score += source.kind === 'component' || source.kind === 'class' ? 6 : 1;
+        }
+        else if (edge.kind === 'want_ipc') {
+            score += 4;
+        }
+        else if (edge.kind === 'references') {
+            score += 2;
+        }
+        if (source.language === 'arkts')
+            score += 3;
+        if (target.language !== source.language)
+            score += 1;
+        if (source.decorators && source.decorators.length > 0)
+            score += 2;
+        if (source.name === 'build')
+            score += 3;
+        if (this.isTaskMapBridgeNode(source))
+            score += 1;
+        if (this.isTaskMapLegacyNode(source))
+            score -= 6;
+        if (source.kind === 'file')
+            score -= 6;
+        return score;
+    }
+    isTaskMapBridgeNode(node) {
+        const haystack = `${node.name} ${node.qualifiedName} ${node.filePath}`.toLowerCase();
+        return /bridge|binding|native|rust|ipc|want|form|ability|entry|adapter|interop|telemetry/.test(haystack);
+    }
+    isTaskMapNativeNode(node) {
+        if (TASK_MAP_NATIVE_LANGUAGES.has(node.language))
+            return true;
+        return /\/(rust|cpp|c)\//.test(node.filePath);
+    }
+    isTaskMapLegacyNode(node) {
+        const haystack = `${node.name} ${node.qualifiedName} ${node.filePath}`.toLowerCase();
+        return /legacy|deprecated|fallback|compat|old/.test(haystack);
+    }
+    isTaskMapBacktraceRoot(node) {
+        if (node.language !== 'arkts')
+            return false;
+        if (node.kind === 'component' || node.kind === 'class' || node.kind === 'module')
+            return true;
+        return Boolean(node.decorators?.some((decorator) => /entry|component/i.test(decorator)));
+    }
+    isTaskMapTerminalCandidate(cg, node, steps) {
+        if (steps.length < 2)
+            return false;
+        if (this.isTaskMapNativeNode(node))
+            return true;
+        const outgoingRelevant = cg
+            .getOutgoingEdges(node.id)
+            .filter((edge) => TASK_MAP_TRACE_EDGE_KINDS.includes(edge.kind));
+        return outgoingRelevant.length === 0
+            && (this.isTaskMapBridgeNode(node) || node.kind === 'function' || node.kind === 'method');
+    }
     deserializeTaskContext(context) {
         return {
             query: context.query,