homegraph 1.1.3 → 1.4.1

package/dist/mcp/tools.js

@@ -6,12 +6,16 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolHandler = exports.tools = exports.PathRefusalError = exports.NotIndexedError = void 0;
+exports.normalizeQuerySpelling = normalizeQuerySpelling;
 exports.getExploreBudget = getExploreBudget;
 exports.getExploreOutputBudget = getExploreOutputBudget;
+exports.tightenExploreBudgetForQuery = tightenExploreBudgetForQuery;
 exports.formatStaleBanner = formatStaleBanner;
 exports.formatStaleFooter = formatStaleFooter;
 exports.formatDegradedBanner = formatDegradedBanner;
 exports.getStaticTools = getStaticTools;
+const query_pool_1 = require("./query-pool");
+const memory_budget_1 = require("./memory-budget");
 const directory_1 = require("../directory");
 // Lazy-load the heavy HomeGraph chain off the MCP startup path — see the same
 // helper in engine.ts. ToolHandler must load to answer tools/list (static
@@ -24,12 +28,15 @@ const query_utils_1 = require("../search/query-utils");
 const fs_1 = require("fs");
 const utils_1 = require("../utils");
 const generated_detection_1 = require("../extraction/generated-detection");
+const arkts_1 = require("../extraction/languages/arkts");
 const dynamic_boundaries_1 = require("./dynamic-boundaries");
+const query_cache_1 = require("./query-cache");
 /** ViewTree structural `references` vias — not UI event bindings. */
 const VIEWTREE_STRUCTURE_VIAS = new Set([
     'child-component',
     'state-binding',
-    'prop-transfer',
+    'Prop',
+    'Link',
     'builder',
     'builder-param',
 ]);
@@ -93,6 +100,25 @@ function lastQualifierPart(symbol) {
     const parts = symbol.split(/::|[./]/).filter((p) => p.length > 0);
     return parts[parts.length - 1] ?? symbol;
 }
+/**
+ * Normalize Erlang-native symbol spellings in an explore query into the shapes
+ * the rest of the pipeline already understands. Agents working Erlang code
+ * name symbols the way the language spells them — `mod:fn/3`, `init/2` — and
+ * those tokens previously died in both consumers: the flow-builder's token
+ * filter rejects `:` and `/arity` outright, and the search-side field parser
+ * eats `mod:fn` as an unknown `field:value`.
+ *
+ *   - `fn/3` → `fn` (arity tail after an identifier)
+ *   - `mod:fn` → `mod.fn` (exactly one colon between identifiers)
+ *
+ * Safe cross-language: Lua's `t:m` spelling maps to the same `t.m` its
+ * qualified names use.
+ */
+function normalizeQuerySpelling(query) {
+    return query
+        .replace(/\b([A-Za-z_][\w@]*)\/(\d{1,3})(?=$|[\s,()[\]/])/g, '$1')
+        .replace(/(^|[\s,()[\]])(?!(?:kind|lang|language|path|name):)([a-z_][\w@]*):([A-Za-z_][\w@]*)(?=$|[\s,()[\]])/g, '$1$2.$3');
+}
 /**
  * Calculate the recommended number of homegraph_explore calls based on project size.
  * Larger codebases need more exploration calls to cover their surface area,
@@ -208,6 +234,46 @@ function getExploreOutputBudget(fileCount) {
         excludeLowValueFiles: false,
     };
 }
+/**
+ * Shrink explore ceilings for local-detail / no-flow named-symbol questions.
+ * Large repos otherwise dump ~24K related source that the agent then still
+ * greps/reads — the main token regression vs without-homegraph.
+ */
+function tightenExploreBudgetForQuery(budget, query, opts) {
+    const hasFlow = opts?.hasFlowPath === true;
+    if (hasFlow && ((0, query_utils_1.queryAsMechanismSurvey)(query) || (0, query_utils_1.queryAsCrossModuleFlowSurvey)(query))) {
+        return budget;
+    }
+    const local = (0, query_utils_1.queryAsLocalSymbolDetail)(query);
+    const compact = (0, query_utils_1.shouldUseCompactExploreBudget)(query);
+    if (!local && !compact && hasFlow)
+        return budget;
+    if (!local && !compact && hasFlow === false) {
+        // Generic no-flow explore: still trim meta + file count a bit.
+        return {
+            ...budget,
+            maxOutputChars: Math.min(budget.maxOutputChars, 14000),
+            defaultMaxFiles: Math.min(budget.defaultMaxFiles, 3),
+            maxCharsPerFile: Math.min(budget.maxCharsPerFile, 5000),
+            includeRelationships: false,
+            includeAdditionalFiles: false,
+            includeCompletenessSignal: false,
+            includeBudgetNote: false,
+        };
+    }
+    if (!local && !compact)
+        return budget;
+    return {
+        ...budget,
+        maxOutputChars: Math.min(budget.maxOutputChars, local ? 9000 : 12000),
+        defaultMaxFiles: Math.min(budget.defaultMaxFiles, local ? 2 : 3),
+        maxCharsPerFile: Math.min(budget.maxCharsPerFile, local ? 4000 : 5000),
+        includeRelationships: false,
+        includeAdditionalFiles: false,
+        includeCompletenessSignal: false,
+        includeBudgetNote: false,
+    };
+}
 /**
  * Whether `homegraph_explore` should prefix source lines with their line
  * numbers (cat -n style: `<num>\t<code>`).
@@ -275,6 +341,29 @@ function numberSourceLines(slice, firstLineNumber) {
     }
     return out.join('\n');
 }
+/** Primary signature line (first line when overloads are stored newline-separated). */
+function primarySignatureLine(signature) {
+    return signature.split('\n')[0]?.trim() ?? signature.trim();
+}
+/** Render a stored signature (single line or newline-separated overloads) for MCP output. */
+function formatNodeSignatureBlock(signature) {
+    const lines = signature.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length <= 1) {
+        return lines.length ? [`**Signature:** \`${lines[0]}\``] : [];
+    }
+    return [
+        '**Signature:**',
+        `- \`${lines[0]}\` (primary)`,
+        ...lines.slice(1).map((l) => `- \`${l}\` (overload)`),
+    ];
+}
+function formatInlineSignature(signature) {
+    const primary = primarySignatureLine(signature);
+    const overloadCount = signature.split('\n').filter((l) => l.trim()).length - 1;
+    if (overloadCount <= 0)
+        return primary;
+    return `${primary} (+${overloadCount} overload${overloadCount === 1 ? '' : 's'})`;
+}
 /**
  * Unique line-prefix for a per-file source section in homegraph_explore output.
  * Issue #778: tool results dropped ATX headings (`####`, `##`, `###`) for bold
@@ -286,6 +375,12 @@ function numberSourceLines(slice, firstLineNumber) {
  * (`reasoning/reasoner.ts`) both key off to cut on whole file sections.
  */
 const FILE_SECTION_PREFIX = '**`';
+// Placeholder for codegraph_explore's "Found N symbols across M files." line.
+// The honest N/M can only be known after the final truncation drops trailing
+// sections (#1046), so the header is emitted as this sentinel and substituted
+// at the very end. This bracketed token never occurs in rendered source or a
+// file path, so the final string-replace can't collide.
+const SUMMARY_SENTINEL = '[[codegraph-explore-summary]]';
 function fileSectionHeader(filePath, suffix) {
     return suffix
         ? `${FILE_SECTION_PREFIX}${filePath}\`** — ${suffix}`
@@ -297,18 +392,26 @@ function fileSectionHeader(filePath, suffix) {
  * The agent uses this to fall back to Read for those specific files
  * without waiting for the debounced sync (issue #403).
  */
-function formatStaleBanner(stale) {
+function formatStaleBanner(stale, opts) {
     const now = Date.now();
     const lines = stale.map((p) => {
         const ageMs = Math.max(0, now - p.lastSeenMs);
         const label = p.indexing ? 'indexing in progress' : 'pending sync';
         return `  - ${p.path} (edited ${ageMs}ms ago, ${label})`;
     });
+    // On large indexes catch-up is skipped for RSS — "Read them" teaches the agent
+    // to abandon homegraph after every save and burn tokens on whole-file Reads.
+    const guidance = opts?.catchUpDeferred
+        ? 'Callers / defs / explore locations above are still usable for structural answers. ' +
+            'Read a listed file only if you need byte-exact content that may have changed mid-session — ' +
+            'do not re-read the whole file just because of this notice.'
+        : 'For accurate content of those specific files, Read them directly. ' +
+            'The rest of this response is fresh.';
     return ('⚠️ Some files referenced below were edited since the last index sync — ' +
         'their homegraph entries may be stale:\n' +
         lines.join('\n') +
-        '\nFor accurate content of those specific files, Read them directly. ' +
-        'The rest of this response is fresh.');
+        '\n' +
+        guidance);
 }
 /**
  * Compact footer listing pending files that are NOT referenced in this
@@ -348,6 +451,23 @@ const projectPathProperty = {
     type: 'string',
     description: 'Absolute path to the project to query (or any directory inside it) — homegraph uses the nearest .homegraph/ index at or above that path. Omit to use this session\'s default project. Pass it to query a second codebase, or when the server root has no index of its own (e.g. a monorepo where only sub-projects are indexed, so there is no default project).',
 };
+/**
+ * EVERY homegraph tool is query-only: it reads the pre-built index and never
+ * mutates the workspace (indexing is the user's explicit CLI call, never the
+ * agent's). Advertising this read-only contract lets clients that gate on it run
+ * the tools where a possibly-mutating tool would be blocked — most concretely,
+ * Cursor's Ask mode, which rejects any MCP tool lacking `readOnlyHint: true`
+ * (issue #1018). `idempotentHint`: a repeated query has no additional effect.
+ * `openWorldHint: false`: the domain is the closed local index, not an open
+ * external world. Shared so the contract is declared once; a hypothetical
+ * mutating tool would simply not reference it.
+ */
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
 /**
  * All HomeGraph MCP tools
  *
@@ -360,7 +480,7 @@ const projectPathProperty = {
 exports.tools = [
     {
         name: 'homegraph_search',
-        description: 'Quick symbol search by name. Returns locations only (no code). Use homegraph_explore instead to get the actual source / understand an area in one call.',
+        description: 'LAST RESORT spelling lookup — locations only, no source. Prefer homegraph_explore whenever the question already names a symbol/file/@kit. If you do call search with a bare name, HomeGraph may answer with a compact explore result instead of locations.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -382,10 +502,11 @@ exports.tools = [
             },
             required: ['query'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_callers',
-        description: 'List functions that call <symbol>. For the full flow, use homegraph_explore.',
+        description: 'Compact caller list for a NAMED in-repo symbol (no bodies). Use after you know the exact name. For full flows use homegraph_explore. DO NOT call for SDK catalogs, one-function semantics, or "what if X fails" hypothetics — Read that function instead. Prefer one explore over parallel callers+callees+node.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -406,10 +527,11 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_callees',
-        description: 'List functions that <symbol> calls. For the full flow, use homegraph_explore.',
+        description: 'Compact callee list for a NAMED in-repo symbol (no bodies). For full flows use homegraph_explore. DO NOT use for out-of-repo SDK internals or counterfactual analysis. Prefer one explore over parallel node+callers+callees.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -430,10 +552,11 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_impact',
-        description: 'List symbols affected by changing <symbol>. Use before a refactor.',
+        description: 'Blast radius for a NAMED in-repo symbol before a refactor. Not for SDK docs, permission judgments, or hypothetical failure effects — those need Read/Grep, not impact.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -454,10 +577,11 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_node',
-        description: 'Two modes. (1) READ A FILE — use INSTEAD of the Read tool: pass `file` (a path or basename) with no `symbol` and it returns that file\'s current on-disk source with line numbers, exactly the shape Read gives you (`<n>\\t<line>`, safe to Edit from), narrowable with `offset`/`limit` just like Read — PLUS a one-line note of which files depend on it. Same bytes as Read, faster (served from the index), with the blast radius attached. Use it whenever you would Read a source file. (2) ONE SYMBOL you can name — its location, signature, verbatim source (includeCode=true) and caller/callee trail in one call, so before changing it you see what calls it and what your edit would break. For an AMBIGUOUS name it returns EVERY matching definition\'s body in one call (so you never Read a file to find the right overload); pass `file`/`line` to pin one. Use homegraph_explore for several related symbols or the full flow.',
+        description: 'Depth on ONE known in-repo symbol or indexed file — not a survey tool. (1) FILE: pass `file` alone → bounded line-numbered source + dependents. (2) SYMBOL: body (includeCode) + short trail; overloads return every body. USE after explore named the symbol and you still need one body. DO NOT call repeatedly to crawl a feature (prefer one explore). DO NOT call for: @kit/SDK catalogs, broad "how does X work", or after explore already returned that symbol\'s source. Treat returned source as already Read — do not grep/read the same path.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -495,16 +619,17 @@ exports.tools = [
             },
             required: [],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_explore',
-        description: 'PRIMARY TOOL — call FIRST for almost any question OR before an edit: how does X work, architecture, a bug, where/what is X, surveying an area, or the symbols you are about to change. Returns the verbatim source of the relevant symbols grouped by file in ONE capped call (Read-equivalent — treat the shown source as already Read; do NOT re-open those files), plus the call path among them. Query can be a natural-language question OR a bag of symbol/file names. Usually the ONLY call you need — more accurate context, in far fewer tokens and round-trips than a search/Read/Grep loop.',
+        description: 'PRIMARY tool for THIS REPO\'s symbol graph (call paths + often line-numbered source). CALL when you need in-repo structure: how a named feature/component is wired, A→B path, callers/callees, Type.member → who uses it, click/handler flow, in-repo @kit import usages — put concrete symbol/file/@kit names in query; skip search. If the question does not need that graph, do not call. One explore; answer from returned Source + trail; treat as already Read; do not re-grep/search the same names. Busy/partial → retry same explore once.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). For a flow question, name the symbols spanning the flow (e.g. "mutateElement renderScene"). A natural-language question works too — no prior homegraph_search needed.',
+                    description: 'In-repo symbols, file basenames, or @kit names for USAGE questions (import/call sites), not for asking the kit\'s official full API list. For flows, name both endpoints. Prefer concrete names from the question.',
                 },
                 maxFiles: {
                     type: 'number',
@@ -515,6 +640,7 @@ exports.tools = [
             },
             required: ['query'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_status',
@@ -525,10 +651,11 @@ exports.tools = [
                 projectPath: projectPathProperty,
             },
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_files',
-        description: 'Indexed file tree with language + symbol counts. Faster than Glob for project layout.',
+        description: 'Indexed directory tree (paths and symbol counts only — NO source code). Do NOT use to answer where/what/how code questions; use homegraph_explore. Only for coarse folder layout when explore cannot help.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -558,6 +685,7 @@ exports.tools = [
                 projectPath: projectPathProperty,
             },
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_spec_match',
@@ -592,8 +720,108 @@ exports.tools = [
             },
             required: ['query'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
+    {
+        name: 'homegraph_spec_find',
+        description: 'Find which specs are related to the given file path by matching against code-fragment file paths ' +
+            'in the Commit4Spec knowledge graph. Traverses code_fragment_nodes → commit_fragment_relations ' +
+            '→ spec_commit_relations → spec_nodes. Useful for answering "which specs does this file affect?" ' +
+            'The database defaults to .homegraph/commit4spec/commit4spec.db under the repo path.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'File path to look up (substring LIKE match). E.g. "src/auth.ts" or "src/auth".',
+                },
+                repoPath: {
+                    type: 'string',
+                    description: 'Path to the repository root. Defaults to the current working directory.',
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Explicit path to the Commit4Spec database. Overrides repoPath-based resolution.',
+                },
+            },
+            required: ['filePath'],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
+    {
+        name: 'homegraph_spec_trace',
+        description: 'Trace a code symbol (function, method, class) back to its associated design Specs in the Commit4Spec ' +
+            'knowledge graph. Resolves the symbol via the HomeGraph code index, then matches against code-fragment ' +
+            'records in the Spec database using five-dimensional scoring: file-path match, code-diff content search ' +
+            '(FTS5), Spec title/subtitle name match, Spec recency, and line-range overlap. ' +
+            'Returns ranked Specs with score breakdowns even when exact line overlap is absent — code drifts over ' +
+            'time, so recency and content matching compensate. ' +
+            'The Spec DB defaults to .homegraph/commit4spec/commit4spec.db under the repo path.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: {
+                    type: 'string',
+                    description: 'Symbol name (bare or qualified). E.g. "authenticate", "AuthService.login", "auth::validate".',
+                },
+                file: {
+                    type: 'string',
+                    description: 'File path for disambiguation when multiple symbols share the same name (optional).',
+                },
+                line: {
+                    type: 'number',
+                    description: 'Line number for disambiguation (optional).',
+                },
+                repoPath: {
+                    type: 'string',
+                    description: 'Path to the repository root. Defaults to the current working directory.',
+                },
+                topK: {
+                    type: 'number',
+                    description: 'Maximum number of matching Specs to return (default: 10).',
+                    default: 10,
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Explicit path to the Commit4Spec database. Overrides repoPath-based resolution.',
+                },
+            },
+            required: ['symbol'],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
 ];
+/**
+ * Return `defs` with `projectPath` marked `required` in each tool's inputSchema.
+ *
+ * Used for the NO-DEFAULT-PROJECT tool surface (issue #993): when the MCP server
+ * has no default project to fall back to — a gateway server started outside any
+ * repo, or a monorepo root whose `.codegraph/` indexes live only in sub-projects
+ * — every call MUST carry an explicit `projectPath`, so the schema should say so.
+ * A `required` field is a HIGH-salience channel (MCP clients surface and often
+ * validate it), unlike the instructions text the reporter found too weak to stop
+ * the agent omitting the param. When a default project IS open, callers leave
+ * projectPath optional and never call this.
+ *
+ * Pure: clones each tool's schema rather than mutating the shared module-level
+ * `tools` array (reused by every session and the static surface). A tool that
+ * doesn't expose projectPath, or already requires it, is returned untouched;
+ * explore's `['query']` becomes `['query', 'projectPath']`, and a tool with no
+ * `required` list (status/files) gains `['projectPath']`.
+ */
+function withRequiredProjectPath(defs) {
+    return defs.map((tool) => {
+        if (!tool.inputSchema.properties.projectPath)
+            return tool;
+        const required = tool.inputSchema.required ?? [];
+        if (required.includes('projectPath'))
+            return tool;
+        return {
+            ...tool,
+            inputSchema: { ...tool.inputSchema, required: [...required, 'projectPath'] },
+        };
+    });
+}
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
@@ -637,9 +865,23 @@ class ToolHandler {
     // huge repo can't hang the first call (#905); cleared on first await so
     // subsequent calls don't pay any cost.
     catchUpGate = null;
+    // Optional worker-thread pool for off-loop read-tool dispatch (daemon mode).
+    // When set + healthy, the heavy read tools run on a worker so the daemon's
+    // main loop stays free for the MCP transport under concurrent load. Null in
+    // direct/in-process mode (one client, no concurrency to parallelize).
+    queryPool = null;
     constructor(cg) {
         this.cg = cg;
     }
+    /**
+     * Engine-only: attach (or detach with null) the worker-thread query pool. The
+     * shared daemon sets this once its default project is open; the workers each
+     * hold their own WAL read connection and run {@link executeReadTool}. A
+     * worker's own ToolHandler never has a pool, so there is no nested off-loading.
+     */
+    setQueryPool(pool) {
+        this.queryPool = pool;
+    }
     /**
      * Update the default HomeGraph instance (e.g. after lazy initialization)
      */
@@ -743,8 +985,18 @@ class ToolHandler {
         let visible = allow
             ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, '')))
             : exports.tools;
+        // No default project loaded → no-root-index case (#993): a gateway server
+        // started outside any repo, or a monorepo root whose indexes live in
+        // sub-projects. With nothing to fall back to, EVERY call needs an explicit
+        // projectPath, so mark it required in the schema — a high-salience nudge the
+        // agent acts on, where SERVER_INSTRUCTIONS_NO_ROOT_INDEX's prose alone
+        // wasn't enough (the reporter had to add an AGENTS.md note). `this.cg` is
+        // settled by `retryInitIfNeeded()` before `handleToolsList` calls us, so a
+        // null here means "genuinely no default", not a startup race. When a default
+        // IS open we leave projectPath optional (below): a bare call falls back to
+        // it, exactly as in the common single-project launch.
         if (!this.cg)
-            return visible;
+            return withRequiredProjectPath(visible);
         try {
             const stats = this.cg.getStats();
             const budget = getExploreBudget(stats.fileCount);
@@ -883,6 +1135,7 @@ class ToolHandler {
     freshen(cg) {
         try {
             if (cg.reopenIfReplaced()) {
+                (0, query_cache_1.getMcpQueryCacheIndex)(cg.getProjectRoot()).reset();
                 process.stderr.write('[HomeGraph MCP] The index was replaced on disk (e.g. a git worktree ' +
                     'recreated at the same path); reopened the live database in place.\n');
             }
@@ -1089,7 +1342,18 @@ class ToolHandler {
         }
         let banner = '';
         if (inResponse.length > 0) {
-            banner = formatStaleBanner(inResponse);
+            let dbPath = null;
+            try {
+                // Large indexes skip catch-up — soft banner so agents don't abandon HG for Read.
+                const root = cg.getProjectRoot();
+                dbPath = (0, path_1.resolve)(root, '.homegraph', 'homegraph.db');
+            }
+            catch {
+                dbPath = null;
+            }
+            banner = formatStaleBanner(inResponse, {
+                catchUpDeferred: (0, memory_budget_1.shouldSkipCatchUpSync)(dbPath),
+            });
         }
         let footer = '';
         if (elsewhere.length > 0) {
@@ -1118,6 +1382,11 @@ class ToolHandler {
                 this.catchUpGate = null;
                 await this.awaitCatchUpGate(gate);
             }
+            // Hard process RSS ceiling — any tool/path that already pushed us over must
+            // stop with success-shaped Partial (never OOM / multi-GB growth).
+            if ((0, memory_budget_1.isOverRssBudget)()) {
+                return (0, memory_budget_1.rssBudgetPartialResult)(toolName);
+            }
             // Honor the optional tool allowlist (HOMEGRAPH_MCP_TOOLS): a trimmed
             // surface rejects ablated tools defensively even if a client cached them.
             if (!this.isToolAllowed(toolName)) {
@@ -1143,48 +1412,83 @@ class ToolHandler {
                 if (typeof check === 'object' && check !== undefined)
                     return check;
             }
-            // Read tools resolve through a single result variable so cross-cutting
-            // notices — worktree-index mismatch (issue #155) and per-file
-            // staleness (issue #403) — can be applied in one place. status embeds
-            // its own verbose worktree warning but still flows through the
-            // staleness wrapper so its pending-files section stays consistent
-            // with what the read tools surface.
-            let result;
-            switch (toolName) {
-                case 'homegraph_search':
-                    result = await this.handleSearch(args);
-                    break;
-                case 'homegraph_callers':
-                    result = await this.handleCallers(args);
-                    break;
-                case 'homegraph_callees':
-                    result = await this.handleCallees(args);
-                    break;
-                case 'homegraph_impact':
-                    result = await this.handleImpact(args);
-                    break;
-                case 'homegraph_explore':
-                    result = await this.handleExplore(args);
-                    break;
-                case 'homegraph_node':
-                    result = await this.handleNode(args);
-                    break;
-                case 'homegraph_status':
-                    // status embeds the pending-files list as a first-class section
-                    // (see handleStatus), so we skip the auto-banner wrapper here to
-                    // avoid duplicating the same info at the top of the response.
-                    return await this.handleStatus(args);
-                case 'homegraph_files':
-                    result = await this.handleFiles(args);
-                    break;
-                case 'homegraph_spec_match':
-                    result = await this.handleSpecMatch(args);
-                    break;
-                default:
-                    return this.errorResult(`Unknown tool: ${toolName}`);
+            const projectPath = args.projectPath;
+            const cacheEnabled = (0, query_cache_1.isMcpQueryCacheEnabled)() && (0, query_cache_1.isCacheableMcpTool)(toolName);
+            let cacheKey;
+            let cacheQueries;
+            let cacheIndex;
+            if (cacheEnabled) {
+                try {
+                    const cacheCg = this.getHomeGraph(projectPath);
+                    cacheQueries = cacheCg.getQueryBuilder();
+                    cacheIndex = (0, query_cache_1.getMcpQueryCacheIndex)(cacheCg.getProjectRoot());
+                    cacheIndex.ensureValid(cacheQueries, () => cacheCg.getLastIndexedAt());
+                    let fileCount;
+                    try {
+                        fileCount = cacheCg.getStats().fileCount;
+                    }
+                    catch {
+                        fileCount = undefined;
+                    }
+                    cacheKey = (0, query_cache_1.buildMcpQueryCacheKey)(toolName, args, fileCount);
+                    const cached = cacheIndex.getEntry(cacheQueries, cacheKey);
+                    if (cached) {
+                        const withWorktree = this.withWorktreeNotice(cached, projectPath);
+                        return this.withStalenessNotice(withWorktree, projectPath);
+                    }
+                }
+                catch {
+                    // No indexed project — fall through; handler returns guidance.
+                }
+            }
+            // homegraph_status reports watcher state (pending files, degraded mode,
+            // worktree warning) and embeds its own sections — it must run on the MAIN
+            // thread against the watched default instance, so it is NEVER off-loaded to
+            // a worker (whose read connection has no watcher). It also skips the
+            // auto-banner wrapper to avoid duplicating its own pending-files section.
+            if (toolName === 'homegraph_status') {
+                return await this.handleStatus(args);
+            }
+            // Every read tool races a deadline ≪ MCP client ~60s hard timeout and
+            // Named-member / local-compact questions finish in tens of ms on the warm
+            // main connection. Serving them here — before the query-pool offload —
+            // avoids cold-worker / wedged-daemon paths that otherwise surface as empty
+            // MCP client `-32001` (the handler itself is fine; the transport times out).
+            if (toolName === 'homegraph_explore' || toolName === 'homegraph_search') {
+                const q = typeof args.query === 'string' ? args.query : '';
+                if (q) {
+                    try {
+                        const cgFast = this.getHomeGraph(projectPath);
+                        const rootFast = cgFast.getProjectRoot();
+                        const fast = (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
+                            ? this.tryFastInventoryExplore(cgFast, q, rootFast)
+                            : null)
+                            ?? this.tryCompactLocalSymbolExplore(cgFast, q, rootFast)
+                            ?? (toolName === 'homegraph_explore'
+                                ? this.tryLightMechanismExplore(cgFast, q, rootFast)
+                                : null);
+                        if (fast) {
+                            if (cacheEnabled && cacheKey && cacheQueries && cacheIndex && !fast.isError) {
+                                cacheIndex.setEntry(cacheQueries, cacheKey, toolName, fast);
+                            }
+                            const withWorktree = this.withWorktreeNotice(fast, projectPath);
+                            return this.withStalenessNotice(withWorktree, projectPath);
+                        }
+                    }
+                    catch {
+                        // Not indexed / path issue — fall through to normal dispatch.
+                    }
+                }
+            }
+            // prefers the query pool so sync SQLite/CPU cannot freeze the transport
+            // (a frozen main loop prevents setTimeout deadlines from firing → empty
+            // `-32001`). Fast-path surveys run inside the worker via executeReadTool.
+            const result = await this.runReadToolWithDeadline(toolName, args);
+            if (cacheEnabled && cacheKey && cacheQueries && cacheIndex && !result.isError) {
+                cacheIndex.setEntry(cacheQueries, cacheKey, toolName, result);
             }
-            const withWorktree = this.withWorktreeNotice(result, args.projectPath);
-            return this.withStalenessNotice(withWorktree, args.projectPath);
+            const withWorktree = this.withWorktreeNotice(result, projectPath);
+            return this.withStalenessNotice(withWorktree, projectPath);
         }
         catch (err) {
             // Expected condition, not a malfunction: answer as a SUCCESS so the
@@ -1203,20 +1507,151 @@ class ToolHandler {
         }
     }
     /**
-     * Handle homegraph_search
+     * Dispatch a read tool with a hard deadline under the typical ~60s MCP client
+     * timeout.
+     *
+     * - **Heavy** tools (explore/impact) → query pool (keeps transport free).
+     * - **Light** tools (search/node/callers/…) → warm main connection (pool cold
+     *   open of a large WAL index routinely outruns the client; search used to
+     *   finish in <1s on the already-open main DB).
+     *
+     * Soft/deadline replies are **static busy text only** — never FTS / explore
+     * on the main thread. A previous path called `searchNodes` from the timeout
+     * callback with the full natural-language query, freezing the event loop so
+     * the success-shaped reply never flushed → empty client `-32001`.
+     */
+    async runReadToolWithDeadline(toolName, args) {
+        const deadlineMs = (0, query_pool_1.resolveToolDeadlineMs)();
+        const light = toolName === 'homegraph_search'
+            || toolName === 'homegraph_node'
+            || toolName === 'homegraph_callers'
+            || toolName === 'homegraph_callees'
+            || toolName === 'homegraph_files';
+        const work = () => {
+            if (!light && this.queryPool && this.queryPool.healthy) {
+                return this.queryPool.run(toolName, args, {
+                    // Static Partial only — never DB/FTS on the soft-timeout callback
+                    // (any sync work here can freeze the MCP transport → empty -32001).
+                    onSoftTimeout: () => this.deadlineBusyResult(deadlineMs),
+                });
+            }
+            return (async () => {
+                await new Promise((r) => setImmediate(r));
+                return this.executeReadTool(toolName, args);
+            })();
+        };
+        let timer;
+        const deadline = new Promise((resolve) => {
+            // Keep this timer ref'd so a blocked sync stretch still flushes Partial
+            // once the event loop runs again — do not call wrapPartialBusyResult here.
+            timer = setTimeout(() => {
+                resolve(this.deadlineBusyResult(deadlineMs));
+            }, deadlineMs);
+        });
+        try {
+            return await Promise.race([work(), deadline]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** Success-shaped busy note — no DB, never blocks the transport. */
+    deadlineBusyResult(deadlineMs) {
+        const secs = Math.max(1, Math.round(deadlineMs / 1000));
+        return this.textResult(`⚠️ **Partial result** — HomeGraph hit its ${secs}s response deadline / is busy ` +
+            `(MCP clients typically kill the call at ~60s with an empty timeout). ` +
+            `This is NOT an error. Retry ONE \`homegraph_explore\` with concrete symbol/file names from the question — ` +
+            `do not fire search+explore or node+callers+callees in parallel, and do not grep/read symbols you already named.`);
+    }
+    /**
+     * Run a single read tool to completion and return its raw {@link ToolResult},
+     * classifying expected failures the same way {@link execute}'s catch does so
+     * the SHAPE is identical whether dispatch runs in-process or on a worker:
+     * NotIndexed → success-shaped guidance, PathRefusal → clean error, anything
+     * else → internal-error-with-retry. Never throws.
+     *
+     * This is the worker thread's entry point (see {@link ./query-worker}) and the
+     * in-process fallback for {@link execute}. It deliberately does NOT run the
+     * catch-up gate or the staleness/worktree notices — those need the daemon's
+     * watched main instance and stay on the main thread. Cross-cutting allowlist +
+     * path validation already ran in {@link execute} before routing here.
+     */
+    async executeReadTool(toolName, args) {
+        try {
+            // Compact inventory / one-symbol surveys — safe on the worker (keeps the
+            // daemon main loop free). Never run these unprotected on the MCP transport
+            // thread: they can block long enough for the client to emit empty `-32001`.
+            const fastPath = this.tryFastPathResult(toolName, args);
+            if (fastPath)
+                return fastPath;
+            return await this.dispatchTool(toolName, args);
+        }
+        catch (err) {
+            if (err instanceof NotIndexedError) {
+                return this.textResult(err.message);
+            }
+            if (err instanceof PathRefusalError) {
+                return this.errorResult(err.message);
+            }
+            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}. ` +
+                'This is an internal homegraph error — retry the call once; if it persists, ' +
+                'continue without homegraph for this task.');
+        }
+    }
+    /**
+     * Pure dispatch over the read tools — the switch, with no gate, no notices, no
+     * allowlist/validation (the caller owns those). `homegraph_status` is handled
+     * on the main thread in {@link execute} and never reaches here. May throw
+     * NotIndexed/PathRefusal, which {@link executeReadTool} classifies.
      */
+    async dispatchTool(toolName, args) {
+        switch (toolName) {
+            case 'homegraph_search': return await this.handleSearch(args);
+            case 'homegraph_callers': return await this.handleCallers(args);
+            case 'homegraph_callees': return await this.handleCallees(args);
+            case 'homegraph_impact': return await this.handleImpact(args);
+            case 'homegraph_explore': return await this.handleExplore(args);
+            case 'homegraph_node': return await this.handleNode(args);
+            case 'homegraph_files': return await this.handleFiles(args);
+            case 'homegraph_spec_match': return await this.handleSpecMatch(args);
+            case 'homegraph_spec_find': return await this.handleSpecFind(args);
+            case 'homegraph_spec_trace': return await this.handleSpecTrace(args);
+            default: return this.errorResult(`Unknown tool: ${toolName}`);
+        }
+    }
     async handleSearch(args) {
         const query = this.validateString(args.query, 'query');
         if (typeof query !== 'string')
             return query;
         const cg = this.getHomeGraph(args.projectPath);
+        // Explore redirect is best-effort — incomplete/faked graphs (or missing
+        // getProjectRoot) must fall through to FTS search rather than error.
+        try {
+            const projectRoot = cg.getProjectRoot();
+            if ((0, query_utils_1.queryShouldPreferExploreOverSearch)(query)) {
+                const exploreRedirect = this.tryFastInventoryExplore(cg, query, projectRoot)
+                    ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot)
+                    ?? this.tryLightMechanismExplore(cg, query, projectRoot);
+                if (exploreRedirect)
+                    return exploreRedirect;
+            }
+            const exploreRedirect = this.tryFastInventoryExplore(cg, query, projectRoot)
+                ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot)
+                ?? this.tryLightMechanismExplore(cg, query, projectRoot);
+            if (exploreRedirect)
+                return exploreRedirect;
+        }
+        catch {
+            // Fall through to FTS search.
+        }
         const rawKind = args.kind;
         // The schema enum says 'type' (what agents naturally reach for); the
         // NodeKind is 'type_alias'. Without the mapping, kind: "type" silently
         // matched nothing — a filter value we advertise must work.
         const kind = rawKind === 'type' ? 'type_alias' : rawKind;
-        const rawLimit = Number(args.limit) || 10;
-        const limit = (0, utils_1.clamp)(rawLimit, 1, 100);
+        const rawLimit = Number(args.limit);
+        const limit = (0, utils_1.clamp)(isNaN(rawLimit) ? 10 : rawLimit, 1, 100);
         const results = cg.searchNodes(query, {
             limit,
             kinds: kind ? [kind] : undefined,
@@ -1233,7 +1668,9 @@ class ToolHandler {
             return aGen - bGen;
         });
         const formatted = this.formatSearchResults(ranked);
-        return this.textResult(this.truncateOutput(formatted));
+        const steer = '\n\n> Locations only. For source / callers / how it works, call `homegraph_explore` ' +
+            'with these symbol names next — do not re-search or grep the same names.';
+        return this.textResult(this.truncateOutput(formatted + steer));
     }
     /**
      * Group symbol matches into DISTINCT DEFINITIONS — one group per
@@ -1295,6 +1732,8 @@ class ToolHandler {
             const callers = [];
             const labels = new Map();
             for (const node of defNodes) {
+                if ((0, memory_budget_1.isOverRssBudget)())
+                    break;
                 for (const c of cg.getCallers(node.id)) {
                     if (!seen.has(c.node.id)) {
                         seen.add(c.node.id);
@@ -1303,6 +1742,8 @@ class ToolHandler {
                         if (label)
                             labels.set(c.node.id, label);
                     }
+                    if (callers.length >= limit)
+                        return { callers, labels };
                 }
             }
             return { callers, labels };
@@ -1316,7 +1757,9 @@ class ToolHandler {
             // A successful `file` narrowing makes the multi-symbol aggregation note
             // stale — suppress it.
             const note = fileFilter && !filteredOut ? '' : allMatches.note;
-            const formatted = this.formatNodeList(callers.slice(0, limit), `Callers of ${symbol}`, labels) + note + filterNote;
+            const formatted = this.formatNodeList(callers.slice(0, limit), `Callers of ${symbol}`, labels)
+                + '\n\n> Caller listing complete — answer from this list; no read/grep needed.'
+                + note + filterNote;
             return this.textResult(this.truncateOutput(formatted));
         }
         // Multiple DISTINCT definitions (#764): one section per definition so an
@@ -1338,7 +1781,7 @@ class ToolHandler {
                 lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
             }
         }
-        return this.textResult(this.truncateOutput(lines.join('\n') + filterNote));
+        return this.textResult(this.truncateOutput(lines.join('\n') + filterNote + '\n\n> Caller listing complete — answer from this list; no read/grep needed.'));
     }
     /**
      * Handle homegraph_callees
@@ -1362,6 +1805,12 @@ class ToolHandler {
             const seen = new Set();
             const callees = [];
             const labels = new Map();
+            const defPaths = defNodes.map((n) => n.filePath);
+            const affinity = (fp) => defPaths.some((dp) => {
+                const a = dp.replace(/\\/g, '/').split('/');
+                const b = fp.replace(/\\/g, '/').split('/');
+                return a.length >= 2 && b.length >= 2 && a[0] === b[0] && a[1] === b[1];
+            });
             for (const node of defNodes) {
                 for (const c of cg.getCallees(node.id)) {
                     if (!seen.has(c.node.id)) {
@@ -1373,7 +1822,10 @@ class ToolHandler {
                     }
                 }
             }
-            return { callees, labels };
+            // Prefer same-package callees when present — cross-package logError/logInfo
+            // homonyms poison upstream/downstream answers.
+            const near = callees.filter((n) => affinity(n.filePath));
+            return { callees: near.length > 0 ? near : callees, labels };
         };
         if (groups.length === 1) {
             const { callees, labels } = collect(groups[0]);
@@ -1526,6 +1978,20 @@ class ToolHandler {
         }
         if (m?.synthesizedBy === 'viewtree') {
             const via = typeof m.via === 'string' ? m.via : '';
+            if (via === 'Prop') {
+                return {
+                    label: `@Prop one-way state transfer (parent → child)`,
+                    compact: `state: @Prop one-way${at}`,
+                    registeredAt,
+                };
+            }
+            if (via === 'Link') {
+                return {
+                    label: `@Link two-way state transfer (parent ↔ child)`,
+                    compact: `state: @Link two-way${at}`,
+                    registeredAt,
+                };
+            }
             if (via && !VIEWTREE_STRUCTURE_VIAS.has(via)) {
                 return {
                     label: `ArkUI event \`.${via}\` — bound handler (dynamic dispatch)`,
@@ -2146,76 +2612,1650 @@ class ToolHandler {
         return `candidates for key \`${key}\`: ${list.join(', ')}`;
     }
     /**
-     * Compact "blast radius" for the entry symbols of an explore result: who
-     * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
-     * no source, so the agent knows what to update / re-verify before editing
-     * without reaching for a separate impact call. Always-on, but skips symbols
-     * that have no dependents (nothing to warn about), and returns '' when none
-     * qualify so a leaf-only exploration stays clean.
+     * Import sites for @kit.* / *Kit module names — surfaces full `import { … } from '@kit.X'`
+     * lines. When the query also names a symbol (taskpool), only matching imports are listed.
      */
-    buildBlastRadiusSection(cg, subgraph) {
-        const ROOT_CAP = 5; // only the symbols the query actually targeted
-        const FILE_CAP = 4; // caller files listed per symbol before "+N more"
-        const MEANINGFUL = new Set([
-            'function', 'method', 'class', 'interface', 'struct', 'trait', 'protocol',
-            'enum', 'type_alias', 'component', 'constant', 'variable', 'property', 'field',
-        ]);
-        const rel = (p) => p.replace(/\\/g, '/');
-        const roots = subgraph.roots
-            .map((id) => subgraph.nodes.get(id))
-            .filter((n) => !!n && MEANINGFUL.has(n.kind))
-            .slice(0, ROOT_CAP);
-        if (roots.length === 0)
-            return '';
-        const entries = [];
-        for (const root of roots) {
-            let callers = [];
+    buildImportSitesSection(cg, query, projectRoot) {
+        const kitTerms = (0, query_utils_1.extractKitModuleNamesFromQuery)(query);
+        const depSymbols = (0, query_utils_1.extractDependencySymbolsFromQuery)(query);
+        const kitSearchTerms = (0, query_utils_1.extractImportSearchTerms)(query);
+        const seen = new Set();
+        const sites = [];
+        const tryAdd = (node, lineText) => {
+            const lineLc = lineText.toLowerCase();
+            if (kitTerms.length > 0) {
+                const matchesKit = kitTerms.some((k) => lineLc.includes(`@kit.${k.toLowerCase()}`));
+                if (!matchesKit)
+                    return;
+            }
+            if (depSymbols.length > 0) {
+                const matchesSym = depSymbols.some((s) => lineLc.includes(s.toLowerCase()));
+                if (!matchesSym)
+                    return;
+            }
+            if (depSymbols.includes('taskpool')) {
+                if (!lineLc.includes('taskpool') || !lineLc.includes('@kit.arkts'))
+                    return;
+            }
+            const key = `${node.filePath}:${node.startLine}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            sites.push({ file: node.filePath, line: node.startLine, lineText });
+        };
+        const resolveImportLine = (node) => (0, query_utils_1.resolveImportLineFromNode)(node, projectRoot);
+        const importLimit = depSymbols.includes('taskpool') ? 200
+            : depSymbols.length > 0 ? 60 : 20;
+        // Symbol-first search: "taskpool" hits `import { taskpool } from '@kit.ArkTS'`.
+        for (const sym of depSymbols) {
+            let hits = [];
             try {
-                callers = cg.getCallers(root.id);
+                hits = cg.searchNodes(sym, { kinds: ['import'], limit: importLimit });
             }
-            catch { /* skip this root */ }
-            const seen = new Set();
-            const uniq = [];
-            for (const c of callers) {
-                if (c?.node && !seen.has(c.node.id)) {
-                    seen.add(c.node.id);
-                    uniq.push(c.node);
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                tryAdd(r.node, resolveImportLine(r.node));
+            }
+        }
+        // Kit-module search (when no symbol filter, or to catch re-exports).
+        if (sites.length === 0 || depSymbols.length === 0) {
+            for (const term of kitSearchTerms) {
+                const termLc = term.toLowerCase().replace(/^@kit\./, '');
+                let hits = [];
+                try {
+                    hits = cg.searchNodes(term, { kinds: ['import'], limit: importLimit });
+                }
+                catch {
+                    continue;
+                }
+                for (const r of hits) {
+                    const lineText = resolveImportLine(r.node);
+                    if (!lineText.toLowerCase().includes(termLc))
+                        continue;
+                    if (depSymbols.length > 0) {
+                        const matchesSym = depSymbols.some((s) => lineText.toLowerCase().includes(s.toLowerCase()));
+                        if (!matchesSym)
+                            continue;
+                    }
+                    tryAdd(r.node, lineText);
                 }
             }
-            if (uniq.length === 0)
-                continue; // no blast radius → nothing to flag
-            const callerFiles = [...new Set(uniq.map((n) => rel(n.filePath)))];
-            const testFiles = callerFiles.filter((f) => (0, query_utils_1.isTestFile)(f));
-            const nonTest = callerFiles.filter((f) => !(0, query_utils_1.isTestFile)(f));
-            const shown = nonTest.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ');
-            const more = nonTest.length > FILE_CAP ? ` +${nonTest.length - FILE_CAP} more` : '';
-            const where = nonTest.length > 0 ? ` in ${shown}${more}` : '';
-            const tests = testFiles.length > 0
-                ? `; tests: ${testFiles.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ')}${testFiles.length > FILE_CAP ? ` +${testFiles.length - FILE_CAP}` : ''}`
-                : '; ⚠️ no covering tests found';
-            entries.push(`- \`${root.name}\` (${rel(root.filePath)}:${root.startLine}) — ${uniq.length} caller${uniq.length === 1 ? '' : 's'}${where}${tests}`);
         }
-        if (entries.length === 0)
-            return '';
-        return [
-            '**Blast radius — what depends on these (update/verify before editing)**',
-            '',
-            ...entries,
-            '',
-        ].join('\n');
+        if (sites.length === 0) {
+            return { section: '', siteCount: 0, compactListing: false };
+        }
+        sites.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+        const importInventoryFilter = (0, query_utils_1.hasImportInventoryFilter)(query);
+        const taskpoolInventory = depSymbols.includes('taskpool');
+        const compactListing = taskpoolInventory || (0, query_utils_1.shouldCompactImportListing)(sites.length, importInventoryFilter);
+        const cap = compactListing ? (taskpoolInventory ? sites.length : 40) : 15;
+        const lines = compactListing
+            ? ['**Dependency list**', '', `Files importing the queried symbol(s) (${sites.length} total):`, '']
+            : ['**Import sites**', ''];
+        for (const s of sites.slice(0, cap)) {
+            if (compactListing) {
+                lines.push(`- \`${s.file}\` (line ${s.line})`);
+            }
+            else {
+                lines.push(`- \`${s.file}:${s.line}\` — \`${s.lineText}\``);
+            }
+        }
+        if (sites.length > cap) {
+            lines.push(`- … and ${sites.length - cap} more`);
+        }
+        if (compactListing) {
+            lines.push('');
+            if (taskpoolInventory) {
+                lines.push(`> Complete list of **${sites.length}** \`import { taskpool } from '@kit.ArkTS'\` site(s) — answer from this section; no grep/read needed.`);
+            }
+            else {
+                lines.push('> Listing complete — answer from this section; no grep/read needed for the dependency set.');
+            }
+        }
+        lines.push('');
+        return { section: lines.join('\n'), siteCount: sites.length, compactListing };
     }
     /**
-     * Graph-connectivity relevance via Random-Walk-with-Restart (personalized
-     * PageRank) from the query's matched SEED nodes over the call/reference graph.
-     *
-     * This is the ranking signal text search (FTS/bm25) CANNOT provide, and it's
-     * homegraph's home turf: relevance by STRUCTURE, not words. A file whose
-     * symbols are call-connected to the matched cluster accrues walk mass and
-     * ranks high; a lone TEXT match — e.g. `LensSwitcher.swift` matched the word
-     * "switch" from `switchOrganization`, but calls none of `setUser`/`fetchUser`
-     * — gets only its own restart probability and ranks ~0. Immune to the
-     * tokenization trap that fools term matching, deterministic, no embeddings.
-     *
+     * External-caller inventory for a named class — methods → who calls them (paths only).
+     */
+    buildCallerListingSection(cg, query) {
+        const typeNames = (0, query_utils_1.extractCallerSurveySymbols)(query);
+        if (typeNames.length === 0)
+            return '';
+        const rel = (p) => p.replace(/\\/g, '/');
+        // Only filter to other files when the user asked for "external" callers.
+        // Applying this to every caller-survey query wiped same-file call sites
+        // (common in C++/ARK .cpp units) and fell through to a fat full explore.
+        const externalOnly = /\bexternal\b/i.test(query) || /外部/.test(query);
+        const lines = ['**Caller inventory**', ''];
+        let substantive = 0;
+        // Function / method symbols named directly (e.g. SortWidgets).
+        for (const sym of typeNames.slice(0, 4)) {
+            const funcs = cg.getNodesByName(sym).filter((n) => (n.kind === 'function' || n.kind === 'method') && !(0, query_utils_1.isTestFile)(n.filePath));
+            for (const fn of funcs.slice(0, 3)) {
+                let callers = [];
+                try {
+                    callers = cg.getCallers(fn.id);
+                }
+                catch {
+                    continue;
+                }
+                const uniq = new Map();
+                for (const c of callers) {
+                    if (!c?.node)
+                        continue;
+                    if (externalOnly && c.node.filePath === fn.filePath)
+                        continue;
+                    if ((0, query_utils_1.isTestFile)(c.node.filePath))
+                        continue;
+                    uniq.set(c.node.id, c.node);
+                }
+                if (uniq.size === 0)
+                    continue;
+                const callerList = [...uniq.values()].slice(0, 12)
+                    .map((n) => `\`${rel(n.filePath)}:${n.startLine}\` (\`${n.name}\`)`)
+                    .join(', ');
+                const more = uniq.size > 12 ? ` +${uniq.size - 12} more` : '';
+                lines.push(`- \`${fn.name}\` (\`${rel(fn.filePath)}:${fn.startLine}\`) ← ${callerList}${more}`);
+                substantive++;
+            }
+        }
+        for (const typeName of typeNames.slice(0, 3)) {
+            const classes = cg.getNodesByName(typeName)
+                .filter((n) => (n.kind === 'class' || n.kind === 'struct' || n.kind === 'component') && !(0, query_utils_1.isTestFile)(n.filePath));
+            for (const cls of classes.slice(0, 2)) {
+                const methods = [];
+                for (const e of cg.getOutgoingEdges(cls.id)) {
+                    if (e.kind !== 'contains')
+                        continue;
+                    const m = cg.getNode(e.target);
+                    if (m && (m.kind === 'method' || m.kind === 'function'))
+                        methods.push(m);
+                }
+                if (methods.length === 0) {
+                    for (const n of cg.getNodesByName(typeName)) {
+                        if (n.filePath === cls.filePath && (n.kind === 'method' || n.kind === 'function')) {
+                            methods.push(n);
+                        }
+                    }
+                }
+                const methodLines = [];
+                for (const method of methods.slice(0, 25)) {
+                    let callers = [];
+                    try {
+                        callers = cg.getCallers(method.id);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const uniq = new Map();
+                    for (const c of callers) {
+                        if (!c?.node)
+                            continue;
+                        if (externalOnly && c.node.filePath === cls.filePath)
+                            continue;
+                        if ((0, query_utils_1.isTestFile)(c.node.filePath))
+                            continue;
+                        uniq.set(c.node.id, c.node);
+                    }
+                    if (uniq.size === 0)
+                        continue;
+                    const callerList = [...uniq.values()].slice(0, 8)
+                        .map((n) => `\`${rel(n.filePath)}:${n.startLine}\` (\`${n.name}\`)`)
+                        .join(', ');
+                    const more = uniq.size > 8 ? ` +${uniq.size - 8} more` : '';
+                    methodLines.push(`- \`${method.name}\` ← ${callerList}${more}`);
+                    substantive++;
+                }
+                if (methodLines.length === 0)
+                    continue;
+                lines.push(`### \`${cls.name}\` (\`${rel(cls.filePath)}\`)`);
+                lines.push(...methodLines);
+                lines.push('');
+            }
+        }
+        if (substantive === 0)
+            return '';
+        lines.push('> Caller inventory complete — answer from this section.');
+        lines.push('');
+        return lines.join('\n');
+    }
+    /**
+     * Upstream data-source survey — which services/symbols feed a Manager (e.g. BadgeManager → notification).
+     */
+    buildDataSourceSection(cg, query) {
+        const anchors = (0, query_utils_1.extractTypeNamesFromQuery)(query).filter((n) => /Manager|Service|Handler|Store|Provider|Controller/i.test(n));
+        if (anchors.length === 0)
+            return { section: '', edgeCount: 0 };
+        const rel = (p) => p.replace(/\\/g, '/');
+        // Prefer system/SDK / service APIs — not local UI helpers (getBadgeOffsetX).
+        const SERVICE_RE = /notification|@ohos|ans|subscribe|publish|bundle|ability|vibrator|telephony|NumBadge|notificationManager|badgeManager|wantAgent|distributed/i;
+        const lines = ['**Data sources / upstream services**', ''];
+        let edgeCount = 0;
+        const addEdge = (bucket, node, via, rank) => {
+            if ((0, query_utils_1.isTestFile)(node.filePath))
+                return;
+            const sig = `${node.name} ${node.filePath} ${node.signature || ''}`;
+            if (!SERVICE_RE.test(sig))
+                return;
+            const prev = bucket.get(node.id);
+            if (!prev || rank < prev.rank) {
+                bucket.set(node.id, { name: node.name, file: rel(node.filePath), line: node.startLine, via, rank });
+                if (!prev)
+                    edgeCount++;
+            }
+        };
+        for (const name of anchors.slice(0, 3)) {
+            const classes = cg.getNodesByName(name).filter((n) => (n.kind === 'class' || n.kind === 'struct' || n.kind === 'component') && !(0, query_utils_1.isTestFile)(n.filePath));
+            for (const cls of classes.slice(0, 2)) {
+                const upstream = new Map();
+                const methods = [];
+                for (const e of cg.getOutgoingEdges(cls.id)) {
+                    if (e.kind !== 'contains')
+                        continue;
+                    const m = cg.getNode(e.target);
+                    if (m && (m.kind === 'method' || m.kind === 'function'))
+                        methods.push(m);
+                }
+                if (methods.length === 0) {
+                    for (const n of cg.getNodesByName(name)) {
+                        if (n.filePath === cls.filePath && (n.kind === 'method' || n.kind === 'function'))
+                            methods.push(n);
+                    }
+                }
+                // 1) Same-file @ohos / kit imports — the usual system-service surface.
+                try {
+                    for (const r of cg.searchNodes('@ohos', { kinds: ['import'], limit: 40 })) {
+                        if (r.node.filePath !== cls.filePath)
+                            continue;
+                        addEdge(upstream, r.node, 'import', 0);
+                    }
+                    for (const term of ['notification', 'badge', 'NumBadge', 'subscribe', 'bundle', 'ability']) {
+                        for (const r of cg.searchNodes(term, { kinds: ['import'], limit: 30 })) {
+                            if (r.node.filePath !== cls.filePath)
+                                continue;
+                            addEdge(upstream, r.node, 'import', 1);
+                        }
+                    }
+                }
+                catch { /* */ }
+                // 2) Callees that look like services/APIs.
+                for (const method of methods.slice(0, 25)) {
+                    let callees = [];
+                    try {
+                        callees = cg.getCallees(method.id);
+                    }
+                    catch {
+                        continue;
+                    }
+                    for (const c of callees) {
+                        if (c?.node)
+                            addEdge(upstream, c.node, method.name, 2);
+                    }
+                }
+                if (upstream.size === 0)
+                    continue;
+                lines.push(`### \`${cls.name}\` (\`${rel(cls.filePath)}\`)`);
+                const ranked = [...upstream.values()].sort((a, b) => a.rank - b.rank || a.name.localeCompare(b.name));
+                for (const u of ranked.slice(0, 15)) {
+                    lines.push(`- \`${u.name}\` at \`${u.file}:${u.line}\` (via \`${u.via}\`)`);
+                }
+                if (ranked.length > 15)
+                    lines.push(`- … and ${ranked.length - 15} more upstream symbol(s)`);
+                lines.push('');
+                lines.push('> Prefer `@ohos.*` / notification / bundle imports as the system-service answer; local helpers are secondary.');
+                lines.push('');
+            }
+        }
+        if (edgeCount === 0)
+            return { section: '', edgeCount: 0 };
+        lines.push('> Data-source survey — answer from upstream symbols above; source bodies omitted.');
+        lines.push('');
+        return { section: lines.join('\n'), edgeCount };
+    }
+    /**
+     * Main-thread fast path for inventory surveys — skips the worker queue.
+     */
+    tryFastPathResult(toolName, args) {
+        const query = args.query;
+        if (typeof query !== 'string')
+            return null;
+        try {
+            const cg = this.getHomeGraph(args.projectPath);
+            const projectRoot = cg.getProjectRoot();
+            if (toolName === 'homegraph_explore') {
+                return this.tryFastInventoryExplore(cg, query, projectRoot)
+                    ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot)
+                    ?? this.tryLightMechanismExplore(cg, query, projectRoot);
+            }
+            if (toolName === 'homegraph_search') {
+                return this.tryFastInventoryExplore(cg, query, projectRoot)
+                    ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot)
+                    ?? this.tryLightMechanismExplore(cg, query, projectRoot);
+            }
+        }
+        catch {
+            return null;
+        }
+        return null;
+    }
+    /**
+     * Fast inventory-only explore — skips findRelevantContext for survey/caller/dependency queries.
+     */
+    tryFastInventoryExplore(cg, query, projectRoot) {
+        if (!(0, query_utils_1.shouldTryFastInventoryExplore)(query))
+            return null;
+        const lines = [`**Exploration: ${query}**`, '', ''];
+        const summaryLineIdx = 2;
+        const inheritanceOnly = (0, query_utils_1.shouldBuildInheritanceSurvey)(query);
+        const typeSurface = inheritanceOnly
+            || (0, query_utils_1.shouldBuildCallerInventory)(query)
+            || (0, query_utils_1.queryIsTypeNameFocus)(query);
+        // Type / hierarchy / method-caller surveys: return inventory first — never a
+        // definition dump or full-graph explore. Agent already named the type.
+        // Exception: caller + co-named "definition visible" needs bodies (compact path).
+        if (typeSurface && !(0, query_utils_1.queryNeedsCoNamedUseBridge)(query)) {
+            const inheritanceSection = this.buildInheritanceSurveySection(cg, query);
+            const callerSection = (0, query_utils_1.shouldBuildCallerInventory)(query)
+                ? this.buildCallerListingSection(cg, query)
+                : '';
+            const inheritanceListed = inheritanceSection
+                ? inheritanceSection.split('\n').filter((l) => l.startsWith('- `')).length > 0
+                : false;
+            const callerBulletCount = callerSection
+                ? callerSection.split('\n').filter((l) => l.startsWith('- ') && l.includes(' ← ')).length
+                : 0;
+            if (inheritanceListed || callerBulletCount > 0) {
+                const parts = [
+                    `**Exploration: ${query}**`,
+                    '',
+                    inheritanceListed && callerBulletCount > 0
+                        ? 'Type surface: inheritance + method caller inventory below — answer from it; do not grep `extends` and do not `homegraph_callers` each method.'
+                        : inheritanceListed
+                            ? 'Inheritance survey above lists all direct subtypes found.'
+                            : 'Caller inventory lists method→caller sites — answer from it; do not fan out `homegraph_callers` per method.',
+                ];
+                if (inheritanceSection)
+                    parts.push(inheritanceSection);
+                if (callerSection)
+                    parts.push(callerSection);
+                return this.textResult(parts.join('\n'));
+            }
+            // Nothing graph-visible — fall through; import/domain may still help.
+        }
+        const importResult = (inheritanceOnly || (0, query_utils_1.queryIsTypeNameFocus)(query) || (0, query_utils_1.queryAsInheritanceSurvey)(query))
+            ? { section: '', siteCount: 0, compactListing: false }
+            : this.buildImportSitesSection(cg, query, projectRoot);
+        if (importResult.section)
+            lines.push(importResult.section);
+        const kitUsageResult = (0, query_utils_1.shouldBuildKitModuleUsageSurvey)(query)
+            ? this.buildKitModuleUsageSection(cg, query, projectRoot)
+            : { section: '', symbolCount: 0 };
+        if (kitUsageResult.section)
+            lines.push(kitUsageResult.section);
+        const domainFileResult = (0, query_utils_1.shouldBuildDomainFileSurvey)(query)
+            ? this.buildDomainFileSurveySection(cg, query)
+            : { section: '', fileCount: 0 };
+        if (domainFileResult.section)
+            lines.push(domainFileResult.section);
+        const apiUsageResult = (0, query_utils_1.shouldBuildApiUsageSurvey)(query)
+            ? this.buildApiUsageSection(cg, query, projectRoot)
+            : { section: '', fileCount: 0 };
+        if (apiUsageResult.section)
+            lines.push(apiUsageResult.section);
+        const dataSourceResult = (0, query_utils_1.queryAsDataSourceSurvey)(query)
+            ? this.buildDataSourceSection(cg, query)
+            : { section: '', edgeCount: 0 };
+        if (dataSourceResult.section)
+            lines.push(dataSourceResult.section);
+        const importInventoryFilter = (0, query_utils_1.hasImportInventoryFilter)(query);
+        const multiAnchor = (0, query_utils_1.queryNamesMultipleExploreAnchors)(query);
+        // Type / caller surveys: skip expensive named-symbol flow synthesize —
+        // it wanders unrelated dynamic edges and burns tokens.
+        const skipFlow = typeSurface || (0, query_utils_1.queryAsCallerOrMethodSurvey)(query);
+        const flow = skipFlow
+            ? { pathNodeIds: new Set(), text: '' }
+            : this.buildFlowFromNamedSymbols(cg, query);
+        const hasFlowPath = flow.pathNodeIds.size > 0;
+        const inheritanceSection = !hasFlowPath && !multiAnchor
+            ? this.buildInheritanceSurveySection(cg, query) : '';
+        const callerSection = !hasFlowPath && !multiAnchor && (0, query_utils_1.shouldBuildCallerInventory)(query)
+            ? this.buildCallerListingSection(cg, query) : '';
+        const memberSection = !hasFlowPath && !multiAnchor && (0, query_utils_1.shouldBuildMemberSurvey)(query)
+            ? this.buildMemberSurveySection(cg, query, projectRoot) : '';
+        const configSection = (0, query_utils_1.shouldBuildConfigSection)(query)
+            ? this.buildConfigFileSection(cg, query, projectRoot) : '';
+        if (inheritanceSection)
+            lines.push(inheritanceSection);
+        if (callerSection)
+            lines.push(callerSection);
+        if (memberSection)
+            lines.push(memberSection);
+        if (configSection)
+            lines.push(configSection);
+        const finishCompact = (summary) => {
+            lines[summaryLineIdx] = summary;
+            return this.textResult(lines.join('\n'));
+        };
+        const memberFileCount = memberSection
+            ? memberSection.split('\n').filter((l) => l.startsWith('- ')).length
+            : 0;
+        const callerBulletCount = callerSection
+            ? callerSection.split('\n').filter((l) => l.startsWith('- ') && l.includes(' ← ')).length
+            : 0;
+        const inheritanceListed = inheritanceSection
+            ? inheritanceSection.split('\n').filter((l) => l.startsWith('- `')).length > 0
+            : false;
+        const hasAnySection = importResult.section || kitUsageResult.section || domainFileResult.section
+            || apiUsageResult.section || dataSourceResult.section || inheritanceSection
+            || callerSection || memberSection || configSection;
+        if (!hasAnySection)
+            return null;
+        const omitSource = (0, query_utils_1.shouldOmitSourceBodies)({
+            importSiteCount: importResult.siteCount,
+            hasFilteredImports: importInventoryFilter && importResult.siteCount > 0,
+            callerBulletCount,
+            memberFileCount,
+            apiUsageFileCount: apiUsageResult.fileCount,
+            configRendered: !!configSection,
+            kitModuleSurveyRendered: !!kitUsageResult.section,
+            inheritanceListed,
+            domainFileCount: domainFileResult.fileCount,
+            dataSourceEdgeCount: dataSourceResult.edgeCount,
+        }, hasFlowPath, multiAnchor);
+        if (!omitSource)
+            return null;
+        if (configSection)
+            return finishCompact('Config/manifest content above — answer from it directly.');
+        if (kitUsageResult.section) {
+            return finishCompact(`Kit module usage survey — **${kitUsageResult.symbolCount}** imported symbol(s) across the repo.`);
+        }
+        if (domainFileResult.fileCount > 0) {
+            return finishCompact(`Domain file survey — **${domainFileResult.fileCount}** related file(s) listed above. ` +
+                'This is the exhaustive related-file inventory; no glob/search needed.');
+        }
+        if (apiUsageResult.fileCount > 0) {
+            return finishCompact(`API usage survey — **${apiUsageResult.fileCount}** file(s) referencing the queried symbol(s).`);
+        }
+        if (dataSourceResult.edgeCount > 0) {
+            return finishCompact(`Data-source survey — **${dataSourceResult.edgeCount}** upstream symbol(s) listed above.`);
+        }
+        if (inheritanceListed)
+            return finishCompact('Inheritance survey above lists all direct subtypes found.');
+        if (importResult.compactListing) {
+            return finishCompact(`Listed **${importResult.siteCount}** import site(s) for the queried symbol(s).`);
+        }
+        if (callerBulletCount >= 1) {
+            return finishCompact(`Caller inventory lists **${callerBulletCount}** call site(s) — answer from the section above.`);
+        }
+        if (memberFileCount >= 2) {
+            return finishCompact(`Member/pattern usage in **${memberFileCount}** file(s) — answer from the inventory above.`);
+        }
+        return finishCompact('Inventory sections above are complete for this query.');
+    }
+    /**
+     * Render a compact symbol-bounded slice of one file (lightweight mechanism path).
+     */
+    renderLightMechanismSource(projectRoot, filePath, nodes, maxChars) {
+        const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, filePath);
+        if (!absPath || !(0, fs_1.existsSync)(absPath))
+            return null;
+        const relevant = nodes.filter((n) => n.startLine > 0 && n.kind !== 'import' && n.kind !== 'export');
+        if (relevant.length === 0)
+            return null;
+        let content;
+        try {
+            content = (0, fs_1.readFileSync)(absPath, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+        const fileLines = content.split('\n');
+        const start = Math.max(1, Math.min(...relevant.map((n) => n.startLine)) - 8);
+        const end = Math.min(fileLines.length, Math.max(...relevant.map((n) => n.endLine ?? n.startLine)) + 8);
+        const lang = relevant[0]?.language || '';
+        const names = [...new Set(relevant.map((n) => n.name))].slice(0, 4).join(', ');
+        const out = [fileSectionHeader(filePath, names), '', '```' + lang];
+        for (let i = start; i <= end; i++) {
+            out.push(`${i}\t${fileLines[i - 1] ?? ''}`);
+        }
+        out.push('```', '');
+        let text = out.join('\n');
+        if (text.length > maxChars) {
+            text = `${text.slice(0, maxChars)}\n... (section trimmed — another explore with a specific symbol is cheaper than grep/read)\n\`\`\`\n`;
+        }
+        return text;
+    }
+    /**
+     * Lightweight mechanism explore — seed entry symbols + flow spine, skip
+     * findRelevantContext. Fast enough for MCP budget; complete enough to avoid
+     * agent grep/read loops (token savings).
+     */
+    tryLightMechanismExplore(cg, query, projectRoot) {
+        if (!(0, query_utils_1.shouldTryLightMechanismExplore)(query))
+            return null;
+        const STRUCTURE_KINDS = new Set(['class', 'struct', 'interface', 'component', 'method', 'function']);
+        const isTestPath = (p) => /(^|\/)(tests?|spec)\//i.test(p) || /\.(test|spec)\./i.test(p);
+        const fileNodes = new Map();
+        const seedIds = new Set();
+        const addNode = (n) => {
+            if (isTestPath(n.filePath))
+                return;
+            if (n.kind !== 'import' && !STRUCTURE_KINDS.has(n.kind))
+                return;
+            seedIds.add(n.id);
+            const list = fileNodes.get(n.filePath) ?? [];
+            if (!list.some((x) => x.id === n.id))
+                list.push(n);
+            fileNodes.set(n.filePath, list);
+        };
+        for (const seed of (0, query_utils_1.extractMechanismEntrySeeds)(query)) {
+            if (seed.startsWith('@')) {
+                let hits = [];
+                try {
+                    hits = cg.searchNodes(seed, { kinds: ['import'], limit: 12 });
+                }
+                catch {
+                    continue;
+                }
+                for (const r of hits)
+                    addNode(r.node);
+                continue;
+            }
+            for (const n of cg.getNodesByName(seed)) {
+                if (STRUCTURE_KINDS.has(n.kind))
+                    addNode(n);
+            }
+        }
+        if (seedIds.size < 2) {
+            const domainTerms = (0, query_utils_1.extractDomainSearchTerms)(query);
+            const asciiTerms = domainTerms.filter((t) => /^[\x00-\x7F]+$/.test(t));
+            for (const term of asciiTerms.slice(0, 8)) {
+                let hits = [];
+                try {
+                    hits = cg.searchNodes(term, {
+                        kinds: ['class', 'struct', 'interface', 'function', 'method', 'import'],
+                        limit: 16,
+                    });
+                }
+                catch {
+                    continue;
+                }
+                for (const r of hits) {
+                    // English FTS expansions from Chinese concepts need not be *Manager.
+                    const nameHit = new RegExp(term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i').test(r.node.name);
+                    const entryOk = (0, query_utils_1.isImplementationEntrySymbol)(r.node.name, domainTerms)
+                        || r.node.kind === 'import'
+                        || ((r.node.kind === 'function' || r.node.kind === 'method') && nameHit);
+                    if (!entryOk)
+                        continue;
+                    addNode(r.node);
+                    if (seedIds.size >= 10)
+                        break;
+                }
+                if (seedIds.size >= 10)
+                    break;
+            }
+        }
+        if (seedIds.size === 0)
+            return null;
+        const seeds = (0, query_utils_1.extractMechanismEntrySeeds)(query);
+        const flow = this.buildFlowFromNamedSymbols(cg, `${query} ${seeds.join(' ')}`);
+        const lines = [
+            `**Exploration: ${query}**`,
+            '',
+            `Mechanism anchors: **${seedIds.size}** symbol(s) — lightweight explore (seed + flow spine).`,
+            '',
+        ];
+        const importResult = this.buildImportSitesSection(cg, query, projectRoot);
+        if (importResult.section)
+            lines.push(importResult.section);
+        if (flow.text)
+            lines.push(flow.text);
+        const fileScores = new Map();
+        for (const [fp, nodes] of fileNodes) {
+            let score = 0;
+            for (const n of nodes) {
+                if (flow.pathNodeIds.has(n.id))
+                    score += 20;
+                else if (flow.uniqueNamedNodeIds.has(n.id))
+                    score += 10;
+                else
+                    score += 5;
+            }
+            fileScores.set(fp, score);
+        }
+        const sortedFiles = [...fileScores.entries()]
+            .filter(([, s]) => s > 0)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 4);
+        lines.push('**Source Code**', '');
+        lines.push('> Line-numbered source below — treat as already Read. Do not grep/read these files again; ' +
+            'another `homegraph_explore` with more symbol names is cheaper if you need more.');
+        lines.push('');
+        let totalChars = lines.join('\n').length;
+        let filesRendered = 0;
+        for (const [fp] of sortedFiles) {
+            if (filesRendered >= 4 || totalChars > 14_000)
+                break;
+            const chunk = this.renderLightMechanismSource(projectRoot, fp, fileNodes.get(fp) ?? [], 4000);
+            if (!chunk)
+                continue;
+            lines.push(chunk);
+            totalChars += chunk.length;
+            filesRendered++;
+        }
+        if (filesRendered === 0 && !importResult.section && !flow.text)
+            return null;
+        lines.push('---');
+        lines.push('> **Mechanism explore complete** for anchored symbols — answer from sections above. ' +
+            'Retry explore with more names before grep/read (grep duplicates token cost).');
+        lines.push('');
+        return this.textResult(lines.join('\n'));
+    }
+    /**
+     * Compact explore for local-symbol behavior questions — skips findRelevantContext
+     * and caps to 1–2 defining files (avoids the ~24K related-file dump).
+     */
+    tryCompactLocalSymbolExplore(cg, query, projectRoot) {
+        // Inventory runs *before* this on the call sites. Do not refuse compact
+        // merely because inventory *intent* matched — empty inventory must fall
+        // through here (bare callbacks like OnSurfaceChangedCB).
+        // Hard rule: 1–3 named anchors → compact for local-detail / bare-id shapes.
+        // Multi-anchor flow bags (routeSave/onSave, aboutToAppear/build, thunk→thunk)
+        // must fall through to full explore so Flow / Dynamic-dispatch / adaptive
+        // sizing still surface — compact trail is not a substitute.
+        const bareId = /^[A-Za-z_][\w]*$/.test(query.trim());
+        if (!(0, query_utils_1.queryAsLocalSymbolDetail)(query) && !bareId && !(0, query_utils_1.queryHasFocusedNamedAnchors)(query)) {
+            return null;
+        }
+        const STRUCTURE_KINDS = new Set([
+            'class', 'struct', 'interface', 'component', 'method', 'function', 'constant', 'variable', 'property', 'field',
+        ]);
+        const isTestPath = (p) => /(^|\/)(tests?|spec)\//i.test(p) || /\.(test|spec)\./i.test(p);
+        const names = (0, query_utils_1.extractLocalDetailAnchors)(query).slice(0, 4);
+        if (names.length === 0)
+            return null;
+        // Multi-anchor bags that form a Flow / Dynamic-dispatch section must use
+        // full explore (synth notes, adaptive sizing, boundary announcements).
+        // Compact trail alone loses those sections. Probe using the raw query —
+        // extractLocalDetailAnchors can drop snake_case tokens (handle_save) that
+        // buildFlowFromNamedSymbols still resolves.
+        const rawTokens = query.split(/[\s,()[\]]+/).filter((t) => t.length >= 3 && /^[A-Za-z_][\w]*$/.test(t));
+        if (names.length >= 2 || rawTokens.length >= 2) {
+            try {
+                const flow = this.buildFlowFromNamedSymbols(cg, query);
+                if (flow.text.length > 0)
+                    return null;
+            }
+            catch {
+                // Probe is best-effort — stay on compact if flow build fails.
+            }
+        }
+        const fileNodes = new Map();
+        const seedIds = new Set();
+        const addNode = (n) => {
+            if (isTestPath(n.filePath) && !(0, query_utils_1.queryAsTestOnlyInterpretation)(query))
+                return;
+            if (!STRUCTURE_KINDS.has(n.kind))
+                return;
+            seedIds.add(n.id);
+            const list = fileNodes.get(n.filePath) ?? [];
+            if (!list.some((x) => x.id === n.id))
+                list.push(n);
+            fileNodes.set(n.filePath, list);
+        };
+        for (const seed of names) {
+            for (const n of cg.getNodesByName(seed)) {
+                addNode(n);
+                if (seedIds.size >= 12)
+                    break;
+            }
+            if (seedIds.size >= 12)
+                break;
+        }
+        if (seedIds.size === 0)
+            return null;
+        const pathAffinity = (seedPath, otherPath) => {
+            const a = seedPath.replace(/\\/g, '/').split('/');
+            const b = otherPath.replace(/\\/g, '/').split('/');
+            // Same package only (e.g. feature/foldeffect/…). Do NOT fallback to
+            // top-level alone — that keeps cross-feature logError homonyms.
+            return a.length >= 2 && b.length >= 2 && a[0] === b[0] && a[1] === b[1];
+        };
+        const seedPaths = [...seedIds].map((id) => {
+            try {
+                return cg.getNode(id)?.filePath;
+            }
+            catch {
+                return undefined;
+            }
+        }).filter((p) => !!p);
+        const nearSeed = (fp) => seedPaths.some((sp) => sp === fp || pathAffinity(sp, fp));
+        // Neighbor policy (agents often search("Foo") alone — do not dump 11 callees):
+        // - bareId / caller-bridge: callers of PRIMARY name only, no callee fan-out
+        // - UI action / pinpoint local-detail: callers + callees
+        const bridge = (0, query_utils_1.queryNeedsCoNamedUseBridge)(query);
+        const callersOnly = bareId
+            || bridge
+            || ((0, query_utils_1.shouldBuildCallerInventory)(query) && !(0, query_utils_1.queryAsNamedComponentAction)(query));
+        const primaryName = names[0];
+        const expandIds = [...seedIds].filter((id) => {
+            try {
+                return cg.getNode(id)?.name === primaryName;
+            }
+            catch {
+                return false;
+            }
+        });
+        // Pull one-hop neighbors into the focus set so the answer is graph-complete
+        // without dumping an import inventory for isExpired/onClick.
+        const neighborIds = new Set();
+        for (const id of expandIds) {
+            let seedPath = '';
+            try {
+                seedPath = cg.getNode(id)?.filePath ?? '';
+            }
+            catch { /* */ }
+            try {
+                for (const { node: c } of cg.getCallers(id).slice(0, callersOnly ? 8 : 10)) {
+                    if (!nearSeed(c.filePath) && seedPath && !pathAffinity(seedPath, c.filePath))
+                        continue;
+                    if (!isTestPath(c.filePath) || (0, query_utils_1.queryAsTestOnlyInterpretation)(query)) {
+                        neighborIds.add(c.id);
+                        // List callers in the trail, but don't pull their whole files into Source
+                        // for bare-name / caller-bridge shapes (that ballooned search("SortWidgets")).
+                        if (!callersOnly)
+                            addNode(c);
+                    }
+                }
+                if (!callersOnly) {
+                    for (const { node: c } of cg.getCallees(id).slice(0, 10)) {
+                        if (!nearSeed(c.filePath) && seedPath && !pathAffinity(seedPath, c.filePath))
+                            continue;
+                        if (!isTestPath(c.filePath) || (0, query_utils_1.queryAsTestOnlyInterpretation)(query)) {
+                            neighborIds.add(c.id);
+                            addNode(c);
+                        }
+                    }
+                }
+            }
+            catch {
+                // skip edge trail for this seed
+            }
+        }
+        const lines = [
+            `**Exploration: ${query}**`,
+            '',
+            `Local-symbol focus: **${seedIds.size}** seed(s)` +
+                (neighborIds.size > 0 ? `, **${neighborIds.size}** caller/callee neighbor(s)` : '') +
+                ' — compact explore (definition + edge trail, no related-file dump).',
+            '',
+        ];
+        // Blast radius for entry seeds (locations only) — same signal full explore
+        // always-on section gives, so bare-name edits know what to update/verify.
+        {
+            const nodes = new Map();
+            for (const id of seedIds) {
+                try {
+                    const n = cg.getNode(id);
+                    if (n)
+                        nodes.set(id, n);
+                }
+                catch { /* skip */ }
+            }
+            const blast = this.buildBlastRadiusSection(cg, {
+                nodes,
+                edges: [],
+                roots: [...seedIds],
+            });
+            if (blast)
+                lines.push(blast);
+        }
+        // Always list a short edge trail — property→UI and button→action questions
+        // need callers/callees; agents otherwise re-grep the same names.
+        {
+            const trail = ['**Call / use trail**', ''];
+            let trailBullets = 0;
+            const trailIds = (callersOnly ? expandIds : [...seedIds]).slice(0, 6);
+            for (const id of trailIds) {
+                let seedNode;
+                try {
+                    seedNode = cg.getNode(id);
+                }
+                catch {
+                    continue;
+                }
+                if (!seedNode)
+                    continue;
+                let callers = [];
+                let callees = [];
+                try {
+                    callers = cg.getCallers(id).slice(0, 8);
+                }
+                catch { /* */ }
+                if (!callersOnly) {
+                    try {
+                        callees = cg.getCallees(id).slice(0, 8);
+                    }
+                    catch { /* */ }
+                }
+                callers = callers.filter((c) => nearSeed(c.node.filePath) || pathAffinity(seedNode.filePath, c.node.filePath));
+                callees = callees.filter((c) => nearSeed(c.node.filePath) || pathAffinity(seedNode.filePath, c.node.filePath));
+                if (callers.length === 0 && callees.length === 0)
+                    continue;
+                trail.push(`- \`${seedNode.name}\` (${seedNode.kind}) — ${seedNode.filePath}:${seedNode.startLine}`);
+                for (const c of callers) {
+                    const loc = c.node.startLine ? `:${c.node.startLine}` : '';
+                    trail.push(`  ← used by \`${c.node.name}\` (${c.node.kind}) — ${c.node.filePath}${loc}`);
+                    trailBullets++;
+                }
+                for (const c of callees) {
+                    const loc = c.node.startLine ? `:${c.node.startLine}` : '';
+                    trail.push(`  → calls \`${c.node.name}\` (${c.node.kind}) — ${c.node.filePath}${loc}`);
+                    trailBullets++;
+                }
+            }
+            if (trailBullets > 0) {
+                trail.push('');
+                trail.push('> Prefer answering from this trail + Source below. Do not grep/search the same symbols again.');
+                trail.push('');
+                lines.push(...trail);
+            }
+        }
+        // When the graph has no call edges (common for static Type.member reads),
+        // fall back to a bounded indexed-file text scan for `name(` usages so the
+        // agent does not pay a Grep round-trip for the same anchors.
+        const textUsageHits = [];
+        // Also scan when the agent asks upstream/registration — callee neighbors
+        // alone do not show Export / OH_NativeXComponent wiring sites.
+        const needUsageScan = neighborIds.size === 0
+            || /上下游|上游|下游|注册|挂到|callback|upstream|downstream/i.test(query)
+            || names.every((n) => /(?:CB|Callback)$/i.test(n));
+        if (needUsageScan) {
+            // Scan ALL focused anchors (incl. PascalCase callables) — previously only
+            // lowercase names were scanned, so OnSurfaceChangedCB registration sites
+            // never surfaced and agents fell through to callers/grep/read.
+            const typeSeeds = (0, query_utils_1.extractTypeNamesFromQuery)(query);
+            const scanNames = names.slice(0, 3);
+            if (scanNames.length > 0) {
+                try {
+                    const defLineKeys = new Set();
+                    for (const nodes of fileNodes.values()) {
+                        for (const n of nodes) {
+                            if (scanNames.includes(n.name))
+                                defLineKeys.add(`${n.filePath}:${n.startLine}`);
+                        }
+                    }
+                    const defDirs = new Set([...fileNodes.keys()].map((fp) => fp.split('/').slice(0, 4).join('/')));
+                    const files = cg.getFiles()
+                        .map((f) => f.path)
+                        .filter((fp) => {
+                        if (isTestPath(fp))
+                            return false;
+                        if (defDirs.size === 0)
+                            return true;
+                        return [...defDirs].some((d) => fp === d || fp.startsWith(`${d}/`));
+                    })
+                        .slice(0, 120);
+                    for (const fp of files) {
+                        if (textUsageHits.length >= 12)
+                            break;
+                        const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, fp);
+                        if (!absPath || !(0, fs_1.existsSync)(absPath))
+                            continue;
+                        let content;
+                        try {
+                            content = (0, fs_1.readFileSync)(absPath, 'utf-8');
+                        }
+                        catch {
+                            continue;
+                        }
+                        // Prefer files that also mention a co-named type when both present
+                        // (skip for single-anchor upstream/registration scans).
+                        if (typeSeeds.length > 1
+                            && names.length > 1
+                            && !typeSeeds.some((t) => content.includes(t))) {
+                            continue;
+                        }
+                        const fileLines = content.split('\n');
+                        for (const sym of scanNames) {
+                            const escaped = sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                            // Match call OR bare identifier use (callback registration tables).
+                            const re = new RegExp(`\\b${escaped}\\b`);
+                            for (let i = 0; i < fileLines.length; i++) {
+                                const lineText = fileLines[i] ?? '';
+                                if (!re.test(lineText))
+                                    continue;
+                                if (defLineKeys.has(`${fp}:${i + 1}`))
+                                    continue;
+                                textUsageHits.push({ filePath: fp, line: i + 1, text: lineText.trim(), symbol: sym });
+                                if (!fileNodes.has(fp))
+                                    fileNodes.set(fp, []);
+                                if (textUsageHits.length >= 12)
+                                    break;
+                            }
+                            if (textUsageHits.length >= 12)
+                                break;
+                        }
+                    }
+                }
+                catch {
+                    // text scan is best-effort
+                }
+            }
+            if (textUsageHits.length > 0) {
+                lines.push('**Text usage sites** (no call-edge indexed for these names — scanned in-repo)', '');
+                for (const h of textUsageHits.slice(0, 10)) {
+                    lines.push(`- \`${h.symbol}\` — ${h.filePath}:${h.line}  \`${h.text.slice(0, 120)}\``);
+                }
+                lines.push('');
+                lines.push('> These lines are the in-repo use sites. Answer from them + Source; do not grep the same names again.');
+                lines.push('');
+            }
+        }
+        // Also surface #include / import lines that make a co-named type visible
+        // near the primary symbol's use sites (IntGrid ↔ SortWidgets shapes).
+        if (names.length >= 2
+            && /include|import|visible|定义可见|可见|头文件|definition/i.test(query)) {
+            const includeHits = [];
+            const primaryFiles = new Set([
+                ...fileNodes.keys(),
+                ...textUsageHits.map((h) => h.filePath),
+            ]);
+            // Files that call / define earlier anchors.
+            for (const id of seedIds) {
+                try {
+                    for (const { node: c } of cg.getCallers(id).slice(0, 8)) {
+                        primaryFiles.add(c.filePath);
+                    }
+                }
+                catch { /* */ }
+            }
+            const secondary = names.slice(1);
+            for (const fp of [...primaryFiles].slice(0, 12)) {
+                const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, fp);
+                if (!absPath || !(0, fs_1.existsSync)(absPath))
+                    continue;
+                let content;
+                try {
+                    content = (0, fs_1.readFileSync)(absPath, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                const fileLines = content.split('\n');
+                for (let i = 0; i < Math.min(fileLines.length, 120); i++) {
+                    const lineText = fileLines[i] ?? '';
+                    if (!/^\s*(?:#\s*include|import\s)/.test(lineText))
+                        continue;
+                    if (!secondary.some((s) => lineText.includes(s)))
+                        continue;
+                    includeHits.push(`- \`${fp}:${i + 1}\`  \`${lineText.trim().slice(0, 140)}\``);
+                    if (includeHits.length >= 8)
+                        break;
+                }
+                if (includeHits.length >= 8)
+                    break;
+            }
+            if (includeHits.length > 0) {
+                lines.push('**Include / import visibility** (how co-named types become visible at use sites)', '');
+                lines.push(...includeHits);
+                lines.push('');
+                lines.push('> Answer the visibility question from these include/import lines — do not re-read headers.');
+                lines.push('');
+            }
+        }
+        const callerSection = (0, query_utils_1.shouldBuildCallerInventory)(query)
+            ? this.buildCallerListingSection(cg, query)
+            : '';
+        if (callerSection)
+            lines.push(callerSection);
+        // Prefer files whose nodes exactly match query names; then neighbor / usage files.
+        // Primary named symbol (first anchor) always ranks first — secondary types like
+        // IntGrid used to drown SortWidgets' defining .cpp via higher exact-count on the header.
+        const nameSet = new Set(names);
+        const usageFiles = new Set(textUsageHits.map((h) => h.filePath));
+        const maxFiles = ((0, query_utils_1.queryAsNamedComponentAction)(query) || (0, query_utils_1.queryHasNamedMemberFocus)(query) || usageFiles.size > 0 || bridge)
+            ? 4
+            : 2;
+        const ranked = [...fileNodes.entries()]
+            .map(([fp, nodes]) => {
+            const exact = nodes.filter((n) => nameSet.has(n.name)).length;
+            const primaryHit = nodes.some((n) => n.name === primaryName) ? 100 : 0;
+            const neighborHit = nodes.filter((n) => neighborIds.has(n.id)).length;
+            const usageHit = usageFiles.has(fp) ? 15 : 0;
+            return {
+                fp,
+                nodes,
+                exact,
+                score: primaryHit + exact * 20 + neighborHit * 5 + usageHit + nodes.length,
+            };
+        })
+            .sort((a, b) => b.score - a.score || a.fp.localeCompare(b.fp))
+            .slice(0, maxFiles);
+        lines.push('**Source Code**', '');
+        lines.push('> Line-numbered source — treat as already Read. Answer from it; do not re-explore/search/grep the same symbols.');
+        lines.push('');
+        let totalChars = lines.join('\n').length;
+        const maxTotal = 9000;
+        const maxPerFile = 4000;
+        let rendered = 0;
+        for (const { fp, nodes } of ranked) {
+            if (rendered >= maxFiles || totalChars > maxTotal)
+                break;
+            const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, fp);
+            if (!absPath || !(0, fs_1.existsSync)(absPath))
+                continue;
+            let fileContent;
+            try {
+                fileContent = (0, fs_1.readFileSync)(absPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const fileLines = fileContent.split('\n');
+            const focusNodes = nodes
+                .filter((n) => nameSet.has(n.name) || STRUCTURE_KINDS.has(n.kind))
+                .sort((a, b) => a.startLine - b.startLine);
+            // Prefer contiguous windows around named symbols; usage-only files
+            // window around the first text-hit line.
+            let start = 1;
+            let end = Math.min(fileLines.length, 120);
+            const usageLine = textUsageHits.find((h) => h.filePath === fp)?.line;
+            if (focusNodes.length > 0) {
+                const named = focusNodes.filter((n) => nameSet.has(n.name));
+                const use = named.length > 0 ? named : focusNodes.slice(0, 3);
+                start = Math.max(1, Math.min(...use.map((n) => n.startLine)) - 2);
+                end = Math.min(fileLines.length, Math.max(...use.map((n) => n.endLine)) + 2);
+                // Keep window bounded
+                if ((end - start + 1) * 40 > maxPerFile) {
+                    end = Math.min(fileLines.length, start + Math.floor(maxPerFile / 40) - 1);
+                }
+            }
+            else if (usageLine) {
+                start = Math.max(1, usageLine - 15);
+                end = Math.min(fileLines.length, usageLine + 25);
+            }
+            const header = fileSectionHeader(fp, focusNodes.map((n) => `${n.name}(${n.kind})`).slice(0, 6).join(', '));
+            const withLineNumbers = exploreLineNumbersEnabled();
+            const bodyLines = [header, '```' + (nodes[0]?.language || ''), ''];
+            for (let i = start; i <= end; i++) {
+                const code = fileLines[i - 1] ?? '';
+                bodyLines.push(withLineNumbers ? `${i}\t${code}` : code);
+            }
+            bodyLines.push('```', '');
+            let chunk = bodyLines.join('\n');
+            if (chunk.length > maxPerFile) {
+                chunk = `${chunk.slice(0, maxPerFile)}\n... (trimmed)\n\`\`\`\n`;
+            }
+            if (totalChars + chunk.length > maxTotal && rendered > 0)
+                break;
+            lines.push(chunk);
+            totalChars += chunk.length;
+            rendered++;
+        }
+        if (rendered === 0)
+            return null;
+        lines.push('---');
+        lines.push('> **Compact local explore complete** — answer from the definition(s) above. ' +
+            'Do not call `homegraph_search` or another full explore for the same symbol.');
+        lines.push('');
+        return this.textResult(lines.join('\n'));
+    }
+    /**
+     * @kit module capability survey — repo import/usage only (SDK defs are not indexed).
+     */
+    buildKitModuleUsageSection(cg, query, projectRoot) {
+        const kitTerms = (0, query_utils_1.extractKitModuleNamesFromQuery)(query);
+        const submodules = (0, query_utils_1.extractKitSubmoduleNamesFromQuery)(query);
+        if (kitTerms.length === 0)
+            return { section: '', symbolCount: 0 };
+        const kitSearchTerms = (0, query_utils_1.extractImportSearchTerms)(query);
+        const seen = new Set();
+        const imports = [];
+        const parseImportedSymbols = (lineText) => {
+            const syms = new Set();
+            const brace = lineText.match(/import\s*\{([^}]+)\}/);
+            if (brace?.[1]) {
+                for (const part of brace[1].split(',')) {
+                    const tok = part.trim().split(/\s+as\s+/i)[0]?.trim();
+                    if (tok)
+                        syms.add(tok);
+                }
+            }
+            const def = lineText.match(/import\s+(\w+)\s+from\b/);
+            if (def?.[1])
+                syms.add(def[1]);
+            const ns = lineText.match(/import\s+\*\s+as\s+(\w+)/);
+            if (ns?.[1])
+                syms.add(ns[1]);
+            return [...syms];
+        };
+        const matchesSubmodule = (lineText, symbols) => {
+            if (submodules.length === 0)
+                return true;
+            const lc = lineText.toLowerCase();
+            return submodules.some((sm) => {
+                const s = sm.toLowerCase();
+                return symbols.some((sym) => sym.toLowerCase() === s || sym.toLowerCase().startsWith(`${s}.`))
+                    || lc.includes(`.${s}`) || lc.includes(`'${s}'`) || lc.includes(`"${s}"`);
+            });
+        };
+        const resolveImportLine = (node) => (0, query_utils_1.resolveImportLineFromNode)(node, projectRoot);
+        for (const term of kitSearchTerms) {
+            const termLc = term.toLowerCase().replace(/^@kit\./, '');
+            let hits = [];
+            try {
+                hits = cg.searchNodes(term, { kinds: ['import'], limit: 80 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                const lineText = resolveImportLine(r.node);
+                if (!lineText.toLowerCase().includes(termLc) && !lineText.toLowerCase().includes('@kit.'))
+                    continue;
+                const symbols = parseImportedSymbols(lineText);
+                if (!matchesSubmodule(lineText, symbols))
+                    continue;
+                const key = `${r.node.filePath}:${r.node.startLine}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                imports.push({
+                    file: r.node.filePath,
+                    line: r.node.startLine,
+                    lineText,
+                    symbols,
+                });
+            }
+        }
+        if (imports.length === 0) {
+            const kitLabel = kitTerms.map((k) => `@kit.${k}`).join(', ');
+            const sub = submodules.length > 0 ? ` (${submodules.join(', ')} submodule)` : '';
+            return {
+                section: [
+                    '**Kit module usage (this repo)**',
+                    '',
+                    `No imports from ${kitLabel}${sub} were found in the indexed codebase.`,
+                    '',
+                    `> @kit module API definitions live in the HarmonyOS SDK, not this repository. Answer from repo imports/usages only.`,
+                    '',
+                ].join('\n'),
+                symbolCount: 0,
+            };
+        }
+        const symbolFiles = new Map();
+        for (const imp of imports) {
+            for (const sym of imp.symbols) {
+                const set = symbolFiles.get(sym) ?? new Set();
+                set.add(imp.file);
+                symbolFiles.set(sym, set);
+            }
+        }
+        const lines = [
+            '**Kit module usage (this repo)**',
+            '',
+            `> @kit module API definitions live in the HarmonyOS SDK, not this repository. Below: how **this project** imports and uses them.`,
+            '',
+            `Imports from ${kitTerms.map((k) => `\`@kit.${k}\``).join(', ')} (${imports.length} site(s)):`,
+            '',
+        ];
+        for (const imp of imports.slice(0, 35)) {
+            const symStr = imp.symbols.length > 0 ? imp.symbols.join(', ') : '(namespace)';
+            lines.push(`- \`${imp.file}:${imp.line}\` — \`${imp.lineText}\` (${symStr})`);
+        }
+        if (imports.length > 35)
+            lines.push(`- … and ${imports.length - 35} more import site(s)`);
+        if (symbolFiles.size > 0) {
+            lines.push('');
+            lines.push('**Symbols imported (unique):**');
+            for (const [sym, files] of [...symbolFiles.entries()].sort((a, b) => a[0].localeCompare(b[0])).slice(0, 40)) {
+                const fileList = [...files].slice(0, 5).map((f) => `\`${f}\``).join(', ');
+                const more = files.size > 5 ? ` +${files.size - 5} files` : '';
+                lines.push(`- \`${sym}\` — imported in ${fileList}${more}`);
+            }
+        }
+        lines.push('');
+        lines.push('> Kit usage survey complete — answer from this section; do not search external SDK docs or grep the repo again.');
+        lines.push('');
+        return { section: lines.join('\n'), symbolCount: symbolFiles.size };
+    }
+    /** Disambiguate homonymous types (Configuration, Rectangle) when several defs exist. */
+    buildHomonymDefinitionsSection(cg, query) {
+        const typeNames = (0, query_utils_1.extractTypeNamesFromQuery)(query);
+        const queryFiles = (0, query_utils_1.extractFileBasenamesFromQuery)(query);
+        const lines = [];
+        for (const name of typeNames.slice(0, 4)) {
+            const defs = cg.getNodesByName(name).filter((n) => (n.kind === 'class' || n.kind === 'struct' || n.kind === 'interface' || n.kind === 'type_alias')
+                && !(0, query_utils_1.isTestFile)(n.filePath));
+            if (defs.length <= 1)
+                continue;
+            lines.push(`**${name}** — ${defs.length} distinct definitions (pin with file basename in a follow-up explore):`);
+            for (const d of defs.slice(0, 8)) {
+                const pin = (0, query_utils_1.fileMatchesQueryBasename)(d.filePath, queryFiles) ? ' ← matches query file' : '';
+                lines.push(`- \`${d.qualifiedName || d.name}\` (\`${d.filePath}:${d.startLine}\`)${pin}`);
+            }
+            if (defs.length > 8)
+                lines.push(`- … and ${defs.length - 8} more`);
+            lines.push('');
+        }
+        if (lines.length === 0)
+            return '';
+        return lines.join('\n');
+    }
+    /** Direct subclasses of a named type — paths only. */
+    buildInheritanceSurveySection(cg, query) {
+        if (!(0, query_utils_1.shouldBuildInheritanceSurvey)(query))
+            return '';
+        const rel = (p) => p.replace(/\\/g, '/');
+        const lines = ['**Inheritance survey**', ''];
+        let listed = 0;
+        for (const typeName of (0, query_utils_1.extractTypeNamesFromQuery)(query).slice(0, 2)) {
+            const bases = cg.getNodesByName(typeName).filter((n) => (n.kind === 'class' || n.kind === 'struct' || n.kind === 'interface') && !(0, query_utils_1.isTestFile)(n.filePath));
+            for (const base of bases.slice(0, 2)) {
+                const subs = [];
+                for (const e of cg.getIncomingEdges(base.id)) {
+                    if (e.kind !== 'extends' && e.kind !== 'implements')
+                        continue;
+                    try {
+                        const child = cg.getNode(e.source);
+                        if (child && !(0, query_utils_1.isTestFile)(child.filePath))
+                            subs.push(child);
+                    }
+                    catch { /* skip */ }
+                }
+                if (subs.length === 0)
+                    continue;
+                lines.push(`### Subtypes of \`${base.name}\` (\`${rel(base.filePath)}\`)`);
+                for (const s of subs.slice(0, 30)) {
+                    lines.push(`- \`${s.name}\` (\`${rel(s.filePath)}:${s.startLine}\`)`);
+                    listed++;
+                }
+                if (subs.length > 30)
+                    lines.push(`- … and ${subs.length - 30} more`);
+                lines.push('');
+            }
+        }
+        if (listed === 0)
+            return '';
+        lines.push('> Inheritance survey complete — answer from this list; no read/grep needed for the subtype set.');
+        lines.push('');
+        return lines.join('\n');
+    }
+    /**
+     * Files/lines using a member or literal pattern (.drawModifier, .width('100%')).
+     */
+    buildMemberSurveySection(cg, query, projectRoot) {
+        const members = (0, query_utils_1.extractMemberAccessFromQuery)(query);
+        const patterns = [];
+        for (const ma of members) {
+            if (ma.dotted.startsWith('.'))
+                patterns.push(ma.dotted);
+            else
+                patterns.push(ma.dotted);
+        }
+        // Literal chains in quotes: .width('100%')
+        for (const m of query.matchAll(/(\.[a-zA-Z_][\w]*\s*\([^)]*\))/g)) {
+            patterns.push(m[1].replace(/\s+/g, ''));
+        }
+        if (patterns.length === 0)
+            return '';
+        const rel = (p) => p.replace(/\\/g, '/');
+        const hits = new Map();
+        const addHit = (file, line) => {
+            const arr = hits.get(file) ?? [];
+            if (!arr.includes(line))
+                arr.push(line);
+            hits.set(file, arr);
+        };
+        for (const pat of patterns) {
+            const bare = pat.replace(/^\./, '');
+            let nodes = [];
+            try {
+                nodes = cg.searchNodes(bare, { limit: 30 });
+            }
+            catch { /* skip */ }
+            for (const r of nodes) {
+                if ((0, query_utils_1.isTestFile)(r.node.filePath))
+                    continue;
+                addHit(rel(r.node.filePath), r.node.startLine);
+            }
+        }
+        // Scan top FTS files for literal pattern in source
+        for (const pat of patterns.slice(0, 3)) {
+            const literal = pat.startsWith('.') ? pat : `.${pat}`;
+            const re = new RegExp(literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+            let files = [];
+            try {
+                files = cg.searchNodes(patterns[0].replace(/^\./, ''), { limit: 25 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of files) {
+                if ((0, query_utils_1.isTestFile)(r.node.filePath))
+                    continue;
+                const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                if (!abs)
+                    continue;
+                let content;
+                try {
+                    content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                const fileLines = content.split('\n');
+                for (let i = 0; i < fileLines.length; i++) {
+                    if (re.test(fileLines[i] ?? ''))
+                        addHit(rel(r.node.filePath), i + 1);
+                }
+            }
+        }
+        if (hits.size === 0)
+            return '';
+        const lines = ['**Member / pattern usage**', ''];
+        let fileCount = 0;
+        for (const [fp, lineNos] of [...hits.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+            if (fileCount >= 40)
+                break;
+            const sorted = lineNos.sort((a, b) => a - b).slice(0, 6);
+            const lineStr = sorted.join(', ');
+            const more = lineNos.length > 6 ? ` +${lineNos.length - 6} lines` : '';
+            lines.push(`- \`${fp}\` — lines ${lineStr}${more}`);
+            fileCount++;
+        }
+        if (hits.size > 40)
+            lines.push(`- … and ${hits.size - 40} more file(s)`);
+        lines.push('');
+        lines.push('> Pattern survey complete — answer from this list; run another explore naming missing symbols if needed.');
+        lines.push('');
+        return lines.join('\n');
+    }
+    /**
+     * API call-site survey — where a named API/symbol (statfs, napi_*) appears in repo source.
+     */
+    buildApiUsageSection(cg, query, projectRoot) {
+        // Include PascalCase SDK modules (Telephony) — deps-only missed them.
+        const symbols = (0, query_utils_1.extractApiUsageTokens)(query).slice(0, 6);
+        if (symbols.length === 0)
+            return { section: '', fileCount: 0 };
+        const rel = (p) => p.replace(/\\/g, '/');
+        const hits = new Map();
+        const addHit = (file, line) => {
+            if ((0, query_utils_1.isTestFile)(file))
+                return;
+            const fp = rel(file);
+            const arr = hits.get(fp) ?? [];
+            if (!arr.includes(line))
+                arr.push(line);
+            hits.set(fp, arr);
+        };
+        for (const sym of symbols.slice(0, 4)) {
+            const symLc = sym.toLowerCase();
+            let nodes = [];
+            try {
+                nodes = cg.searchNodes(sym, { limit: 40 });
+            }
+            catch { /* skip */ }
+            for (const r of nodes) {
+                const n = r.node;
+                if (n.name.toLowerCase() === symLc || (n.signature || '').toLowerCase().includes(symLc)) {
+                    addHit(n.filePath, n.startLine);
+                }
+            }
+            const wordRe = new RegExp(`\\b${sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+            let scanHits = [];
+            try {
+                scanHits = cg.searchNodes(sym, { limit: 30 });
+            }
+            catch {
+                continue;
+            }
+            const seenFiles = new Set();
+            for (const r of scanHits) {
+                if ((0, query_utils_1.isTestFile)(r.node.filePath))
+                    continue;
+                const fp = rel(r.node.filePath);
+                if (seenFiles.has(fp))
+                    continue;
+                seenFiles.add(fp);
+                const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                if (!abs)
+                    continue;
+                let content;
+                try {
+                    content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                const fileLines = content.split('\n');
+                for (let i = 0; i < fileLines.length; i++) {
+                    if (wordRe.test(fileLines[i] ?? ''))
+                        addHit(fp, i + 1);
+                }
+            }
+        }
+        if (hits.size === 0)
+            return { section: '', fileCount: 0 };
+        const lines = [
+            '**API usage sites**',
+            '',
+            `> Files referencing \`${symbols.join('`, `')}\` in this repo (${hits.size} file(s)). Answer from this list; source bodies omitted.`,
+            '',
+        ];
+        let shown = 0;
+        for (const [fp, lineNos] of [...hits.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+            if (shown >= 45)
+                break;
+            const sortedLines = [...lineNos].sort((a, b) => a - b).slice(0, 6);
+            const lineStr = sortedLines.map((l) => `L${l}`).join(', ');
+            const more = lineNos.length > sortedLines.length ? ` +${lineNos.length - sortedLines.length} more` : '';
+            lines.push(`- \`${fp}\` (${lineStr}${more})`);
+            shown++;
+        }
+        if (hits.size > shown)
+            lines.push(`- … and ${hits.size - shown} more file(s)`);
+        lines.push('');
+        lines.push(`> API usage survey complete — **${hits.size}** file(s) listed.`);
+        lines.push('');
+        return { section: lines.join('\n'), fileCount: hits.size };
+    }
+    /**
+     * Domain file inventory — related files, usage existence, or concept comparison.
+     * Paths + top symbols only; source bodies omitted when this section renders.
+     */
+    buildDomainFileSurveySection(cg, query) {
+        const terms = (0, query_utils_1.extractDomainSearchTerms)(query);
+        if (terms.length === 0)
+            return { section: '', fileCount: 0 };
+        const rel = (p) => p.replace(/\\/g, '/');
+        const fileScores = new Map();
+        const addFile = (filePath, score, symbol) => {
+            if ((0, query_utils_1.isTestFile)(filePath))
+                return;
+            const fp = rel(filePath);
+            const existing = fileScores.get(fp) ?? { score: 0, symbols: [] };
+            existing.score += score;
+            if (symbol && existing.symbols.length < 5 && !existing.symbols.includes(symbol)) {
+                existing.symbols.push(symbol);
+            }
+            fileScores.set(fp, existing);
+        };
+        for (const term of terms) {
+            let hits = [];
+            try {
+                hits = cg.searchNodes(term, { limit: 45 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                addFile(r.node.filePath, (r.score ?? 1) + 2, r.node.name);
+            }
+        }
+        try {
+            for (const f of cg.getFiles()) {
+                const fpLc = f.path.toLowerCase();
+                for (const term of terms) {
+                    if (term.length >= 3 && fpLc.includes(term.toLowerCase())) {
+                        addFile(f.path, 6);
+                    }
+                }
+            }
+        }
+        catch { /* getFiles unavailable */ }
+        if (fileScores.size === 0)
+            return { section: '', fileCount: 0 };
+        const sorted = [...fileScores.entries()]
+            .sort((a, b) => b[1].score - a[1].score)
+            .slice(0, 50);
+        const lines = [
+            '**Related files (domain survey)**',
+            '',
+            `> File paths matching the query domain (${terms.map((t) => `\`${t}\``).join(', ')}). Answer from this inventory; source bodies omitted.`,
+            '',
+        ];
+        for (const [fp, info] of sorted.slice(0, 40)) {
+            const symStr = info.symbols.length > 0 ? ` — ${info.symbols.join(', ')}` : '';
+            lines.push(`- \`${fp}\`${symStr}`);
+        }
+        if (sorted.length > 40)
+            lines.push(`- … and ${sorted.length - 40} more file(s)`);
+        lines.push('');
+        lines.push(`> Domain file survey complete — **${sorted.length}** file(s) listed. ` +
+            'Exhaustive related-file inventory; no glob/search needed.');
+        lines.push('');
+        return { section: lines.join('\n'), fileCount: sorted.length };
+    }
+    /**
+     * Render a small config/manifest file named in the query (build-profile.json5, …).
+     */
+    buildConfigFileSection(cg, query, projectRoot) {
+        const basenames = (0, query_utils_1.extractFileBasenamesFromQuery)(query);
+        if (basenames.length === 0)
+            return '';
+        const CONFIG_EXT = /\.(?:json5?|ya?ml|toml|xml|ini|properties)$/i;
+        const rel = (p) => p.replace(/\\/g, '/');
+        const lines = ['**Config / manifest**', ''];
+        let any = false;
+        for (const name of basenames.slice(0, 3)) {
+            let files = [];
+            try {
+                files = cg.searchNodes(name, { kinds: ['file'], limit: 15 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of files) {
+                const base = rel(r.node.filePath).split('/').pop() ?? '';
+                if (!base.toLowerCase().includes(name.toLowerCase()))
+                    continue;
+                if (!CONFIG_EXT.test(base))
+                    continue;
+                const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                if (!abs)
+                    continue;
+                let content;
+                try {
+                    content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                if (content.length > 12000)
+                    continue;
+                any = true;
+                lines.push(`**\`${rel(r.node.filePath)}\`**`);
+                lines.push('');
+                lines.push('```json5');
+                lines.push(content.replace(/\n+$/, ''));
+                lines.push('```');
+                lines.push('');
+            }
+        }
+        if (!any)
+            return '';
+        lines.push('> Config content above is verbatim — answer from it; no broad grep needed.');
+        lines.push('');
+        return lines.join('\n');
+    }
+    /**
+     * Compact "blast radius" for the entry symbols of an explore result: who
+     * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
+     * no source, so the agent knows what to update / re-verify before editing
+     * without reaching for a separate impact call. Always-on, but skips symbols
+     * that have no dependents (nothing to warn about), and returns '' when none
+     * qualify so a leaf-only exploration stays clean.
+     */
+    buildBlastRadiusSection(cg, subgraph) {
+        const ROOT_CAP = 5; // only the symbols the query actually targeted
+        const FILE_CAP = 4; // caller files listed per symbol before "+N more"
+        const MEANINGFUL = new Set([
+            'function', 'method', 'class', 'interface', 'struct', 'trait', 'protocol',
+            'enum', 'type_alias', 'component', 'constant', 'variable', 'property', 'field',
+        ]);
+        const rel = (p) => p.replace(/\\/g, '/');
+        const roots = subgraph.roots
+            .map((id) => subgraph.nodes.get(id))
+            .filter((n) => !!n && MEANINGFUL.has(n.kind))
+            .slice(0, ROOT_CAP);
+        if (roots.length === 0)
+            return '';
+        const entries = [];
+        for (const root of roots) {
+            let callers = [];
+            try {
+                callers = cg.getCallers(root.id);
+            }
+            catch { /* skip this root */ }
+            const seen = new Set();
+            const uniq = [];
+            for (const c of callers) {
+                if (c?.node && !seen.has(c.node.id)) {
+                    seen.add(c.node.id);
+                    uniq.push(c.node);
+                }
+            }
+            if (uniq.length === 0)
+                continue; // no blast radius → nothing to flag
+            const callerFiles = [...new Set(uniq.map((n) => rel(n.filePath)))];
+            const testFiles = callerFiles.filter((f) => (0, query_utils_1.isTestFile)(f));
+            const nonTest = callerFiles.filter((f) => !(0, query_utils_1.isTestFile)(f));
+            const shown = nonTest.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ');
+            const more = nonTest.length > FILE_CAP ? ` +${nonTest.length - FILE_CAP} more` : '';
+            const where = nonTest.length > 0 ? ` in ${shown}${more}` : '';
+            const tests = testFiles.length > 0
+                ? `; tests: ${testFiles.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ')}${testFiles.length > FILE_CAP ? ` +${testFiles.length - FILE_CAP}` : ''}`
+                : '; ⚠️ no covering tests found';
+            entries.push(`- \`${root.name}\` (${rel(root.filePath)}:${root.startLine}) — ${uniq.length} caller${uniq.length === 1 ? '' : 's'}${where}${tests}`);
+        }
+        if (entries.length === 0)
+            return '';
+        return [
+            '**Blast radius — what depends on these (update/verify before editing)**',
+            '',
+            ...entries,
+            '',
+        ].join('\n');
+    }
+    /**
+     * Graph-connectivity relevance via Random-Walk-with-Restart (personalized
+     * PageRank) from the query's matched SEED nodes over the call/reference graph.
+     *
+     * This is the ranking signal text search (FTS/bm25) CANNOT provide, and it's
+     * homegraph's home turf: relevance by STRUCTURE, not words. A file whose
+     * symbols are call-connected to the matched cluster accrues walk mass and
+     * ranks high; a lone TEXT match — e.g. `LensSwitcher.swift` matched the word
+     * "switch" from `switchOrganization`, but calls none of `setUser`/`fetchUser`
+     * — gets only its own restart probability and ranks ~0. Immune to the
+     * tokenization trap that fools term matching, deterministic, no embeddings.
+     *
      * Undirected adjacency (reachability both ways), restart α=0.25 to the seeds,
      * power iteration to convergence. Bounded to the already-relevant subgraph, so
      * it's a few hundred nodes × ~25 iterations — negligible cost.
@@ -2298,12 +4338,22 @@ class ToolHandler {
      * tax on small projects while earning its keep on large ones.
      */
     async handleExplore(args) {
-        const query = this.validateString(args.query, 'query');
-        if (typeof query !== 'string')
-            return query;
+        const rawQuery = this.validateString(args.query, 'query');
+        if (typeof rawQuery !== 'string')
+            return rawQuery;
+        // One normalization point so the flow-builder, relevance search, and
+        // ranking all see the same canonical spelling (Erlang `mod:fn/arity`).
+        const query = normalizeQuerySpelling(rawQuery);
         const cg = this.getHomeGraph(args.projectPath);
         const projectRoot = cg.getProjectRoot();
-        // Resolve adaptive output budget from project size. Falls back to the
+        const compactLocal = this.tryFastInventoryExplore(cg, query, projectRoot)
+            ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot);
+        if (compactLocal)
+            return compactLocal;
+        const lightMechanism = this.tryLightMechanismExplore(cg, query, projectRoot);
+        if (lightMechanism)
+            return lightMechanism;
+        // Resolve adaptive output budget from project size.
         // largest-tier defaults if stats aren't available, which preserves
         // pre-#185 behavior for callers that hit the rare stats failure.
         let budget;
@@ -2313,20 +4363,72 @@ class ToolHandler {
         catch {
             budget = getExploreOutputBudget(Infinity);
         }
-        const maxFiles = (0, utils_1.clamp)(args.maxFiles || budget.defaultMaxFiles, 1, 20);
+        budget = tightenExploreBudgetForQuery(budget, query);
+        const explicitMaxFiles = typeof args.maxFiles === 'number' && !Number.isNaN(args.maxFiles);
+        let maxFiles = (0, utils_1.clamp)(args.maxFiles || budget.defaultMaxFiles, 1, 20);
+        const queryFileBasenames = (0, query_utils_1.extractFileBasenamesFromQuery)(query);
+        const interpretationQuery = (0, query_utils_1.queryAsInterpretationSurvey)(query);
+        const testOnlyInterpretation = (0, query_utils_1.queryAsTestOnlyInterpretation)(query);
+        const crossModuleFlow = (0, query_utils_1.queryAsCrossModuleFlowSurvey)(query);
         // Step 1: Find relevant context with generous parameters.
-        // Use a large maxNodes budget — explore has its own 35k char output limit
-        // that prevents context bloat, so more nodes just means better coverage
-        // across entry points (especially for large files like Svelte components).
-        const subgraph = await cg.findRelevantContext(query, {
-            searchLimit: 8,
-            traversalDepth: 3,
-            maxNodes: 200,
-            minScore: 0.2,
-        });
+        const contextOpts = interpretationQuery && queryFileBasenames.length === 1
+            ? { searchLimit: 6, traversalDepth: 2, maxNodes: 60, minScore: 0.25 }
+            : { searchLimit: 8, traversalDepth: 3, maxNodes: 200, minScore: 0.2 };
+        const contextQuery = interpretationQuery && queryFileBasenames.length === 1
+            ? `${queryFileBasenames[0]} ${query}`
+            : query;
+        const subgraph = await cg.findRelevantContext(contextQuery, contextOpts);
         if (subgraph.nodes.size === 0) {
             return this.textResult(`No relevant code found for "${query}"`);
         }
+        // Seed import nodes for @kit.* / *Kit names (and named symbols like taskpool).
+        const importTerms = (0, query_utils_1.extractImportSearchTerms)(query);
+        const depSymbols = (0, query_utils_1.extractDependencySymbolsFromQuery)(query);
+        const seedImport = (r, lineText) => {
+            const lineLc = lineText.toLowerCase();
+            if (importTerms.length > 0) {
+                const kitNames = (0, query_utils_1.extractKitModuleNamesFromQuery)(query);
+                if (kitNames.length > 0 && !kitNames.some((k) => lineLc.includes(`@kit.${k.toLowerCase()}`))) {
+                    return;
+                }
+            }
+            if (depSymbols.length > 0 && !depSymbols.some((s) => lineLc.includes(s.toLowerCase()))) {
+                return;
+            }
+            if (!subgraph.nodes.has(r.node.id)) {
+                subgraph.nodes.set(r.node.id, r.node);
+                subgraph.roots.push(r.node.id);
+            }
+        };
+        for (const sym of depSymbols) {
+            let hits = [];
+            try {
+                hits = cg.searchNodes(sym, { kinds: ['import'], limit: 40 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                const sig = (r.node.signature || r.node.name || '').trim();
+                seedImport(r, sig);
+            }
+        }
+        for (const term of importTerms) {
+            const termLc = term.toLowerCase().replace(/^@kit\./, '');
+            let hits = [];
+            try {
+                hits = cg.searchNodes(term, { kinds: ['import'], limit: 12 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                const sig = (r.node.signature || r.node.name || '').trim();
+                if (!sig.toLowerCase().includes(termLc))
+                    continue;
+                seedImport(r, sig);
+            }
+        }
         // 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
@@ -2374,14 +4476,53 @@ class ToolHandler {
         // trace endpoint picker uses) and inject it as an entry, so every symbol the
         // agent explicitly named is in the subgraph and its file is scored.
         const namedSeedIds = new Set();
+        // The subset of named seeds that earns the named-FIRST sort tier. We still
+        // SEED every ≤3-def name (so RWR / flow ranking is unchanged), but only the
+        // most-substantive def is tiered — a bare name's unrelated namesakes (Go's
+        // `NewClient` = real client + test fake + xds pool) must not fill the tier
+        // and crowd out the real answer file (grpc's `dialoptions.go`). Corroborated
+        // overloads (the query also named the type) all earn it. (#1064)
+        const tierSeedIds = new Set();
         {
             const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
             const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
+            // Named types (BridgeInterceptor, ResponseFormatter) must also seed — the
+            // adaptive sibling-skeleton path needs those files in the subgraph even
+            // when they hold no callable the agent also named.
+            const SEED_KINDS = new Set([
+                ...CALLABLE,
+                'class', 'struct', 'interface', 'trait', 'protocol', 'constant', 'variable',
+            ]);
             const isTestPath = (p) => /(^|\/)(tests?|specs?|__tests__|testdata|mocks?|fixtures?)\//i.test(p) || /\.(test|spec)\.[a-z]+$/i.test(p);
             const bodyLines = (n) => Math.max(0, (n.endLine ?? n.startLine) - n.startLine);
-            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);
+            const callerCount = (n) => { try {
+                return cg.getCallers(n.id).length;
+            }
+            catch {
+                return 0;
+            } };
+            const namedParts = [];
+            for (const kit of (0, query_utils_1.extractKitModuleNamesFromQuery)(query))
+                namedParts.push(kit);
+            for (const base of (0, query_utils_1.extractFileBasenamesFromQuery)(query))
+                namedParts.push(base);
+            for (const ma of (0, query_utils_1.extractMemberAccessFromQuery)(query)) {
+                namedParts.push(ma.member);
+                if (ma.receiver)
+                    namedParts.push(ma.receiver);
+            }
+            for (const m of query.matchAll(/\b([A-Za-z_][\w]*)(::)([A-Za-z_][\w]*)\b/g)) {
+                if (m[1])
+                    namedParts.push(m[1]);
+                if (m[3])
+                    namedParts.push(m[3]);
+            }
+            const tokens = [...new Set([
+                    ...namedParts,
+                    ...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);
             // PascalCase tokens in the query are type/file disambiguators — when the
             // agent writes "DataRequest task validate", the `task`/`validate` it wants
             // are DataRequest's, NOT the same-named overloads in Validation.swift /
@@ -2405,8 +4546,15 @@ class ToolHandler {
                 const isQual = /[.\/]|::/.test(t);
                 const raw = isQual ? this.findAllSymbols(cg, t).nodes : cg.getNodesByName(t);
                 const cands = raw
-                    .filter((n) => CALLABLE.has(n.kind) && !isTestPath(n.filePath))
-                    .sort((a, b) => (bodyLines(b) > 1 ? 1 : 0) - (bodyLines(a) > 1 ? 1 : 0) || bodyLines(b) - bodyLines(a));
+                    .filter((n) => SEED_KINDS.has(n.kind) && !isTestPath(n.filePath))
+                    .sort((a, b) => {
+                    // Prefer callables over types when both share a name, then body size.
+                    const ac = CALLABLE.has(a.kind) ? 1 : 0;
+                    const bc = CALLABLE.has(b.kind) ? 1 : 0;
+                    if (ac !== bc)
+                        return bc - ac;
+                    return (bodyLines(b) > 1 ? 1 : 0) - (bodyLines(a) > 1 ? 1 : 0) || bodyLines(b) - bodyLines(a);
+                });
                 // A specific name (<=3 defs) injects all its defs. An overloaded name
                 // (`validate` = 10, `request` = 44) would flood the subgraph, so inject
                 // only: the overloads whose file/class the query ALSO names (the agent
@@ -2414,12 +4562,23 @@ class ToolHandler {
                 // capped; else fall back to the single most-substantive def. This is the
                 // explore-side mirror of homegraph_node's overload disambiguation.
                 let picks;
+                let tierPicks; // subset that earns the named-first tier (#1064)
                 if (cands.length <= 3) {
                     picks = cands;
+                    // Centrality de-noise: tier the most-substantive def PLUS any co-named
+                    // def of comparable centrality (a real overload/wrapper — excalidraw's
+                    // `mutateElement` lives in mutateElement.ts, App.tsx AND Scene.ts, all
+                    // within ~2x callers). EXCLUDE a vastly-less-central namesake (Go's
+                    // `NewClient`: real client 492 callers vs xds-pool 11, test-fake 3 →
+                    // ratio <0.025) so it doesn't fill the tier and crowd out the answer.
+                    const counts = new Map(cands.map((c) => [c.id, callerCount(c)]));
+                    const maxCallers = Math.max(1, ...counts.values());
+                    tierPicks = cands.filter((c, i) => i === 0 || (counts.get(c.id) ?? 0) >= maxCallers * 0.25);
                 }
                 else {
                     const ctx = cands.filter(inNamedContext);
                     picks = ctx.length > 0 ? ctx.slice(0, 4) : cands.slice(0, 1);
+                    tierPicks = picks; // corroborated overloads (or the single fallback) all earn it
                 }
                 for (const n of picks) {
                     if (!subgraph.nodes.has(n.id))
@@ -2431,6 +4590,70 @@ class ToolHandler {
                     // so a named symbol FTS already gathered never sorted to the top.)
                     namedSeedIds.add(n.id);
                 }
+                for (const n of tierPicks)
+                    tierSeedIds.add(n.id);
+            }
+            // Mechanism survey: seed query-shaped entry symbols first, then domain search.
+            if ((0, query_utils_1.queryAsMechanismSurvey)(query)) {
+                const STRUCTURE_KINDS = new Set(['class', 'struct', 'interface', 'component']);
+                const implEntryNames = [];
+                for (const seed of (0, query_utils_1.extractMechanismEntrySeeds)(query)) {
+                    if (seed.startsWith('@')) {
+                        let hits = [];
+                        try {
+                            hits = cg.searchNodes(seed, { kinds: ['import'], limit: 20 });
+                        }
+                        catch {
+                            continue;
+                        }
+                        for (const r of hits) {
+                            if (isTestPath(r.node.filePath))
+                                continue;
+                            if (!subgraph.nodes.has(r.node.id))
+                                subgraph.nodes.set(r.node.id, r.node);
+                            namedSeedIds.add(r.node.id);
+                            tierSeedIds.add(r.node.id);
+                        }
+                        continue;
+                    }
+                    const nodes = cg.getNodesByName(seed).filter((n) => STRUCTURE_KINDS.has(n.kind) && !isTestPath(n.filePath));
+                    for (const n of nodes.slice(0, 3)) {
+                        if (!subgraph.nodes.has(n.id))
+                            subgraph.nodes.set(n.id, n);
+                        namedSeedIds.add(n.id);
+                        tierSeedIds.add(n.id);
+                        if (!implEntryNames.includes(n.name))
+                            implEntryNames.push(n.name);
+                    }
+                }
+                if (implEntryNames.length < 2) {
+                    const domainTerms = (0, query_utils_1.extractDomainSearchTerms)(query);
+                    for (const term of domainTerms.slice(0, 5)) {
+                        let hits = [];
+                        try {
+                            hits = cg.searchNodes(term, { kinds: ['class', 'struct', 'interface'], limit: 30 });
+                        }
+                        catch {
+                            continue;
+                        }
+                        for (const r of hits) {
+                            if (isTestPath(r.node.filePath))
+                                continue;
+                            if (!(0, query_utils_1.isImplementationEntrySymbol)(r.node.name, domainTerms))
+                                continue;
+                            if (!subgraph.nodes.has(r.node.id))
+                                subgraph.nodes.set(r.node.id, r.node);
+                            namedSeedIds.add(r.node.id);
+                            tierSeedIds.add(r.node.id);
+                            if (!implEntryNames.includes(r.node.name))
+                                implEntryNames.push(r.node.name);
+                            if (implEntryNames.length >= 6)
+                                break;
+                        }
+                        if (implEntryNames.length >= 6)
+                            break;
+                    }
+                }
             }
         }
         // Step 2: Group nodes by file, score by relevance
@@ -2444,6 +4667,46 @@ class ToolHandler {
             if (entryNodeIds.has(edge.target))
                 connectedToEntry.add(edge.source);
         }
+        // CHANGE SURFACE (#1064): a named method's signature types — its parameter
+        // and return types — are part of what you'd edit to "add a parameter to X",
+        // yet they can be lexically dissimilar to the query ("add a parameter to
+        // NewClient" shares no words with `dialoptions.go`, which defines NewClient's
+        // `DialOption`) and sit a hop away. COLLECT them here from each named-seed
+        // callable's outgoing signature edges (full graph — the type is often not in
+        // the subgraph); the decision to surface one is DEFERRED to the buried-rescue
+        // pass below, which fires only when the type's file would otherwise be
+        // dropped — so a well-connected type (excalidraw's element types, Alamofire's
+        // `DataRequest` on a flow query) is left to rank on its own and never
+        // displaces a flow-central file. Bounded: only the few named seeds, only the
+        // types in their signatures.
+        const CALLABLE_KINDS = new Set(['method', 'function', 'component', 'constructor']);
+        const TYPE_KINDS = new Set(['class', 'struct', 'interface', 'trait', 'protocol', 'enum', 'type_alias']);
+        const SIG_EDGE = new Set(['references', 'type_of', 'returns']);
+        const changeSurfaceCandidates = [];
+        const seenChangeSurface = new Set();
+        for (const seedId of tierSeedIds) {
+            const seedNode = subgraph.nodes.get(seedId);
+            if (!seedNode || !CALLABLE_KINDS.has(seedNode.kind))
+                continue;
+            let outs = [];
+            try {
+                outs = cg.getOutgoingEdges(seedId);
+            }
+            catch {
+                continue;
+            }
+            for (const e of outs) {
+                if (!SIG_EDGE.has(e.kind))
+                    continue;
+                const tgt = cg.getNode(e.target);
+                if (!tgt || !TYPE_KINDS.has(tgt.kind) || namedSeedIds.has(tgt.id))
+                    continue;
+                if (seenChangeSurface.has(tgt.id))
+                    continue;
+                seenChangeSurface.add(tgt.id);
+                changeSurfaceCandidates.push(tgt);
+            }
+        }
         for (const node of subgraph.nodes.values()) {
             // Skip import/export nodes — they add noise without information
             if (node.kind === 'import' || node.kind === 'export')
@@ -2476,6 +4739,14 @@ class ToolHandler {
             }
             fileGroups.set(node.filePath, group);
         }
+        if (testOnlyInterpretation) {
+            for (const [, group] of fileGroups) {
+                const fp = group.nodes[0]?.filePath ?? '';
+                if (fp && !(0, query_utils_1.isTestFile)(fp) && !(0, query_utils_1.fileMatchesQueryBasename)(fp, queryFileBasenames)) {
+                    group.score = Math.max(0, group.score - 50);
+                }
+            }
+        }
         // Only include files that have entry points or nodes directly connected to entry points
         let relevantFiles = [...fileGroups.entries()].filter(([, group]) => group.score >= 3);
         // Extract query terms for relevance checking
@@ -2563,6 +4834,36 @@ class ToolHandler {
             if (n)
                 entryFiles.add(n.filePath);
         }
+        // Buried-rescue pass (#1064): surface a named method's signature type ONLY
+        // when its file is genuinely buried — near-zero graph mass AND not lexically
+        // matched. That is the invisible case (grpc's `DialOption` → `dialoptions.go`,
+        // g≈0, 0 term hits): reachable but ranked nowhere, so the agent greps. A
+        // well-connected type file (excalidraw element types, Alamofire `DataRequest`)
+        // is NOT buried and is left alone — rescuing it would displace a flow-central
+        // file (App.tsx, Validation.swift). Buried is judged on the PRE-rescue graph,
+        // so injecting the type below can't make it look connected. A rescued file is
+        // injected (so it renders), force-kept (gate + relevantFiles), and tiered.
+        const changeSurfaceFiles = new Set();
+        for (const t of changeSurfaceCandidates) {
+            const fp = t.filePath;
+            const buried = (fileGraphScore.get(fp) ?? 0) < maxGraph * 0.06
+                && (fileTermHits.get(fp) ?? 0) < 2;
+            if (!buried)
+                continue;
+            changeSurfaceFiles.add(fp);
+            if (!subgraph.nodes.has(t.id))
+                subgraph.nodes.set(t.id, t);
+            let group = fileGroups.get(fp);
+            if (!group) {
+                group = { nodes: [], score: 0 };
+                fileGroups.set(fp, group);
+            }
+            if (!group.nodes.some((n) => n.id === t.id))
+                group.nodes.push(t);
+            group.score = Math.max(group.score, 45);
+            if (!relevantFiles.some(([f]) => f === fp))
+                relevantFiles.push([fp, group]);
+        }
         // Relevance gate (so the generous budget is a CEILING, not a target): keep a
         // file only if it is STRUCTURALLY relevant by ANY of:
         //   - graph score within a fraction of the top (it's on/near the flow), OR
@@ -2579,6 +4880,7 @@ class ToolHandler {
             const gated = relevantFiles.filter(([fp]) => (fileGraphScore.get(fp) ?? 0) >= maxGraph * 0.06
                 || centralFiles.has(fp)
                 || entryFiles.has(fp)
+                || changeSurfaceFiles.has(fp)
                 || (fileTermHits.get(fp) ?? 0) >= 2);
             if (gated.length >= 2)
                 relevantFiles = gated;
@@ -2593,11 +4895,16 @@ class ToolHandler {
         // in other files (`Validation.swift`), falls outside the budget, and the
         // agent Reads it. The named file is the answer — rank it at the top.
         const namedSeedFiles = new Set();
-        for (const id of namedSeedIds) {
+        for (const id of tierSeedIds) {
             const n = subgraph.nodes.get(id);
             if (n)
                 namedSeedFiles.add(n.filePath);
         }
+        // A rescued change-surface file (only the genuinely-buried ones — see the
+        // buried-rescue pass) is the lexically-dissimilar answer; give it the named
+        // tier so it isn't buried under files that merely share surface words (#1064).
+        for (const fp of changeSurfaceFiles)
+            namedSeedFiles.add(fp);
         // Multi-term corroboration tier: a file that is BOTH (a) an entry/central file
         // (a search root, named seed, or graph-central hub — i.e. structurally part of
         // the answer) AND (b) matched by ≥2 DISTINCT query terms must not be buried by
@@ -2617,9 +4924,16 @@ class ToolHandler {
         const isCorroborated = (fp) => !MULTITERM_OFF &&
             (fileTermHits.get(fp) ?? 0) >= 2 &&
             (entryFiles.has(fp) || centralFiles.has(fp));
+        const queryMemberAccesses = (0, query_utils_1.extractMemberAccessFromQuery)(query);
         const sortedFiles = relevantFiles.sort((a, b) => {
             const aPath = a[0].toLowerCase();
             const bPath = b[0].toLowerCase();
+            // Query-named file (LocationController.ets in the question) before partial
+            // substring matches (control.ets matching "Controller" inside LocationController).
+            const aExactBase = (0, query_utils_1.fileMatchesQueryBasename)(a[0], queryFileBasenames) ? 1 : 0;
+            const bExactBase = (0, query_utils_1.fileMatchesQueryBasename)(b[0], queryFileBasenames) ? 1 : 0;
+            if (aExactBase !== bExactBase)
+                return bExactBase - aExactBase;
             // Agent-named files first (it asked for a symbol defined here by name).
             const aNamed = namedSeedFiles.has(a[0]) ? 1 : 0;
             const bNamed = namedSeedFiles.has(b[0]) ? 1 : 0;
@@ -2662,19 +4976,164 @@ class ToolHandler {
         const lines = [
             `**Exploration: ${query}**`,
             '',
-            `Found ${subgraph.nodes.size} symbols across ${fileGroups.size} files.`,
+            // Curated summary — filled in after the source loop (see below). We do NOT
+            // report `subgraph.nodes.size` / `fileGroups.size` here: that's the raw
+            // candidate gather, which a broad natural-language query inflates wildly
+            // (260 symbols / 124 files on a 636-file repo) even though only a handful
+            // render. Reporting the pool read as "260 results to wade through" when the
+            // real, correctly-ranked answer is the few files below (#1046).
+            '',
             '',
         ];
-        // Blast radius (always-on, compact): for the entry symbols, who depends on
-        // them + which tests cover them — locations only, no source — so the agent
-        // knows what to update/verify before editing without a separate call.
-        const blastRadius = this.buildBlastRadiusSection(cg, subgraph);
-        if (blastRadius)
-            lines.push(blastRadius);
-        // Relationship map — show how symbols connect
+        const summaryLineIdx = 2;
+        if (testOnlyInterpretation) {
+            lines.push('> **Test-file scope only** — answer from the named `.test.ets` file below; ' +
+                'production handlers are out of scope unless explicitly referenced in the test.');
+            lines.push('');
+        }
+        const importResult = this.buildImportSitesSection(cg, query, projectRoot);
+        if (importResult.section)
+            lines.push(importResult.section);
+        const homonymSection = this.buildHomonymDefinitionsSection(cg, query);
+        if (homonymSection)
+            lines.push(homonymSection);
+        const kitUsageResult = (0, query_utils_1.shouldBuildKitModuleUsageSurvey)(query)
+            ? this.buildKitModuleUsageSection(cg, query, projectRoot)
+            : { section: '', symbolCount: 0 };
+        if (kitUsageResult.section)
+            lines.push(kitUsageResult.section);
+        const domainFileResult = (0, query_utils_1.shouldBuildDomainFileSurvey)(query)
+            ? this.buildDomainFileSurveySection(cg, query)
+            : { section: '', fileCount: 0 };
+        if (domainFileResult.section)
+            lines.push(domainFileResult.section);
+        const apiUsageResult = (0, query_utils_1.shouldBuildApiUsageSurvey)(query)
+            ? this.buildApiUsageSection(cg, query, projectRoot)
+            : { section: '', fileCount: 0 };
+        if (apiUsageResult.section)
+            lines.push(apiUsageResult.section);
+        const dataSourceResult = (0, query_utils_1.queryAsDataSourceSurvey)(query)
+            ? this.buildDataSourceSection(cg, query)
+            : { section: '', edgeCount: 0 };
+        if (dataSourceResult.section)
+            lines.push(dataSourceResult.section);
+        const importInventoryFilter = (0, query_utils_1.hasImportInventoryFilter)(query);
+        const multiAnchor = (0, query_utils_1.queryNamesMultipleExploreAnchors)(query) || crossModuleFlow;
+        const mechanismSurvey = (0, query_utils_1.queryAsMechanismSurvey)(query);
+        // Flow path — computed before omit-source so graph connectivity drives the decision,
+        // not question-text keyword matching. Mechanism/cross-module surveys augment the
+        // query with seeded entry symbol names so buildFlowFromNamedSymbols can connect them.
+        let flowQuery = query;
+        if (crossModuleFlow) {
+            flowQuery = `${query} ${(0, query_utils_1.extractTypeNamesFromQuery)(query).join(' ')}`;
+        }
+        else if (mechanismSurvey) {
+            const seeds = (0, query_utils_1.extractMechanismEntrySeeds)(query);
+            if (seeds.length >= 2) {
+                flowQuery = `${query} ${seeds.join(' ')}`;
+            }
+            else {
+                const entryNames = [...subgraph.nodes.values()]
+                    .filter((n) => (n.kind === 'class' || n.kind === 'struct' || n.kind === 'interface')
+                    && (0, query_utils_1.isImplementationEntrySymbol)(n.name, (0, query_utils_1.extractDomainSearchTerms)(query)))
+                    .map((n) => n.name)
+                    .slice(0, 6);
+                if (entryNames.length >= 2)
+                    flowQuery = `${query} ${entryNames.join(' ')}`;
+            }
+        }
+        const flow = this.buildFlowFromNamedSymbols(cg, flowQuery);
+        const hasFlowPath = flow.pathNodeIds.size > 0;
+        budget = tightenExploreBudgetForQuery(budget, query, { hasFlowPath });
+        // Honor an explicit maxFiles from the caller — budget.defaultMaxFiles is only
+        // a default when the agent didn't ask for more (adaptive sibling tests pass 12).
+        if (!explicitMaxFiles) {
+            maxFiles = Math.min(maxFiles, (0, utils_1.clamp)(budget.defaultMaxFiles, 1, 20));
+        }
+        const localDetail = (0, query_utils_1.queryAsLocalSymbolDetail)(query);
+        const inheritanceSection = !hasFlowPath && !multiAnchor
+            ? this.buildInheritanceSurveySection(cg, query) : '';
+        const callerSection = !hasFlowPath && !multiAnchor && (0, query_utils_1.shouldBuildCallerInventory)(query)
+            ? this.buildCallerListingSection(cg, query) : '';
+        const memberSection = !hasFlowPath && !multiAnchor && (0, query_utils_1.shouldBuildMemberSurvey)(query)
+            ? this.buildMemberSurveySection(cg, query, projectRoot) : '';
+        const configSection = (0, query_utils_1.shouldBuildConfigSection)(query)
+            ? this.buildConfigFileSection(cg, query, projectRoot) : '';
+        if (inheritanceSection)
+            lines.push(inheritanceSection);
+        if (callerSection)
+            lines.push(callerSection);
+        if (memberSection)
+            lines.push(memberSection);
+        if (configSection)
+            lines.push(configSection);
+        const finishCompact = (summary) => {
+            lines[summaryLineIdx] = summary;
+            return this.textResult(lines.join('\n'));
+        };
+        const memberFileCount = memberSection
+            ? memberSection.split('\n').filter((l) => l.startsWith('- ')).length
+            : 0;
+        const callerBulletCount = callerSection
+            ? callerSection.split('\n').filter((l) => l.startsWith('- ') && l.includes(' ← ')).length
+            : 0;
+        const inheritanceListed = inheritanceSection
+            ? inheritanceSection.split('\n').filter((l) => l.startsWith('- `')).length > 0
+            : false;
+        const omitSource = (0, query_utils_1.shouldOmitSourceBodies)({
+            importSiteCount: importResult.siteCount,
+            hasFilteredImports: importInventoryFilter && importResult.siteCount > 0,
+            callerBulletCount,
+            memberFileCount,
+            apiUsageFileCount: apiUsageResult.fileCount,
+            configRendered: !!configSection,
+            kitModuleSurveyRendered: !!kitUsageResult.section,
+            inheritanceListed,
+            domainFileCount: domainFileResult.fileCount,
+            dataSourceEdgeCount: dataSourceResult.edgeCount,
+        }, hasFlowPath, multiAnchor);
+        if (omitSource) {
+            if (configSection) {
+                return finishCompact('Config/manifest content above — answer from it directly.');
+            }
+            if (kitUsageResult.section) {
+                return finishCompact(`Kit module usage survey — **${kitUsageResult.symbolCount}** imported symbol(s) across the repo. SDK definitions are not in this project; answer from the usage list above.`);
+            }
+            if (domainFileResult.section && domainFileResult.fileCount > 0) {
+                return finishCompact(`Domain file survey — **${domainFileResult.fileCount}** related file(s) listed above. Source bodies omitted; answer from the inventory.`);
+            }
+            if (apiUsageResult.section && apiUsageResult.fileCount > 0) {
+                return finishCompact(`API usage survey — **${apiUsageResult.fileCount}** file(s) referencing the queried symbol(s). Source bodies omitted; answer from the list above.`);
+            }
+            if (dataSourceResult.section && dataSourceResult.edgeCount > 0) {
+                return finishCompact(`Data-source survey — **${dataSourceResult.edgeCount}** upstream symbol(s) listed above. Source bodies omitted; answer from the inventory.`);
+            }
+            if (inheritanceListed) {
+                return finishCompact('Inheritance survey above lists all direct subtypes found — source bodies omitted.');
+            }
+            if (importResult.compactListing) {
+                return finishCompact(`Listed **${importResult.siteCount}** import site(s) for the queried symbol(s). Source bodies omitted — answer from the dependency list above.`);
+            }
+            if (callerBulletCount >= 1) {
+                return finishCompact(`Caller inventory above lists **${callerBulletCount}** method(s) with external callers — source bodies omitted.`);
+            }
+            if (memberSection && memberFileCount >= 2) {
+                return finishCompact(`Member/pattern usage in **${memberFileCount}** file(s) — source bodies omitted; answer from the inventory above.`);
+            }
+        }
+        // Blast radius only for structural flow / mechanism answers — skip on local-detail
+        // and no-flow dumps (it's expensive and rarely changes the answer there).
+        if (!localDetail && (hasFlowPath || mechanismSurvey || crossModuleFlow)) {
+            const blastRadius = this.buildBlastRadiusSection(cg, subgraph);
+            if (blastRadius)
+                lines.push(blastRadius);
+        }
+        // Relationship map — show how symbols connect (skip when no flow path: saves
+        // tokens on survey/dependency/how-to questions that don't need call graphs).
         const significantEdges = subgraph.edges.filter(e => e.kind !== 'contains' // skip contains — it's implied by file grouping
         );
-        if (budget.includeRelationships && significantEdges.length > 0) {
+        if (budget.includeRelationships && hasFlowPath && !importResult.compactListing
+            && significantEdges.length > 0) {
             lines.push('**Relationships**');
             lines.push('');
             // Group edges by kind for readability
@@ -2702,10 +5161,7 @@ class ToolHandler {
             }
         }
         // Step 4: Read contiguous file sections
-        // Compute the flow spine once — used both to prepend the Flow section (below)
-        // and to gate adaptive source sizing: files on the spine get full source,
-        // off-spine peers skeletonize.
-        const flow = this.buildFlowFromNamedSymbols(cg, query);
+        // (flow already computed above for relationship gating and adaptive sizing)
         // Polymorphic-sibling detector for adaptive sizing. A class that implements/
         // extends a supertype shared by >= MIN_SIBLINGS classes is one of many
         // INTERCHANGEABLE implementations (OkHttp's 14 `: Interceptor` classes —
@@ -2762,13 +5218,61 @@ class ToolHandler {
         };
         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('> Line-numbered source — treat as already Read. Answer from Flow + Source below when you can; ' +
+            'do not re-read/grep these files, and do not fan out `homegraph_node` / search for symbols already shown. ' +
+            'Another `homegraph_explore` with tighter names only if a needed symbol is missing.');
         lines.push('');
         let totalChars = lines.join('\n').length;
         let filesIncluded = 0;
+        // Paths we actually render source for below. Drives the curated header count
+        // (#1046) — it must reflect what we show, not the raw candidate gather.
+        const renderedFilePaths = [];
         let anyFileTrimmed = false;
-        for (const [filePath, group] of sortedFiles) {
-            if (filesIncluded >= maxFiles)
+        const limitSingleFile = (0, query_utils_1.shouldLimitToQueryNamedFile)(query, hasFlowPath, multiAnchor)
+            || (interpretationQuery && queryFileBasenames.length === 1);
+        let filesToRender = sortedFiles;
+        if (limitSingleFile) {
+            const anchored = sortedFiles.filter(([fp]) => (0, query_utils_1.fileMatchesQueryBasename)(fp, queryFileBasenames));
+            if (anchored.length > 0)
+                filesToRender = anchored.slice(0, 1);
+        }
+        else if ((0, query_utils_1.shouldFocusOnNamedTypeFile)(query, hasFlowPath, multiAnchor)) {
+            const typeName = (0, query_utils_1.extractTypeNamesFromQuery)(query)[0];
+            const anchored = sortedFiles.filter(([, group]) => group.nodes.some((n) => n.name === typeName && (n.kind === 'class' || n.kind === 'interface' || n.kind === 'struct')));
+            if (anchored.length > 0)
+                filesToRender = anchored.slice(0, 1);
+        }
+        else if ((0, query_utils_1.shouldFocusOnQueryNamedDefs)(query, hasFlowPath, multiAnchor)) {
+            const nameSet = new Set([
+                ...(0, query_utils_1.extractTypeNamesFromQuery)(query),
+                ...(0, query_utils_1.extractDependencySymbolsFromQuery)(query),
+                ...(0, query_utils_1.extractMemberAccessFromQuery)(query).map((m) => m.member),
+            ]);
+            const anchored = sortedFiles.filter(([, group]) => group.nodes.some((n) => nameSet.has(n.name)));
+            if (anchored.length > 0) {
+                filesToRender = anchored.slice(0, localDetail ? 2 : 3);
+            }
+        }
+        else if (crossModuleFlow && hasFlowPath) {
+            const onSpine = sortedFiles.filter(([, group]) => group.nodes.some((n) => flow.pathNodeIds.has(n.id) || flow.uniqueNamedNodeIds.has(n.id)));
+            if (onSpine.length > 0)
+                filesToRender = onSpine;
+        }
+        const sourceFileCap = limitSingleFile && filesToRender.length === 1
+            ? 1
+            : localDetail
+                ? Math.min(maxFiles, 2)
+                : crossModuleFlow && hasFlowPath
+                    ? Math.min(maxFiles, 5)
+                    : mechanismSurvey && hasFlowPath
+                        ? Math.min(maxFiles, 4)
+                        : mechanismSurvey
+                            ? Math.min(maxFiles, 3)
+                            : !hasFlowPath
+                                ? Math.min(maxFiles, 3)
+                                : maxFiles;
+        for (const [filePath, group] of filesToRender) {
+            if (filesIncluded >= sourceFileCap)
                 break;
             // A file DEFINES a named/spine symbol (the answer) vs merely references the
             // flow. Past 90% budget, stop pulling INCIDENTAL files — but keep scanning
@@ -2779,6 +5283,24 @@ class ToolHandler {
             const fileNecessary = group.nodes.some(n => entryNodeIds.has(n.id) || flow.pathNodeIds.has(n.id) || flow.uniqueNamedNodeIds.has(n.id));
             if (!fileNecessary && totalChars > budget.maxOutputChars * 0.9)
                 continue;
+            if ((0, arkts_1.isOhosApiFilePath)(filePath)) {
+                const rel = filePath.slice(arkts_1.OHOS_API_FILE_PREFIX.length);
+                const syms = group.nodes
+                    .filter((n) => n.kind !== 'import' && n.kind !== 'export')
+                    .sort((a, b) => a.startLine - b.startLine);
+                if (syms.length === 0)
+                    continue;
+                lines.push(fileSectionHeader(rel, 'HarmonyOS SDK API (prebuilt db)'));
+                lines.push('');
+                for (const n of syms) {
+                    const sig = n.signature || n.docstring || `${n.kind} ${n.qualifiedName || n.name}`;
+                    lines.push(`\`${sig}\``);
+                }
+                lines.push('');
+                totalChars = lines.join('\n').length;
+                filesIncluded++;
+                continue;
+            }
             const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, filePath);
             if (!absPath || !(0, fs_1.existsSync)(absPath))
                 continue;
@@ -2917,6 +5439,7 @@ class ToolHandler {
                         : 'skeleton (signatures only — homegraph_explore a name for its full body; do NOT Read)';
                     lines.push(fileSectionHeader(filePath, `${names} · ${tag}`), '', '```' + lang, skel.join('\n'), '```', '');
                     totalChars += skel.join('\n').length + 120;
+                    renderedFilePaths.push(filePath);
                     filesIncluded++;
                     continue;
                 }
@@ -2963,6 +5486,7 @@ class ToolHandler {
                 }
                 lines.push(wholeHeader, '', '```' + lang, wholeSection, '```', '');
                 totalChars += wholeSection.length + 200;
+                renderedFilePaths.push(filePath);
                 filesIncluded++;
                 continue;
             }
@@ -3044,6 +5568,39 @@ class ToolHandler {
                     ranges.push({ start: edge.line, end: edge.line, name: targetName, kind: edge.kind, importance: 2, spine: false });
                 }
             }
+            // Query member-access anchors: pin lines the question names (locationManager.on,
+            // .drawModifier) so per-file budget gaps don't hide the exact call site.
+            if (queryMemberAccesses.length > 0) {
+                const anchorLines = new Set();
+                for (const ma of queryMemberAccesses) {
+                    const patterns = [];
+                    if (ma.receiver) {
+                        const recv = ma.receiver.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                        const mem = ma.member.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                        patterns.push(new RegExp(`${recv}\\.${mem}\\s*\\(`));
+                        patterns.push(new RegExp(`${recv}\\.${mem}\\b`));
+                    }
+                    else if (ma.dotted.startsWith('.')) {
+                        const lit = ma.dotted.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                        patterns.push(new RegExp(`${lit}\\b`));
+                    }
+                    for (let i = 0; i < fileLines.length; i++) {
+                        const line = fileLines[i] ?? '';
+                        if (patterns.some((p) => p.test(line)))
+                            anchorLines.add(i + 1);
+                    }
+                }
+                for (const lineNo of anchorLines) {
+                    ranges.push({
+                        start: lineNo,
+                        end: lineNo,
+                        name: 'query-anchor',
+                        kind: 'anchor',
+                        importance: 11,
+                        spine: false,
+                    });
+                }
+            }
             ranges.sort((a, b) => a.start - b.start);
             if (ranges.length === 0)
                 continue;
@@ -3251,8 +5808,14 @@ class ToolHandler {
             lines.push('```');
             lines.push('');
             totalChars += fileSection.length + 200;
+            renderedFilePaths.push(filePath);
             filesIncluded++;
         }
+        // The curated header count is computed from the files that SURVIVE the final
+        // truncation (see end of method) — `filesIncluded` can over-count when the
+        // hard ceiling drops trailing sections — so leave a sentinel here and fill it
+        // in once the output is final.
+        lines[summaryLineIdx] = SUMMARY_SENTINEL;
         // Add remaining files as references (from both relevant and peripheral files).
         // Small projects (per budget) skip this — the relevant story already fits
         // in the source section, and a trailing pointer list is pure overhead.
@@ -3309,6 +5872,7 @@ class ToolHandler {
         // externalize territory.
         const output = flow.text + lines.join('\n');
         const hardCeiling = Math.min(Math.round(budget.maxOutputChars * 1.5), 25000);
+        let finalText;
         if (output.length > hardCeiling) {
             // Cut at a FILE-SECTION boundary (the last ``**` `` file header before the
             // ceiling) so we drop whole trailing file-sections rather than slicing
@@ -3319,9 +5883,36 @@ class ToolHandler {
             const lastSection = cut.lastIndexOf('\n' + FILE_SECTION_PREFIX);
             const boundary = lastSection > hardCeiling * 0.5 ? lastSection : cut.lastIndexOf('\n');
             const safe = boundary > 0 ? cut.slice(0, boundary) : 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 homegraph_explore with the specific names — do NOT Read these files.)');
+            finalText = safe + '\n\n... (output truncated to budget; the source above is complete and verbatim — treat it as already Read. For uncovered files/symbols, run another homegraph_explore with their exact names — not grep/read/node for symbols already shown.)';
         }
-        return this.textResult(output);
+        else {
+            finalText = output;
+        }
+        if (!finalText.includes('**Partial result**') && !finalText.includes('> **Explore complete**')) {
+            finalText +=
+                '\n\n> **Explore complete — ANSWER NOW.** Flow + Source above are authoritative for this query. ' +
+                    'Do **not** grep/read/`homegraph_node`/`homegraph_search` for the same symbols or files. ' +
+                    'Only call one tighter `homegraph_explore` if a named symbol essential to the answer is missing.';
+        }
+        // Curated header (#1046): substitute the sentinel with the count of files
+        // whose source SURVIVES in the final text — not `subgraph`/`fileGroups` (the
+        // raw gather a broad query inflates) and not `filesIncluded` (which can
+        // over-count when the ceiling above drops trailing sections). A file counts
+        // only if its section header is still present; its relevant (non-import)
+        // symbols are summed for N. Files we couldn't fit are still named under "Not
+        // shown above" + the budget note, so nothing is silently dropped.
+        const survivors = renderedFilePaths.filter((fp) => finalText.includes(`${FILE_SECTION_PREFIX}${fp}\``));
+        const shownSymbols = survivors.reduce((sum, fp) => {
+            const g = fileGroups.get(fp);
+            if (!g)
+                return sum;
+            return sum + new Set(g.nodes.filter((n) => n.kind !== 'import' && n.kind !== 'export').map((n) => n.id)).size;
+        }, 0);
+        const summaryLine = survivors.length > 0
+            ? `Found ${shownSymbols} symbol${shownSymbols === 1 ? '' : 's'} across ${survivors.length} file${survivors.length === 1 ? '' : 's'}.`
+            : `Found ${subgraph.nodes.size} symbol${subgraph.nodes.size === 1 ? '' : 's'} across ${fileGroups.size} file${fileGroups.size === 1 ? '' : 's'}.`;
+        finalText = finalText.replace(SUMMARY_SENTINEL, summaryLine);
+        return this.textResult(finalText);
     }
     /**
      * Handle homegraph_node
@@ -3392,12 +5983,12 @@ class ToolHandler {
             const list = matches.map((n) => `- \`${n.name}\` (${n.kind}) — ${n.filePath}:${n.startLine}`);
             return this.textResult(this.truncateOutput([header, '', 'Re-query with `includeCode: true` to get every body in one call — no need to pick one first.', '', ...list].join('\n')));
         }
-        const BODY_BUDGET = 12000; // leaves room under MAX_OUTPUT_LENGTH for the header + list
+        const BODY_BUDGET = 10_000; // leaves room under MAX_OUTPUT_LENGTH for the header + list
         // The CHAR budget is the real limiter — keep the count cap high so a set of
         // SHORT overloads (Alamofire's 10 `validate` variants, each a few lines) all
         // render in full rather than relegating the one the agent wanted to a
         // bodiless list. Only a set of many LARGE bodies hits the char budget first.
-        const HARD_CAP = 16;
+        const HARD_CAP = 12;
         const rendered = [];
         const listed = [];
         let used = 0;
@@ -3483,7 +6074,7 @@ class ToolHandler {
         const symbolMap = (heading, limit = 200) => {
             const lines = [heading];
             for (const n of nodes.slice(0, limit)) {
-                const sig = n.signature ? ` ${n.signature.replace(/\s+/g, ' ').trim()}` : '';
+                const sig = n.signature ? ` ${formatInlineSignature(n.signature)}` : '';
                 lines.push(`- \`${n.name}\` (${n.kind})${sig} — :${n.startLine}`);
             }
             if (nodes.length > limit)
@@ -3533,12 +6124,12 @@ class ToolHandler {
         const fileLines = content.split('\n');
         const total = fileLines.length;
         // Read-parity windowing: `offset`/`limit` mean exactly what they do on Read
-        // (1-based start line; max line count). Default: the whole file, capped like
-        // Read at 2000 lines and bounded by a char budget that tracks explore's
-        // proven-safe ~38k response ceiling. Overflow is stated explicitly (Read
-        // paginates too) — never the silent 15k truncateOutput chop.
-        const CHAR_BUDGET = 38000;
-        const DEFAULT_LIMIT = 2000;
+        // (1-based start line; max line count). Default window is intentionally
+        // smaller than explore's flow budget — dumping a whole multi-kLOC file from
+        // `homegraph_node` teaches the agent to over-drill and burns tokens.
+        // Overflow is stated explicitly (pass offset/limit or name a symbol).
+        const CHAR_BUDGET = 12_000;
+        const DEFAULT_LIMIT = 400;
         const offset = Math.max(1, opts.offset ?? 1);
         if (offset > total) {
             return this.textResult(`**${filePath}** has ${total} line${total === 1 ? '' : 's'} — offset ${offset} is past the end. ${depSummary}`);
@@ -3561,8 +6152,9 @@ class ToolHandler {
         const complete = offset === 1 && shownEnd >= total;
         const out = [header, '', ...numbered];
         if (!complete) {
-            out.push('', `(lines ${offset}–${shownEnd} of ${total} — pass \`offset\`/\`limit\` for another range, or \`homegraph_node <symbol>\` for one symbol in full)`);
+            out.push('', `(lines ${offset}–${shownEnd} of ${total} — pass \`offset\`/\`limit\` for another range, or \`homegraph_node\` with a symbol name for one body in full)`);
         }
+        out.push('', '> Treat this source as already Read. Prefer answering now; do not grep/read the same file or fan out more `homegraph_node` calls for symbols listed above.');
         // Self-bounded to CHAR_BUDGET — do NOT route through truncateOutput (15k).
         return this.textResult(out.join('\n'));
     }
@@ -3886,12 +6478,12 @@ class ToolHandler {
             return query;
         const repoPath = args.repoPath;
         const explicitDbPath = args.dbPath;
-        const topK = Math.max(1, Math.min(Number(args.topK) || 5, 50));
+        const topKRaw = Number(args.topK);
+        const topK = Math.max(1, Math.min(isNaN(topKRaw) ? 5 : topKRaw, 50));
         const includeFragments = args.includeFragments !== false;
         // Lazily require spec modules so the MCP startup path stays lean.
         const { resolveDbPath } = require('../spec/utils');
         const { createDatabase } = require('../db/sqlite-adapter');
-        const { initSpecSchema } = require('../spec/db/schema');
         const { searchAndGetContext } = require('../spec/graph/queries');
         const { truncateCodeDiff, truncateSubtitles, computeBudgetProfile, } = require('../spec/utils');
         // Resolve the database path.
@@ -3906,8 +6498,6 @@ class ToolHandler {
                 `${err instanceof Error ? err.message : String(err)}`);
         }
         try {
-            // Ensure the schema exists (idempotent).
-            initSpecSchema(db);
             // Search and traverse.
             const contexts = searchAndGetContext(db, query, topK, includeFragments);
             if (contexts.length === 0) {
@@ -3975,15 +6565,238 @@ class ToolHandler {
                     return this.textResult(`(Fragments elided — output exceeded ${MAX_OUTPUT_LENGTH} chars)\n\n` + slim);
                 }
             }
-            // Fallback: hard-truncate the JSON.
-            const truncated = json.slice(0, MAX_OUTPUT_LENGTH - 3) + '...';
-            return this.textResult(truncated);
+            // Fallback: truncate at a newline to avoid broken JSON.
+            return this.textResult(this.truncateOutput(json));
+        }
+        finally {
+            db.close();
+        }
+    }
+    // =========================================================================
+    // handleSpecFind — file-path based spec lookup
+    // =========================================================================
+    /**
+     * Find which specs are related to the given file path by matching against
+     * code-fragment file paths in the Commit4Spec knowledge graph.
+     *
+     * Traverses: filePath → code_fragment_nodes → commit_fragment_relations
+     * → spec_commit_relations → spec_nodes.
+     */
+    async handleSpecFind(args) {
+        const filePath = this.validateString(args.filePath, 'filePath');
+        if (typeof filePath !== 'string')
+            return filePath;
+        const repoPath = args.repoPath;
+        const explicitDbPath = args.dbPath;
+        // Lazily require spec modules so the MCP startup path stays lean.
+        const { resolveDbPath } = require('../spec/utils');
+        const { createDatabase } = require('../db/sqlite-adapter');
+        const { findSpecsByFilePath } = require('../spec/graph/queries');
+        // Resolve the database path.
+        const dbPath = resolveDbPath(repoPath || process.cwd(), explicitDbPath);
+        // Open the database.
+        let db;
+        try {
+            db = createDatabase(dbPath).db;
+        }
+        catch (err) {
+            return this.errorResult(`Failed to open Commit4Spec database at "${dbPath}": ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            const result = findSpecsByFilePath(db, filePath);
+            const response = {
+                filePath,
+                matched_count: result.matched_count,
+                truncated: result.truncated,
+                results: result.results,
+            };
+            const json = JSON.stringify(response, null, 2);
+            if (json.length <= MAX_OUTPUT_LENGTH) {
+                return this.textResult(json);
+            }
+            // Truncate: reduce results
+            const slim = {
+                ...response,
+                results: response.results.slice(0, Math.max(1, Math.floor(response.results.length / 2))),
+            };
+            const slimJson = JSON.stringify(slim, null, 2);
+            if (slimJson.length <= MAX_OUTPUT_LENGTH) {
+                return this.textResult(`(Results trimmed to fit output limit)\n\n${slimJson}`);
+            }
+            return this.textResult(this.truncateOutput(json));
         }
         finally {
             db.close();
         }
     }
     // =========================================================================
+    // handleSpecTrace — code symbol → Spec reverse trace
+    // =========================================================================
+    /**
+     * Trace a code symbol back to its associated Specs.
+     *
+     * Uses the HomeGraph code index to resolve the symbol to AST-level node(s),
+     * then queries the Commit4Spec knowledge graph for associated Specs via
+     * five-dimensional scoring (file-path, content FTS5, name FTS5, recency,
+     * line overlap).
+     *
+     * This bridges the two databases: homegraph.db (code entities) →
+     * commit4spec.db (Spec knowledge graph).
+     */
+    async handleSpecTrace(args) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const fileRaw = this.validateOptionalPath(args.file, 'file');
+        if (typeof fileRaw === 'object')
+            return fileRaw;
+        const file = fileRaw;
+        const line = typeof args.line === 'number' ? args.line : undefined;
+        const repoPath = args.repoPath;
+        const explicitDbPath = args.dbPath;
+        const topKRaw = Number(args.topK);
+        const topK = Math.max(1, Math.min(isNaN(topKRaw) ? 10 : topKRaw, 50));
+        // Lazily require all needed modules
+        const HomeGraph = loadHomeGraph();
+        const { resolveDbPath } = require('../spec/utils');
+        const { createDatabase } = require('../db/sqlite-adapter');
+        const { findSpecsByCodeSymbol } = require('../spec/graph/queries');
+        const { initSpecSchema, runSpecMigrations, getCurrentSpecVersion, CURRENT_SPEC_SCHEMA_VERSION } = require('../spec/db/schema');
+        // Resolve project path for the code graph
+        const projectPath = repoPath || process.cwd();
+        // Open the HomeGraph code index
+        let cg;
+        try {
+            cg = await HomeGraph.open(projectPath);
+        }
+        catch (err) {
+            return this.errorResult(`Failed to open HomeGraph code index at "${projectPath}": ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            // Step 1: Resolve symbol to nodes via findSymbolMatches
+            let nodes = this.findSymbolMatches(cg, symbol);
+            if (nodes.length === 0) {
+                await cg.close();
+                return this.textResult(JSON.stringify({
+                    symbol,
+                    error: `No code entities found for symbol "${symbol}".`,
+                    matches: [],
+                }, null, 2));
+            }
+            // Disambiguate by file/line if provided
+            if (file) {
+                // Use endsWith for precise file path matching
+                nodes = nodes.filter((n) => n.filePath.endsWith(file));
+            }
+            if (line !== undefined && nodes.length > 1) {
+                const closest = nodes.reduce((best, n) => {
+                    const bestDist = Math.abs(best.startLine - line) + Math.abs(best.endLine - line);
+                    const curDist = Math.abs(n.startLine - line) + Math.abs(n.endLine - line);
+                    return curDist < bestDist ? n : best;
+                });
+                nodes = [closest];
+            }
+            // Take the best disambiguated node
+            const node = nodes[0];
+            if (!node) {
+                await cg.close();
+                return this.textResult(JSON.stringify({
+                    symbol,
+                    error: `Could not resolve symbol "${symbol}" to a specific code entity.`,
+                    matches: [],
+                }, null, 2));
+            }
+            // Step 2: Resolve the Spec database path
+            const dbPath = resolveDbPath(repoPath || process.cwd(), explicitDbPath);
+            // Step 3: Open the Spec database
+            let db;
+            try {
+                db = createDatabase(dbPath).db;
+            }
+            catch (err) {
+                await cg.close();
+                return this.errorResult(`Failed to open Commit4Spec database at "${dbPath}": ` +
+                    `${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                // Ensure schema is up to date
+                initSpecSchema(db);
+                const currentVersion = getCurrentSpecVersion(db);
+                if (currentVersion < CURRENT_SPEC_SCHEMA_VERSION) {
+                    runSpecMigrations(db, currentVersion);
+                }
+                // Step 4: Query Specs for the code entity
+                const result = findSpecsByCodeSymbol(db, {
+                    name: node.name,
+                    qualifiedName: node.qualifiedName,
+                    kind: node.kind,
+                    filePath: node.filePath,
+                    startLine: node.startLine,
+                    endLine: node.endLine,
+                }, topK);
+                // Step 5: Serialize the response
+                const response = {
+                    symbol,
+                    entity: {
+                        name: result.entity.name,
+                        qualifiedName: result.entity.qualifiedName,
+                        kind: result.entity.kind,
+                        filePath: result.entity.filePath,
+                        startLine: result.entity.startLine,
+                        endLine: result.entity.endLine,
+                    },
+                    matched_count: result.matches.length,
+                    total_candidates: result.totalCandidates,
+                    matches: result.matches.map((m) => ({
+                        spec_id: m.spec.id,
+                        title: m.spec.title,
+                        status: m.spec.status,
+                        version: m.spec.version,
+                        file_path: m.spec.filePath,
+                        score: Math.round(m.score * 1000) / 1000,
+                        score_detail: {
+                            file_path: Math.round(m.scoreDetail.filePathScore * 1000) / 1000,
+                            content: Math.round(m.scoreDetail.contentScore * 1000) / 1000,
+                            name: Math.round(m.scoreDetail.nameScore * 1000) / 1000,
+                            recency: Math.round(m.scoreDetail.recencyScore * 1000) / 1000,
+                            line_overlap: Math.round(m.scoreDetail.overlapScore * 1000) / 1000,
+                        },
+                        fragment_count: m.fragmentCount,
+                        commit_count: m.commitCount,
+                    })),
+                };
+                const json = JSON.stringify(response, null, 2);
+                if (json.length <= MAX_OUTPUT_LENGTH) {
+                    return this.textResult(json);
+                }
+                // Truncate: reduce matches
+                const slim = {
+                    ...response,
+                    matches: response.matches.slice(0, Math.max(1, Math.floor(topK / 2))),
+                };
+                const slimJson = JSON.stringify(slim, null, 2);
+                if (slimJson.length <= MAX_OUTPUT_LENGTH) {
+                    return this.textResult(`(Results trimmed to fit output limit)\n\n${slimJson}`);
+                }
+                return this.textResult(this.truncateOutput(json));
+            }
+            finally {
+                try {
+                    db.close();
+                }
+                catch { /* best effort */ }
+            }
+        }
+        finally {
+            try {
+                await cg.close();
+            }
+            catch { /* best effort */ }
+        }
+    }
+    // =========================================================================
     // Symbol resolution helpers
     // =========================================================================
     /**
@@ -4108,25 +6921,47 @@ class ToolHandler {
             if (tail && tail !== symbol)
                 results = cg.searchNodes(tail, { limit: 50 });
         }
-        if (results.length === 0) {
+        const exactMatches = results.filter(r => this.matchesSymbol(r.node, symbol));
+        // Prefer exact name/qualified matches. Never fall back to the top FTS
+        // hit — that resolved unrelated symbols (e.g. OnSurfaceChangedCB → a
+        // function whose body merely mentions "surface") and poisoned callees.
+        let pool = exactMatches.map((r) => r.node);
+        if (pool.length === 0) {
+            try {
+                pool = cg.getNodesByName(symbol).filter((n) => this.matchesSymbol(n, symbol));
+            }
+            catch {
+                pool = [];
+            }
+        }
+        if (pool.length === 0 && /[.\/]|::/.test(symbol)) {
+            const tail = lastQualifierPart(symbol);
+            if (tail && tail !== symbol) {
+                try {
+                    pool = cg.getNodesByName(tail).filter((n) => this.matchesSymbol(n, symbol) || this.matchesSymbol(n, tail));
+                }
+                catch {
+                    pool = [];
+                }
+            }
+        }
+        if (pool.length === 0) {
             return { nodes: [], note: '' };
         }
-        const exactMatches = results.filter(r => this.matchesSymbol(r.node, symbol));
-        if (exactMatches.length <= 1) {
-            const node = exactMatches[0]?.node ?? results[0].node;
-            return { nodes: [node], note: '' };
+        if (pool.length === 1) {
+            return { nodes: pool, note: '' };
         }
         // Same generated-file down-rank as findSymbol — keeps callers/callees
         // /impact aggregation aligned (a query against "Send" returns the
         // hand-written implementations before the protobuf scaffold).
-        const ranked = [...exactMatches].sort((a, b) => {
-            const aGen = (0, generated_detection_1.isGeneratedFile)(a.node.filePath) ? 1 : 0;
-            const bGen = (0, generated_detection_1.isGeneratedFile)(b.node.filePath) ? 1 : 0;
+        const ranked = [...pool].sort((a, b) => {
+            const aGen = (0, generated_detection_1.isGeneratedFile)(a.filePath) ? 1 : 0;
+            const bGen = (0, generated_detection_1.isGeneratedFile)(b.filePath) ? 1 : 0;
             return aGen - bGen;
         });
-        const locations = ranked.map(r => `${r.node.kind} at ${r.node.filePath}:${r.node.startLine}`);
+        const locations = ranked.map(n => `${n.kind} at ${n.filePath}:${n.startLine}`);
         const note = `\n\n> **Note:** Aggregated results across ${ranked.length} symbols named "${symbol}": ${locations.join(', ')}`;
-        return { nodes: ranked.map(r => r.node), note };
+        return { nodes: ranked, note };
     }
     /**
      * Truncate output if it exceeds the maximum length
@@ -4151,7 +6986,7 @@ class ToolHandler {
             lines.push(`**${node.name}** (${node.kind})`);
             lines.push(`${node.filePath}${location}`);
             if (node.signature)
-                lines.push(`\`${node.signature}\``);
+                lines.push(`\`${formatInlineSignature(node.signature)}\``);
             lines.push('');
         }
         return lines.join('\n');
@@ -4225,7 +7060,7 @@ class ToolHandler {
         const lines = [`**Members (${children.length}):**`, ''];
         for (const c of children) {
             const loc = c.startLine ? `:${c.startLine}` : '';
-            const sig = c.signature ? ` — \`${c.signature}\`` : '';
+            const sig = c.signature ? ` — \`${formatInlineSignature(c.signature)}\`` : '';
             lines.push(`- ${c.name} (${c.kind})${loc}${sig}`);
         }
         return lines.join('\n');
@@ -4238,7 +7073,7 @@ class ToolHandler {
             `**Location:** ${node.filePath}${location}`,
         ];
         if (node.signature) {
-            lines.push(`**Signature:** \`${node.signature}\``);
+            lines.push(...formatNodeSignatureBlock(node.signature));
         }
         // Only include docstring if it's short and useful
         if (node.docstring && node.docstring.length < 200) {