homegraph 1.2.0 → 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
@@ -96,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,
@@ -211,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>`).
@@ -329,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
@@ -409,7 +480,7 @@ const READ_ONLY_ANNOTATIONS = {
 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: {
@@ -435,7 +506,7 @@ exports.tools = [
     },
     {
         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: {
@@ -460,7 +531,7 @@ exports.tools = [
     },
     {
         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: {
@@ -485,7 +556,7 @@ exports.tools = [
     },
     {
         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: {
@@ -510,7 +581,7 @@ exports.tools = [
     },
     {
         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: {
@@ -552,13 +623,13 @@ exports.tools = [
     },
     {
         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',
@@ -584,7 +655,7 @@ exports.tools = [
     },
     {
         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: {
@@ -1064,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');
             }
@@ -1270,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) {
@@ -1299,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)) {
@@ -1328,11 +1416,13 @@ class ToolHandler {
             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();
-                    (0, query_cache_1.ensureMcpQueryCacheValid)(cacheQueries, () => cacheCg.getLastIndexedAt());
+                    cacheIndex = (0, query_cache_1.getMcpQueryCacheIndex)(cacheCg.getProjectRoot());
+                    cacheIndex.ensureValid(cacheQueries, () => cacheCg.getLastIndexedAt());
                     let fileCount;
                     try {
                         fileCount = cacheCg.getStats().fileCount;
@@ -1341,7 +1431,7 @@ class ToolHandler {
                         fileCount = undefined;
                     }
                     cacheKey = (0, query_cache_1.buildMcpQueryCacheKey)(toolName, args, fileCount);
-                    const cached = (0, query_cache_1.getMcpQueryCacheEntry)(cacheQueries, cacheKey);
+                    const cached = cacheIndex.getEntry(cacheQueries, cacheKey);
                     if (cached) {
                         const withWorktree = this.withWorktreeNotice(cached, projectPath);
                         return this.withStalenessNotice(withWorktree, projectPath);
@@ -1359,20 +1449,43 @@ class ToolHandler {
             if (toolName === 'homegraph_status') {
                 return await this.handleStatus(args);
             }
-            // Read tools: off-load the CPU-heavy dispatch to the worker pool when one
-            // is attached and healthy (daemon mode), so the daemon's single event loop
-            // stays free for the MCP transport under concurrent load — otherwise N
-            // concurrent explores serialize AND starve the transport until the whole
-            // batch drains (clients then time out). With no pool (direct mode) or a
-            // degraded one, dispatch runs in-process exactly as before. Either way the
-            // result flows through the cross-cutting notices — worktree-index mismatch
-            // (#155) and per-file staleness (#403) — which need the watched MAIN
-            // instance and so are always applied here, never in the worker.
-            const result = (this.queryPool && this.queryPool.healthy)
-                ? await this.queryPool.run(toolName, args)
-                : await this.executeReadTool(toolName, args);
-            if (cacheEnabled && cacheKey && cacheQueries && !result.isError) {
-                (0, query_cache_1.setMcpQueryCacheEntry)(cacheQueries, cacheKey, toolName, result);
+            // 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, projectPath);
             return this.withStalenessNotice(withWorktree, projectPath);
@@ -1393,6 +1506,64 @@ class ToolHandler {
                 'continue without homegraph for this task.');
         }
     }
+    /**
+     * 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
@@ -1408,6 +1579,12 @@ class ToolHandler {
      */
     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) {
@@ -1443,14 +1620,31 @@ class ToolHandler {
             default: return this.errorResult(`Unknown tool: ${toolName}`);
         }
     }
-    /**
-     * Handle homegraph_search
-     */
     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
@@ -1474,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
@@ -1536,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);
@@ -1544,6 +1742,8 @@ class ToolHandler {
                         if (label)
                             labels.set(c.node.id, label);
                     }
+                    if (callers.length >= limit)
+                        return { callers, labels };
                 }
             }
             return { callers, labels };
@@ -1557,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
@@ -1579,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
@@ -1603,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)) {
@@ -1614,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]);
@@ -2275,130 +2486,1704 @@ class ToolHandler {
                     supers.set(s.id, e);
                 }
             }
-            // Pick the supertype with the most TRUE implementers (graph-wide), among
-            // those genuinely shared by the token's definers.
-            let best = null;
-            for (const { node, count, targets } of supers.values()) {
-                if (count < MIN_SUPPORT)
+            // Pick the supertype with the most TRUE implementers (graph-wide), among
+            // those genuinely shared by the token's definers.
+            let best = null;
+            for (const { node, count, targets } of supers.values()) {
+                if (count < MIN_SUPPORT)
+                    continue;
+                let impl = 0;
+                try {
+                    impl = cg.getIncomingEdges(node.id).filter((e) => e.kind === 'implements' || e.kind === 'extends').length;
+                }
+                catch { /* leave 0 — gated out below */ }
+                if (impl < MIN_IMPL)
+                    continue;
+                if (!best || impl > best.impl)
+                    best = { node, impl, targets };
+            }
+            if (!best || seenSuper.has(best.node.id))
+                continue;
+            seenSuper.add(best.node.id);
+            const namedNames = new Set([...named.values()].map((n) => n.name));
+            const eg = best.targets.slice(0, 4).map((m) => {
+                const cont = containerOf(m);
+                const disp = cont ? `${cont.name}.${m.name}` : (m.qualifiedName || m.name);
+                const mark = cont && namedNames.has(cont.name) ? ' ← you named this' : '';
+                return `\`${disp}\` (${rel(m.filePath)}:${m.startLine})${mark}`;
+            });
+            const more = best.impl > eg.length ? ` +${best.impl - eg.length} more` : '';
+            notes.push(`- \`${token}\` → runtime dispatch to **${best.impl}** types implementing \`${best.node.name}\` — the static path ends here, the target is chosen at runtime. e.g. ${eg.join(', ')}${more}`);
+        }
+        if (notes.length === 0)
+            return '';
+        return [
+            '**Interface dispatch (a named method has many implementations)**',
+            '',
+            ...notes,
+            '',
+            '> The method above is dispatched at runtime to one of the listed implementations (a registry / plugin / strategy interface) — there is no single static caller→callee edge; the implementations ARE the continuations. To follow one, run homegraph_explore on a listed target.',
+            '',
+        ].join('\n');
+    }
+    /**
+     * Shortlist candidate runtime targets for a dispatch key surfaced by
+     * {@link buildDynamicBoundaries}. Exact conventional names first (`save` →
+     * `onSave`/`handleSave`; `CreateCmd` → `CreateCmdHandler`), then FTS, with a
+     * normalized-containment post-filter (FTS camel-splitting is fuzzier than a
+     * candidate list should be). Symbols the agent already named sort first and
+     * are marked — that's the "you were right, here's the wiring" case.
+     */
+    boundaryCandidates(cg, key, keyIsType, named, selfId) {
+        const CALLABLE = new Set(['method', 'function', 'component', 'constructor', 'class']);
+        const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+        const keyNorm = norm(key);
+        if (keyNorm.length < 3)
+            return '';
+        const cands = new Map();
+        const consider = (n) => {
+            if (!n || n.id === selfId || !CALLABLE.has(n.kind) || cands.has(n.id))
+                return;
+            const nameNorm = norm(n.name || '');
+            if (nameNorm.length < 3)
+                return;
+            if (!nameNorm.includes(keyNorm) && !keyNorm.includes(nameNorm))
+                return;
+            cands.set(n.id, n);
+        };
+        const cap = key.charAt(0).toUpperCase() + key.slice(1);
+        const probes = keyIsType
+            ? [`${key}Handler`, key]
+            : [key, `on${cap}`, `handle${cap}`, `${key}Handler`, `handle_${key}`];
+        for (const p of probes) {
+            try {
+                for (const n of cg.getNodesByName(p))
+                    consider(n);
+            }
+            catch { /* exact probe miss is fine */ }
+        }
+        let raw = 0;
+        try {
+            const results = cg.searchNodes(key, { limit: 12 });
+            raw = results.length;
+            for (const r of results)
+                consider(r.node);
+        }
+        catch { /* FTS syntax edge — exact probes already ran */ }
+        if (cands.size === 0) {
+            return raw >= 12 && key.length < 5 ? `key \`${key}\` is too generic to shortlist (${raw}+ matches)` : '';
+        }
+        // A constructor candidate duplicates its class: extractors emit ctors as
+        // METHOD nodes named like the class (C#/Java `Foo::Foo`) — keep the class.
+        const all = [...cands.values()];
+        const classKey = new Set(all.filter((n) => n.kind === 'class').map((n) => `${n.name}|${n.filePath}`));
+        const namedNames = new Set([...named.values()].map((n) => n.name));
+        const isNamed = (n) => named.has(n.id) || namedNames.has(n.name); // the flow's named set holds callables only — transfer the mark to the class
+        const list = all
+            .filter((n) => !(n.kind !== 'class' && classKey.has(`${n.name}|${n.filePath}`)))
+            .sort((a, b) => (isNamed(b) ? 1 : 0) - (isNamed(a) ? 1 : 0))
+            .slice(0, 4)
+            .map((n) => {
+            // Typed-bus convention: the runtime target is the candidate class's
+            // Handle/Execute/Consume method — name the exact node, not just the class.
+            let display = n.qualifiedName || n.name;
+            let at = `${n.filePath}:${n.startLine}`;
+            if (keyIsType && n.kind === 'class') {
+                try {
+                    const HANDLER_METHODS = /^(handle|handleAsync|execute|executeAsync|consume|consumeAsync|run|__invoke)$/i;
+                    const method = cg.getOutgoingEdges(n.id)
+                        .filter((e) => e.kind === 'contains')
+                        .map((e) => { try {
+                        return cg.getNode(e.target);
+                    }
+                    catch {
+                        return null;
+                    } })
+                        .find((c) => !!c && c.kind === 'method' && HANDLER_METHODS.test(c.name));
+                    if (method) {
+                        display = `${n.name}.${method.name}`;
+                        at = `${method.filePath}:${method.startLine}`;
+                    }
+                }
+                catch { /* class without resolvable members — show the class itself */ }
+            }
+            return `\`${display}\` (${at})${isNamed(n) ? ' ← you named this' : ''}`;
+        });
+        return `candidates for key \`${key}\`: ${list.join(', ')}`;
+    }
+    /**
+     * 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.
+     */
+    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 {
+                hits = cg.searchNodes(sym, { kinds: ['import'], limit: importLimit });
+            }
+            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 (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 };
+    }
+    /**
+     * 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;
-                let impl = 0;
+                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 {
-                    impl = cg.getIncomingEdges(node.id).filter((e) => e.kind === 'implements' || e.kind === 'extends').length;
+                    content = (0, fs_1.readFileSync)(abs, 'utf-8');
                 }
-                catch { /* leave 0 — gated out below */ }
-                if (impl < MIN_IMPL)
+                catch {
                     continue;
-                if (!best || impl > best.impl)
-                    best = { node, impl, targets };
+                }
+                const fileLines = content.split('\n');
+                for (let i = 0; i < fileLines.length; i++) {
+                    if (wordRe.test(fileLines[i] ?? ''))
+                        addHit(fp, i + 1);
+                }
             }
-            if (!best || seenSuper.has(best.node.id))
-                continue;
-            seenSuper.add(best.node.id);
-            const namedNames = new Set([...named.values()].map((n) => n.name));
-            const eg = best.targets.slice(0, 4).map((m) => {
-                const cont = containerOf(m);
-                const disp = cont ? `${cont.name}.${m.name}` : (m.qualifiedName || m.name);
-                const mark = cont && namedNames.has(cont.name) ? ' ← you named this' : '';
-                return `\`${disp}\` (${rel(m.filePath)}:${m.startLine})${mark}`;
-            });
-            const more = best.impl > eg.length ? ` +${best.impl - eg.length} more` : '';
-            notes.push(`- \`${token}\` → runtime dispatch to **${best.impl}** types implementing \`${best.node.name}\` — the static path ends here, the target is chosen at runtime. e.g. ${eg.join(', ')}${more}`);
         }
-        if (notes.length === 0)
-            return '';
-        return [
-            '**Interface dispatch (a named method has many implementations)**',
-            '',
-            ...notes,
+        if (hits.size === 0)
+            return { section: '', fileCount: 0 };
+        const lines = [
+            '**API usage sites**',
             '',
-            '> The method above is dispatched at runtime to one of the listed implementations (a registry / plugin / strategy interface) — there is no single static caller→callee edge; the implementations ARE the continuations. To follow one, run homegraph_explore on a listed target.',
+            `> Files referencing \`${symbols.join('`, `')}\` in this repo (${hits.size} file(s)). Answer from this list; source bodies omitted.`,
             '',
-        ].join('\n');
+        ];
+        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 };
     }
     /**
-     * Shortlist candidate runtime targets for a dispatch key surfaced by
-     * {@link buildDynamicBoundaries}. Exact conventional names first (`save` →
-     * `onSave`/`handleSave`; `CreateCmd` → `CreateCmdHandler`), then FTS, with a
-     * normalized-containment post-filter (FTS camel-splitting is fuzzier than a
-     * candidate list should be). Symbols the agent already named sort first and
-     * are marked — that's the "you were right, here's the wiring" case.
+     * Domain file inventory — related files, usage existence, or concept comparison.
+     * Paths + top symbols only; source bodies omitted when this section renders.
      */
-    boundaryCandidates(cg, key, keyIsType, named, selfId) {
-        const CALLABLE = new Set(['method', 'function', 'component', 'constructor', 'class']);
-        const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
-        const keyNorm = norm(key);
-        if (keyNorm.length < 3)
-            return '';
-        const cands = new Map();
-        const consider = (n) => {
-            if (!n || n.id === selfId || !CALLABLE.has(n.kind) || cands.has(n.id))
-                return;
-            const nameNorm = norm(n.name || '');
-            if (nameNorm.length < 3)
-                return;
-            if (!nameNorm.includes(keyNorm) && !keyNorm.includes(nameNorm))
+    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;
-            cands.set(n.id, n);
+            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);
         };
-        const cap = key.charAt(0).toUpperCase() + key.slice(1);
-        const probes = keyIsType
-            ? [`${key}Handler`, key]
-            : [key, `on${cap}`, `handle${cap}`, `${key}Handler`, `handle_${key}`];
-        for (const p of probes) {
+        for (const term of terms) {
+            let hits = [];
             try {
-                for (const n of cg.getNodesByName(p))
-                    consider(n);
+                hits = cg.searchNodes(term, { limit: 45 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                addFile(r.node.filePath, (r.score ?? 1) + 2, r.node.name);
             }
-            catch { /* exact probe miss is fine */ }
         }
-        let raw = 0;
         try {
-            const results = cg.searchNodes(key, { limit: 12 });
-            raw = results.length;
-            for (const r of results)
-                consider(r.node);
+            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 { /* FTS syntax edge — exact probes already ran */ }
-        if (cands.size === 0) {
-            return raw >= 12 && key.length < 5 ? `key \`${key}\` is too generic to shortlist (${raw}+ matches)` : '';
+        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}`);
         }
-        // A constructor candidate duplicates its class: extractors emit ctors as
-        // METHOD nodes named like the class (C#/Java `Foo::Foo`) — keep the class.
-        const all = [...cands.values()];
-        const classKey = new Set(all.filter((n) => n.kind === 'class').map((n) => `${n.name}|${n.filePath}`));
-        const namedNames = new Set([...named.values()].map((n) => n.name));
-        const isNamed = (n) => named.has(n.id) || namedNames.has(n.name); // the flow's named set holds callables only — transfer the mark to the class
-        const list = all
-            .filter((n) => !(n.kind !== 'class' && classKey.has(`${n.name}|${n.filePath}`)))
-            .sort((a, b) => (isNamed(b) ? 1 : 0) - (isNamed(a) ? 1 : 0))
-            .slice(0, 4)
-            .map((n) => {
-            // Typed-bus convention: the runtime target is the candidate class's
-            // Handle/Execute/Consume method — name the exact node, not just the class.
-            let display = n.qualifiedName || n.name;
-            let at = `${n.filePath}:${n.startLine}`;
-            if (keyIsType && n.kind === 'class') {
+        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 {
-                    const HANDLER_METHODS = /^(handle|handleAsync|execute|executeAsync|consume|consumeAsync|run|__invoke)$/i;
-                    const method = cg.getOutgoingEdges(n.id)
-                        .filter((e) => e.kind === 'contains')
-                        .map((e) => { try {
-                        return cg.getNode(e.target);
-                    }
-                    catch {
-                        return null;
-                    } })
-                        .find((c) => !!c && c.kind === 'method' && HANDLER_METHODS.test(c.name));
-                    if (method) {
-                        display = `${n.name}.${method.name}`;
-                        at = `${method.filePath}:${method.startLine}`;
-                    }
+                    content = (0, fs_1.readFileSync)(abs, 'utf-8');
                 }
-                catch { /* class without resolvable members — show the class itself */ }
+                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('');
             }
-            return `\`${display}\` (${at})${isNamed(n) ? ' ← you named this' : ''}`;
-        });
-        return `candidates for key \`${key}\`: ${list.join(', ')}`;
+        }
+        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
@@ -2553,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;
@@ -2568,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
@@ -2639,6 +4486,13 @@ class ToolHandler {
         {
             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 callerCount = (n) => { try {
@@ -2647,9 +4501,28 @@ class ToolHandler {
             catch {
                 return 0;
             } };
-            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 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 /
@@ -2673,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
@@ -2713,6 +4593,68 @@ class ToolHandler {
                 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
         const fileGroups = new Map();
@@ -2797,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
@@ -2974,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;
@@ -3029,16 +4986,154 @@ class ToolHandler {
             '',
         ];
         const summaryLineIdx = 2;
-        // 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
+        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
@@ -3066,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 —
@@ -3126,7 +5218,9 @@ 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;
@@ -3134,8 +5228,51 @@ class ToolHandler {
         // (#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
@@ -3431,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;
@@ -3713,11 +5883,17 @@ 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;
-            finalText = 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.)';
         }
         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
@@ -3807,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;
@@ -3948,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}`);
@@ -3976,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'));
     }
@@ -4744,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