homegraph 1.5.2 → 1.5.3

package/dist/mcp/tools.js

@@ -5,7 +5,8 @@
  * Defines the tools exposed by the HomeGraph MCP server.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolHandler = exports.tools = exports.PathRefusalError = exports.NotIndexedError = void 0;
+exports.ToolHandler = exports.tools = exports.PathRefusalError = exports.GraphSourcesDisabledError = exports.NotIndexedError = void 0;
+exports.__setLoadHomeGraphForTests = __setLoadHomeGraphForTests;
 exports.normalizeQuerySpelling = normalizeQuerySpelling;
 exports.getExploreBudget = getExploreBudget;
 exports.getExploreOutputBudget = getExploreOutputBudget;
@@ -22,13 +23,26 @@ const directory_1 = require("../directory");
 // schemas), but it must NOT drag in sqlite/query layers before the daemon binds;
 // HomeGraph is pulled in only when a tool actually opens a project. require() is
 // sync + cached (CommonJS build).
-const loadHomeGraph = () => require('../index').default;
+const loadHomeGraph = () => loadHomeGraphForTests ?? require('../index').default;
+// Test seam (same pattern as the watcher's `__setFsWatchForTests`): vitest's
+// module transform can't service the lazy `require('../index')` above, so
+// in-process tests that exercise a genuine cross-project open (an explicit
+// `projectPath` to a different project — issue #1474's repro shape) inject the
+// already-imported class here. Never set outside tests.
+let loadHomeGraphForTests = null;
+function __setLoadHomeGraphForTests(cls) {
+    loadHomeGraphForTests = cls;
+}
 const worktree_1 = require("../sync/worktree");
+const graph_sources_1 = require("../graph-sources");
 const query_utils_1 = require("../search/query-utils");
 const fs_1 = require("fs");
+const crypto_1 = require("crypto");
 const utils_1 = require("../utils");
 const generated_detection_1 = require("../extraction/generated-detection");
 const arkts_1 = require("../extraction/languages/arkts");
+const explore_session_state_1 = require("./explore-session-state");
+const explore_dedup_1 = require("./explore-dedup");
 const dynamic_boundaries_1 = require("./dynamic-boundaries");
 const query_cache_1 = require("./query-cache");
 const diff_impact_1 = require("./diff-impact");
@@ -56,6 +70,10 @@ const sqlite_adapter_1 = require("../db/sqlite-adapter");
 class NotIndexedError extends Error {
 }
 exports.NotIndexedError = NotIndexedError;
+/** `HOMEGRAPH_SOURCES=none` (or equivalent) — success-shaped, not isError. */
+class GraphSourcesDisabledError extends Error {
+}
+exports.GraphSourcesDisabledError = GraphSourcesDisabledError;
 /**
  * A security refusal (sensitive system path). Stays `isError: true` WITHOUT
  * retry guidance — abandoning this path is the desired agent reaction.
@@ -114,6 +132,114 @@ function lastQualifierPart(symbol) {
     const parts = symbol.split(/::|[./]/).filter((p) => p.length > 0);
     return parts[parts.length - 1] ?? symbol;
 }
+/**
+ * Page/Dialog surface digests — methods that answer "which UI children / how
+ * does preview load" without dumping the whole struct. Lifecycle alone is not
+ * enough: agents re-Read for PageMap / preview helpers when those are trimmed.
+ */
+function isUiSurfaceDigestMethod(name, includePreviewHelpers) {
+    if (/^(build|aboutToAppear|aboutToDisappear|PageMap)$/i.test(name))
+        return true;
+    if (!includePreviewHelpers)
+        return false;
+    return /preview|pixelmap|loadimage|getimage|decodeimage/i.test(name);
+}
+/** Prefer build/PageMap/preview over aboutToAppear when budget is tight. */
+function surfaceMethodPriority(name) {
+    if (/^(build|PageMap)$/i.test(name))
+        return 0;
+    if (/preview|pixelmap|loadimage|getimage/i.test(name))
+        return 1;
+    return 2;
+}
+/**
+ * Structured UI/nav bullets extracted from surface method bodies so agents can
+ * ANSWER NOW without re-Reading for child Types / PageMap routes.
+ */
+function extractUiSurfaceInventory(fileLines, methods) {
+    const FRAMEWORK_TAG = new Set([
+        'Column', 'Row', 'Stack', 'Flex', 'Grid', 'List', 'ListItem', 'Scroll', 'Tabs', 'TabContent',
+        'Text', 'Image', 'Button', 'Blank', 'Divider', 'ForEach', 'LazyForEach', 'If', 'Else',
+        'RelativeContainer', 'Swiper', 'WaterFlow', 'GridItem', 'Span', 'SymbolGlyph',
+    ]);
+    const comps = new Set();
+    const nav = new Set();
+    const media = [];
+    for (const m of methods) {
+        const from = Math.max(1, m.startLine);
+        const to = Math.min(fileLines.length, Math.max(m.endLine, m.startLine));
+        for (let i = from; i <= to; i++) {
+            const line = fileLines[i - 1] ?? '';
+            for (const mm of line.matchAll(/\b([A-Z][A-Za-z0-9_]{2,})\s*\(/g)) {
+                const id = mm[1];
+                if (FRAMEWORK_TAG.has(id) || (0, query_utils_1.isFrameworkUiDecoratorName)(id))
+                    continue;
+                if (/^(Promise|Array|Map|Set|Date|Error|JSON|Object|Math|Number|String|Boolean)$/.test(id))
+                    continue;
+                comps.add(id);
+            }
+            if (/PageMap|pushUrl|replaceUrl|pushPath|replacePath|router\./i.test(line)) {
+                const clipped = line.trim().replace(/\s+/g, ' ').slice(0, 120);
+                if (clipped)
+                    nav.add(clipped);
+            }
+            for (const mm of line.matchAll(/\bConstants\.[A-Z][A-Z0-9_]+\b/g)) {
+                nav.add(mm[0]);
+            }
+            // Preview / Image load origin — $r vs file URI vs network.
+            if (/\$r\s*\(|Image\s*\(|PixelMap|createPixelMap|decode|tempFileUri|http|download|fileUri|getPreview|previewPixelMap|loadImage/i.test(line)) {
+                const clipped = line.trim().replace(/\s+/g, ' ').slice(0, 140);
+                if (clipped && media.length < 14) {
+                    media.push(`L${i} (\`${m.name}\`): \`${clipped}\``);
+                }
+            }
+        }
+    }
+    if (comps.size === 0 && nav.size === 0 && media.length === 0)
+        return '';
+    const out = ['**UI surface inventory (from build / PageMap / preview methods)**', ''];
+    if (comps.size > 0) {
+        out.push('UI / child Types:');
+        for (const c of [...comps].sort().slice(0, 24))
+            out.push(`- \`${c}\``);
+        if (comps.size > 24)
+            out.push(`- … and ${comps.size - 24} more`);
+        out.push('');
+    }
+    if (nav.size > 0) {
+        out.push('Navigation / PageMap / route constants:');
+        for (const n of [...nav].slice(0, 16))
+            out.push(`- ${n.startsWith('Constants.') ? `\`${n}\`` : n}`);
+        if (nav.size > 16)
+            out.push(`- … and ${nav.size - 16} more`);
+        out.push('');
+    }
+    if (media.length > 0) {
+        out.push('Image / preview load sites ($r / file / network cues):');
+        for (const row of media)
+            out.push(`- ${row}`);
+        out.push('');
+    }
+    out.push('> **ANSWER NOW** from this inventory + method digests below — do not Read/Grep for the same Page UI children, routes, or preview-load origin.');
+    out.push('');
+    return out.join('\n');
+}
+/** C++ `class Foo : public Bar` vs private `: Bar` — prefer public is-a for subtype lists. */
+function cppExtendsLooksPublic(declLine, baseName) {
+    const esc = baseName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (new RegExp(`:\\s*public\\s+(?:virtual\\s+)?${esc}\\b`).test(declLine))
+        return true;
+    if (new RegExp(`:\\s*protected\\s+(?:virtual\\s+)?${esc}\\b`).test(declLine))
+        return false;
+    if (new RegExp(`:\\s*private\\s+(?:virtual\\s+)?${esc}\\b`).test(declLine))
+        return false;
+    // `class Cluster : Rectangle` (no access) defaults to private for class.
+    if (new RegExp(`:\\s*${esc}\\b`).test(declLine) && /\bclass\b/.test(declLine))
+        return false;
+    if (new RegExp(`:\\s*${esc}\\b`).test(declLine) && /\bstruct\b/.test(declLine))
+        return true;
+    return null;
+}
 /**
  * Normalize Erlang-native symbol spellings in an explore query into the shapes
  * the rest of the pipeline already understands. Agents working Erlang code
@@ -252,11 +378,24 @@ function getExploreOutputBudget(fileCount) {
  * 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.
+ *
+ * Mechanism / cross-module flows also get a tighter ceiling: full 24K + a
+ * second explore/node/Read stack is what blows session tokens on "how is X
+ * implemented" questions even when the first answer was already enough.
  */
 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;
+        return {
+            ...budget,
+            maxOutputChars: Math.min(budget.maxOutputChars, 12000),
+            defaultMaxFiles: Math.min(budget.defaultMaxFiles, 4),
+            maxCharsPerFile: Math.min(budget.maxCharsPerFile, 4500),
+            includeRelationships: false,
+            includeAdditionalFiles: false,
+            includeCompletenessSignal: false,
+            includeBudgetNote: false,
+        };
     }
     const local = (0, query_utils_1.queryAsLocalSymbolDetail)(query);
     const compact = (0, query_utils_1.shouldUseCompactExploreBudget)(query);
@@ -277,11 +416,14 @@ function tightenExploreBudgetForQuery(budget, query, opts) {
     }
     if (!local && !compact)
         return budget;
+    const lean = (0, query_utils_1.queryAsAssignedFlagImpactSurvey)(query)
+        || (0, query_utils_1.queryAsFocusedUiCluster)(query)
+        || (0, query_utils_1.queryAsTypeLifecycleSurvey)(query);
     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),
+        maxOutputChars: Math.min(budget.maxOutputChars, lean ? 4800 : local ? 7000 : 9000),
+        defaultMaxFiles: Math.min(budget.defaultMaxFiles, lean ? 2 : local ? 2 : 3),
+        maxCharsPerFile: Math.min(budget.maxCharsPerFile, lean ? 2200 : local ? 3500 : 4000),
         includeRelationships: false,
         includeAdditionalFiles: false,
         includeCompletenessSignal: false,
@@ -485,9 +627,9 @@ const READ_ONLY_ANNOTATIONS = {
 /**
  * All HomeGraph MCP tools
  *
- * Designed for minimal context usage - use homegraph_explore as the primary tool
- * (one call usually answers the whole question), and only use other tools for
- * targeted follow-up queries.
+ * Prefer the smallest tool that answers: callers/node for one named symbol,
+ * explore for multi-file flows. Skip HomeGraph entirely for topic file-lists,
+ * concept compares, SDK catalogs, and literal greps.
  *
  * All tools support cross-project queries via the optional `projectPath` parameter.
  */
@@ -495,7 +637,9 @@ exports.tools = [
     {
         name: 'homegraph_search',
         description: 'LAST RESORT spelling lookup — locations only, no source. Required: `query` (e.g. "signIn"). ' +
-            'Prefer homegraph_explore when the question already names a symbol/file/@kit. ' +
+            'Prefer explore/callers/node when names are known. ' +
+            'DO NOT call for topic file-lists, concept compares, or SDK/@kit feature catalogs (those return Skip guidance). ' +
+            'Also skip literal string/pattern greps — use Grep instead. ' +
             'Bare-name search may return a compact explore result instead of locations.',
         inputSchema: {
             type: 'object',
@@ -523,9 +667,8 @@ exports.tools = [
     {
         name: 'homegraph_callers',
         description: 'Compact caller list for one NAMED in-repo symbol (no bodies). Required: `symbol` (e.g. "authenticate"). ' +
-            '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. ' +
-            'Prefer one explore over parallel callers+callees+node.',
+            'Cheaper than explore when you only need who-calls-X. For multi-file flows use homegraph_explore. ' +
+            'DO NOT call for SDK catalogs, topic file-lists, concept compares, or hypothetics.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -551,8 +694,8 @@ exports.tools = [
     {
         name: 'homegraph_callees',
         description: 'Compact callee list for one NAMED in-repo symbol (no bodies). Required: `symbol` (e.g. "authenticate"). ' +
-            '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.',
+            'Cheaper than explore when you only need what-X-calls. For multi-file flows use homegraph_explore. ' +
+            'DO NOT use for out-of-repo SDK catalogs or counterfactual analysis.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -649,10 +792,11 @@ exports.tools = [
         name: 'homegraph_node',
         description: 'Depth on ONE known in-repo symbol or indexed file — not a survey tool. ' +
             'Required: pass `symbol` (symbol mode) OR `file` alone (file mode). ' +
+            'Cheaper than explore when you already know the name and only need one body. ' +
             'FILE: `file` only → line-numbered source + dependents. ' +
             'SYMBOL: body via includeCode + short trail; overloads return every body. ' +
-            'USE after explore named the symbol and you still need one body. ' +
-            'DO NOT crawl a feature with repeated node calls (prefer one explore). ' +
+            'DO NOT call after explore already returned that symbol/file (multiplies tokens). ' +
+            'DO NOT crawl a feature with repeated node calls (prefer one explore for flows). ' +
             'Treat returned source as already Read.',
         inputSchema: {
             type: 'object',
@@ -696,16 +840,22 @@ exports.tools = [
     },
     {
         name: 'homegraph_explore',
-        description: 'PRIMARY tool for THIS REPO\'s symbol graph (call paths + often line-numbered source). Required: `query` with concrete symbol/file/@kit names. ' +
-            'CALL for in-repo structure: feature wiring, A→B path, callers/callees, Type.member usage, click→handler, in-repo @kit usages. ' +
-            'Skip search when names are already known. One explore; answer from Source + trail; treat as already Read. Busy/partial → retry same explore once.',
+        description: 'In-repo multi-file / mechanism tool (call paths + compact line-numbered source). Required: `query`. ' +
+            'CALL FIRST for how/wired questions — pass the question or domain keywords; PascalCase names optional. ' +
+            'Also CALL FIRST (alone, no parallel Grep) for named Type/Component/Page/Dialog, Type.member, click→handler, inheritance/subtypes, ' +
+            'declaration/attribute sites, ALL_CAPS constant / field-mutex usages, path-module NAPI/exports or inter-deps, ' +
+            'and in-repo @kit/@ohos *usages/dependencies* (which files import a named export — not the SDK feature catalog). ' +
+            'On the first turn call explore alone (no parallel Grep). Prefer callers/node when one named symbol is already enough. ' +
+            'DO NOT call for topic file-lists, concept/UI-behavior with no named anchors, literal copy hunts, or SDK/@kit *feature catalogs* — those return Skip guidance. ' +
+            'Literal string/pattern hunts → Grep. ' +
+            'One explore; answer from Source + trail; treat as already Read — do not re-grep/node/read the same symbols. Busy/partial → retry same explore once.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Required. In-repo symbols, file basenames, or @kit names (e.g. "ParentPage onClick build", "CartRepository.addItem"). ' +
-                        'For flows, name both endpoints. Not for official SDK API catalogs.',
+                    description: 'Required. Prefer the user question or domain keywords for how/mechanism. ' +
+                        'For named flows, include Type / Type.member / component names. For @kit, ask usages (depend/import sites), not SDK catalogs.',
                 },
                 maxFiles: {
                     type: 'number',
@@ -729,6 +879,25 @@ exports.tools = [
         },
         annotations: READ_ONLY_ANNOTATIONS,
     },
+    {
+        name: 'homegraph_arkui_migrate',
+        description: 'ArkUI migrate / state-semantics snapshot in ONE call (components, state decorators + args, ' +
+            'data-passage types, Provide/Consume/Storage key channels, @Observed classes). ' +
+            'Required: `scope`. PRIMARY for ArkUI V1↔V2 migration decisions — do NOT stitch with explore. ' +
+            'Scope: component name, relative .ets path, or directory prefix. Returns JSON (no source bodies).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: {
+                    type: 'string',
+                    description: 'Required. Component name (e.g. "ParentPage"), relative file (e.g. "pages/Index.ets"), or directory prefix.',
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['scope'],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
     {
         name: 'homegraph_files',
         description: 'Indexed directory tree (paths and symbol counts only — NO source). ' +
@@ -1115,6 +1284,10 @@ class ToolHandler {
      * similar to how git finds .git/ directories.
      */
     getHomeGraph(projectPath) {
+        const sourcesMode = (0, graph_sources_1.resolveGraphSources)();
+        if (!(0, graph_sources_1.graphSourceFlags)(sourcesMode).openProjectDb) {
+            throw new GraphSourcesDisabledError((0, graph_sources_1.graphSourcesDisabledGuidance)(sourcesMode));
+        }
         if (!projectPath) {
             if (!this.cg) {
                 const searched = this.defaultProjectHint ?? process.cwd();
@@ -1126,7 +1299,7 @@ class ToolHandler {
                     'explicitly:\n' +
                     '  • Pass projectPath to the tool call, e.g. projectPath: "/absolute/path/to/your/project" ' +
                     '(any project that has a .homegraph/ — including a sub-project of a monorepo)\n' +
-                    '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]\n' +
+                    '  • Or add --path to the server\'s MCP config args: ["serve", "mcp", "--path", "/absolute/path/to/your/project"]\n' +
                     'If a project simply has no index, use your built-in tools (Read/Grep/Glob) for THAT ' +
                     "project (the user can run 'homegraph init' there to enable it) — you can still query " +
                     'other indexed projects by projectPath in the same session.');
@@ -1177,7 +1350,7 @@ class ToolHandler {
         const cached = this.projectCache.get(resolvedRoot);
         if (cached)
             return this.freshen(cached);
-        const cg = loadHomeGraph().openSync(resolvedRoot);
+        const cg = loadHomeGraph().openSync(resolvedRoot, { sources: sourcesMode });
         this.projectCache.set(resolvedRoot, cg);
         return cg;
     }
@@ -1326,6 +1499,46 @@ class ToolHandler {
      * Cost when nothing is pending — the common case — is one boolean check.
      * No I/O, no parsing of markdown beyond a per-pending-file substring scan.
      */
+    driftCache = new Map();
+    static DRIFT_TTL_MS = 2000;
+    /**
+     * On-disk drift check for a single indexed file (issue #1474). The code
+     * renderers slice CURRENT bytes at INDEXED line ranges; when the file
+     * changed after its last index sync those ranges can point at a DIFFERENT
+     * symbol's code. Freshness is verified here from data the index already
+     * stores: one stat() (size + mtime); content hashed only on mismatch.
+     */
+    isFileStaleOnDisk(cg, relPath, content) {
+        let root;
+        try {
+            root = cg.getProjectRoot();
+        }
+        catch {
+            return false;
+        }
+        const key = `${root}\0${relPath}`;
+        const now = Date.now();
+        const hit = this.driftCache.get(key);
+        if (hit && now - hit.at < ToolHandler.DRIFT_TTL_MS)
+            return hit.stale;
+        let stale = false;
+        try {
+            const rec = cg.getFile(relPath);
+            const absPath = rec ? (0, utils_1.validatePathWithinRoot)(root, relPath) : null;
+            if (rec && absPath && (0, fs_1.existsSync)(absPath)) {
+                const st = (0, fs_1.statSync)(absPath);
+                if (st.size !== rec.size || Math.floor(st.mtimeMs) !== Math.floor(rec.modifiedAt)) {
+                    const data = content ?? (0, fs_1.readFileSync)(absPath, 'utf-8');
+                    stale = (0, crypto_1.createHash)('sha256').update(data).digest('hex') !== rec.contentHash;
+                }
+            }
+        }
+        catch {
+            stale = false;
+        }
+        this.driftCache.set(key, { at: now, stale });
+        return stale;
+    }
     withStalenessNotice(result, projectPath) {
         if (result.isError)
             return result;
@@ -1432,9 +1645,12 @@ class ToolHandler {
         return { ...result, content: [{ type: 'text', text: composed }, ...rest] };
     }
     /**
-     * Execute a tool by name
+     * Execute a tool by name.
+     *
+     * `sessionState` is the calling MCP session's explore history (CG-17). Omit
+     * it (the CLI does) and explore behaves exactly as before, untracked.
      */
-    async execute(toolName, args) {
+    async execute(toolName, args, sessionState) {
         try {
             // Block the first tool call on the engine's post-open reconcile so we
             // never serve rows for files deleted/edited while no MCP server was
@@ -1480,7 +1696,20 @@ class ToolHandler {
                     return check;
             }
             const projectPath = args.projectPath;
-            const cacheEnabled = (0, query_cache_1.isMcpQueryCacheEnabled)() && (0, query_cache_1.isCacheableMcpTool)(toolName);
+            // Wrong question shapes → short Skip (before cache / graph work).
+            if (toolName === 'homegraph_explore' || toolName === 'homegraph_search') {
+                const qEarly = typeof args.query === 'string' ? args.query : '';
+                if (qEarly) {
+                    const deferKind = (0, query_utils_1.queryShouldDeferToBuiltinTools)(qEarly);
+                    if (deferKind) {
+                        return this.textResult((0, query_utils_1.homegraphDeferGuidance)(deferKind, qEarly));
+                    }
+                }
+            }
+            // Session-tracked explore must not hit the MCP query cache: a cache hit
+            // would re-serve the first call's full source and defeat CG-18 dedup.
+            const skipCacheForSession = toolName === 'homegraph_explore' && !!sessionState;
+            const cacheEnabled = !skipCacheForSession && (0, query_cache_1.isMcpQueryCacheEnabled)() && (0, query_cache_1.isCacheableMcpTool)(toolName);
             let cacheKey;
             let cacheQueries;
             let cacheIndex;
@@ -1530,10 +1759,10 @@ class ToolHandler {
                         const fast = (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
                             ? this.tryFastInventoryExplore(cgFast, q, rootFast)
                             : null)
-                            ?? this.tryCompactLocalSymbolExplore(cgFast, q, rootFast)
-                            ?? (toolName === 'homegraph_explore'
+                            ?? (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
                                 ? this.tryLightMechanismExplore(cgFast, q, rootFast)
-                                : null);
+                                : null)
+                            ?? this.tryCompactLocalSymbolExplore(cgFast, q, rootFast);
                         if (fast) {
                             if (cacheEnabled && cacheKey && cacheQueries && cacheIndex && !fast.isError) {
                                 cacheIndex.setEntry(cacheQueries, cacheKey, toolName, fast);
@@ -1547,10 +1776,16 @@ class ToolHandler {
                     }
                 }
             }
+            // Explore also carries the session's own call history down (CG-17) and its
+            // emission record back up. Both travel as plain properties — on the args
+            // object down, on the ToolResult up — because either leg may cross a
+            // structured-clone boundary into a worker.
+            const dispatchArgs = this.withSessionView(toolName, args, sessionState);
             // 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);
+            const raw = await this.runReadToolWithDeadline(toolName, dispatchArgs);
+            const result = this.takeExploreEmission(raw, sessionState);
             if (cacheEnabled && cacheKey && cacheQueries && cacheIndex && !result.isError) {
                 cacheIndex.setEntry(cacheQueries, cacheKey, toolName, result);
             }
@@ -1564,6 +1799,9 @@ class ToolHandler {
             if (err instanceof NotIndexedError) {
                 return this.textResult(err.message);
             }
+            if (err instanceof GraphSourcesDisabledError) {
+                return this.textResult(err.message);
+            }
             // Security refusal: a clean error, no retry encouragement.
             if (err instanceof PathRefusalError) {
                 return this.errorResult(err.message);
@@ -1573,6 +1811,50 @@ class ToolHandler {
                 'continue without homegraph for this task.');
         }
     }
+    /**
+     * Attach the caller's session view to an explore call's args (CG-17), on a
+     * COPY so the caller's object is never mutated. Nothing else sees it: a
+     * non-explore tool, or a caller with no session state, gets the args
+     * unchanged and pays nothing.
+     *
+     * A client that spells the internal key itself is stripped rather than
+     * trusted — the view decides what source a later call may withhold, so it has
+     * to come from the server's own record, never from the wire.
+     */
+    withSessionView(toolName, args, sessionState) {
+        if (!(explore_session_state_1.EXPLORE_SESSION_VIEW_ARG in args) && (!sessionState || toolName !== 'homegraph_explore')) {
+            return args;
+        }
+        const copy = { ...args };
+        delete copy[explore_session_state_1.EXPLORE_SESSION_VIEW_ARG];
+        if (sessionState && toolName === 'homegraph_explore') {
+            copy[explore_session_state_1.EXPLORE_SESSION_VIEW_ARG] = sessionState.view();
+        }
+        return copy;
+    }
+    /**
+     * Record an explore call's emission into the caller's session state and strip
+     * it from the result (CG-17).
+     *
+     * Unconditional strip: the property is internal, so it comes off even when
+     * there is no session state to record it into (the CLI path) — that is what
+     * keeps the agent-facing response byte-identical. Recording is wrapped
+     * because a bookkeeping bug must never fail a tool call that already
+     * succeeded.
+     */
+    takeExploreEmission(result, sessionState) {
+        const emission = result?.[explore_session_state_1.EXPLORE_EMISSION_KEY];
+        if (emission === undefined)
+            return result;
+        delete result[explore_session_state_1.EXPLORE_EMISSION_KEY];
+        if (sessionState) {
+            try {
+                sessionState.record(emission);
+            }
+            catch { /* bookkeeping only — never fail a served call */ }
+        }
+        return result;
+    }
     /**
      * Dispatch a read tool with a hard deadline under the typical ~60s MCP client
      * timeout.
@@ -1658,6 +1940,9 @@ class ToolHandler {
             if (err instanceof NotIndexedError) {
                 return this.textResult(err.message);
             }
+            if (err instanceof GraphSourcesDisabledError) {
+                return this.textResult(err.message);
+            }
             if (err instanceof PathRefusalError) {
                 return this.errorResult(err.message);
             }
@@ -1682,6 +1967,7 @@ class ToolHandler {
             case 'homegraph_explore': return await this.handleExplore(args);
             case 'homegraph_node': return await this.handleNode(args);
             case 'homegraph_files': return await this.handleFiles(args);
+            case 'homegraph_arkui_migrate': return await this.handleArkuiMigrate(args);
             case 'homegraph_spec_match': return await this.handleSpecMatch(args);
             case 'homegraph_spec_find': return await this.handleSpecFind(args);
             case 'homegraph_spec_trace': return await this.handleSpecTrace(args);
@@ -1692,6 +1978,10 @@ class ToolHandler {
         const query = this.validateString(args.query, 'query');
         if (typeof query !== 'string')
             return query;
+        const deferKind = (0, query_utils_1.queryShouldDeferToBuiltinTools)(query);
+        if (deferKind) {
+            return this.textResult((0, query_utils_1.homegraphDeferGuidance)(deferKind, 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.
@@ -1699,14 +1989,14 @@ class ToolHandler {
             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);
+                    ?? this.tryLightMechanismExplore(cg, query, projectRoot)
+                    ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot);
                 if (exploreRedirect)
                     return exploreRedirect;
             }
             const exploreRedirect = this.tryFastInventoryExplore(cg, query, projectRoot)
-                ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot)
-                ?? this.tryLightMechanismExplore(cg, query, projectRoot);
+                ?? this.tryLightMechanismExplore(cg, query, projectRoot)
+                ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot);
             if (exploreRedirect)
                 return exploreRedirect;
         }
@@ -1731,8 +2021,8 @@ class ToolHandler {
         // for "Send" surfaces the hand-written keeper before .pb.go stubs
         // that share the name. Stable: only reorders generated vs. not.
         const ranked = [...results].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 aGen = this.isGeneratedCandidate(cg, a.node.filePath) ? 1 : 0;
+            const bGen = this.isGeneratedCandidate(cg, b.node.filePath) ? 1 : 0;
             return aGen - bGen;
         });
         const formatted = this.formatSearchResults(ranked);
@@ -1820,13 +2110,28 @@ class ToolHandler {
         if (groups.length === 1) {
             const { callers, labels } = collect(groups[0]);
             if (callers.length === 0) {
+                // Empty callers often means registration/callback wiring (OnSurfaceChangedCB)
+                // — a one-line "no callers" teaches Grep/node thrash. Prefer compact body +
+                // text-usage sites when the symbol is a local anchor.
+                try {
+                    const root = cg.getProjectRoot();
+                    const compact = this.tryCompactLocalSymbolExplore(cg, symbol, root);
+                    if (compact)
+                        return compact;
+                }
+                catch { /* fall through */ }
                 return this.textResult(`No callers found for "${symbol}"${allMatches.note}${filterNote}`);
             }
             // A successful `file` narrowing makes the multi-symbol aggregation note
             // stale — suppress it.
             const note = fileFilter && !filteredOut ? '' : allMatches.note;
+            const includeBlock = this.formatCallerIncludeVisibility(cg, callers.slice(0, limit));
             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.'
+                + includeBlock
+                + '\n\n> Caller listing complete — answer from this list'
+                + (includeBlock ? ' + include/import visibility' : '')
+                + '; no read/grep needed.'
+                + '\n> If another type\'s visibility matters, pass **both** names to `homegraph_explore` (not callers alone).'
                 + note + filterNote;
             return this.textResult(this.truncateOutput(formatted));
         }
@@ -2831,28 +3136,35 @@ class ToolHandler {
     }
     /**
      * 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.
+     * lines. When the query also names an export/API token, 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 depSymbols = (0, query_utils_1.extractDependencySymbolsFromQuery)(query).filter((s) => !(0, query_utils_1.isMemberLikeIdentifier)(s) && !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(s.toLowerCase()));
+        const focusExports = [
+            ...new Set([
+                ...(0, query_utils_1.extractKitSubmoduleNamesFromQuery)(query),
+                ...depSymbols.filter((s) => s.length >= 4),
+            ]),
+        ];
         const kitSearchTerms = (0, query_utils_1.extractImportSearchTerms)(query);
+        // Named export/API + kit (or usage-survey intent) → return the full matching list.
+        const completeInventory = focusExports.length > 0
+            && (kitTerms.length > 0 || (0, query_utils_1.shouldBuildKitModuleUsageSurvey)(query) || (0, query_utils_1.shouldBuildApiUsageSurvey)(query));
         const seen = new Set();
         const sites = [];
         const tryAdd = (node, lineText) => {
+            if ((0, arkts_1.isOhosApiFilePath)(node.filePath))
+                return;
             const lineLc = lineText.toLowerCase();
+            const focus = focusExports.length > 0 ? focusExports : depSymbols;
+            if (focus.length > 0 && !focus.some((s) => lineLc.includes(s.toLowerCase())))
+                return;
+            // When a @kit module is named, require that kit — or @ohos.<focus> module path.
             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'))
+                const matchesOhosModule = focusExports.some((s) => lineLc.includes(`@ohos.${s.toLowerCase()}`));
+                if (!matchesKit && !matchesOhosModule)
                     return;
             }
             const key = `${node.filePath}:${node.startLine}`;
@@ -2862,10 +3174,10 @@ class ToolHandler {
             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) {
+        const importLimit = completeInventory ? 200 : focusExports.length > 0 || depSymbols.length > 0 ? 60 : 20;
+        const searchSyms = focusExports.length > 0 ? focusExports : depSymbols;
+        // Symbol-first search: named export hits `import { foo } from '@kit.X'`.
+        for (const sym of searchSyms) {
             let hits = [];
             try {
                 hits = cg.searchNodes(sym, { kinds: ['import'], limit: importLimit });
@@ -2878,7 +3190,7 @@ class ToolHandler {
             }
         }
         // Kit-module search (when no symbol filter, or to catch re-exports).
-        if (sites.length === 0 || depSymbols.length === 0) {
+        if (sites.length === 0 || searchSyms.length === 0) {
             for (const term of kitSearchTerms) {
                 const termLc = term.toLowerCase().replace(/^@kit\./, '');
                 let hits = [];
@@ -2892,8 +3204,8 @@ class ToolHandler {
                     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 (searchSyms.length > 0) {
+                        const matchesSym = searchSyms.some((s) => lineText.toLowerCase().includes(s.toLowerCase()));
                         if (!matchesSym)
                             continue;
                     }
@@ -2906,11 +3218,11 @@ class ToolHandler {
         }
         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 compactListing = completeInventory || (0, query_utils_1.shouldCompactImportListing)(sites.length, importInventoryFilter);
+        const cap = completeInventory ? sites.length : compactListing ? 40 : 15;
+        const focusLabel = focusExports.length > 0 ? focusExports.map((s) => `\`${s}\``).join(', ') : 'queried symbol(s)';
         const lines = compactListing
-            ? ['**Dependency list**', '', `Files importing the queried symbol(s) (${sites.length} total):`, '']
+            ? ['**Dependency list**', '', `Files importing ${focusLabel} (${sites.length} total):`, '']
             : ['**Import sites**', ''];
         for (const s of sites.slice(0, cap)) {
             if (compactListing) {
@@ -2925,12 +3237,8 @@ class ToolHandler {
         }
         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(`> **ANSWER NOW.** Complete list of **${sites.length}** matching import site(s) for ${focusLabel}. ` +
+                'Do **not** Grep/Read the same `@kit`/`@ohos` import pattern.');
         }
         lines.push('');
         return { section: lines.join('\n'), siteCount: sites.length, compactListing };
@@ -2938,7 +3246,7 @@ class ToolHandler {
     /**
      * External-caller inventory for a named class — methods → who calls them (paths only).
      */
-    buildCallerListingSection(cg, query) {
+    buildCallerListingSection(cg, query, projectRoot) {
         const typeNames = (0, query_utils_1.extractCallerSurveySymbols)(query);
         if (typeNames.length === 0)
             return '';
@@ -2947,11 +3255,34 @@ class ToolHandler {
         // 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 listedMethods = new Set((0, query_utils_1.extractListedTypeMethodsFromQuery)(query));
+        const typeNameSet = new Set((0, query_utils_1.extractTypeNamesFromQuery)(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));
+        // When Type + listed methods (BinaryGrid Set/Test/Fill), keep defs near the
+        // owning Type's files (template methods often lack reliable contains edges).
+        const ownerDirs = new Set();
+        if (listedMethods.size > 0 && typeNameSet.size > 0) {
+            for (const t of typeNameSet) {
+                for (const n of cg.getNodesByName(t)) {
+                    if (n.kind === 'class' || n.kind === 'struct' || n.kind === 'component') {
+                        const fp = rel(n.filePath);
+                        ownerDirs.add(fp.split('/').slice(0, -1).join('/'));
+                    }
+                }
+            }
+        }
+        for (const sym of typeNames.slice(0, 6)) {
+            let funcs = cg.getNodesByName(sym).filter((n) => (n.kind === 'function' || n.kind === 'method') && !(0, query_utils_1.isTestFile)(n.filePath));
+            if (listedMethods.has(sym) && ownerDirs.size > 0) {
+                const near = funcs.filter((n) => {
+                    const dir = rel(n.filePath).split('/').slice(0, -1).join('/');
+                    return ownerDirs.has(dir);
+                });
+                if (near.length > 0)
+                    funcs = near;
+            }
             for (const fn of funcs.slice(0, 3)) {
                 let callers = [];
                 try {
@@ -2981,6 +3312,8 @@ class ToolHandler {
             }
         }
         for (const typeName of typeNames.slice(0, 3)) {
+            if (!typeNameSet.has(typeName) && listedMethods.size > 0)
+                continue;
             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)) {
@@ -2999,8 +3332,11 @@ class ToolHandler {
                         }
                     }
                 }
+                const focusMethods = listedMethods.size > 0
+                    ? methods.filter((m) => listedMethods.has(m.name))
+                    : methods;
                 const methodLines = [];
-                for (const method of methods.slice(0, 25)) {
+                for (const method of (focusMethods.length > 0 ? focusMethods : methods).slice(0, 25)) {
                     let callers = [];
                     try {
                         callers = cg.getCallers(method.id);
@@ -3034,166 +3370,617 @@ class ToolHandler {
                 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.
+        // Text call-site fallback for return-value / member consumers when the graph
+        // has no edges onto SDK/.d.ts methods (common for getConnectionState).
+        if (substantive === 0 && (0, query_utils_1.queryAsReturnValueConsumerSurvey)(query)) {
+            const root = projectRoot || '';
+            for (const sym of typeNames.slice(0, 3)) {
+                if (!/^(?:get|is|has|create|on)[A-Z]/.test(sym) && !(0, query_utils_1.isMemberLikeIdentifier)(sym))
+                    continue;
+                let scanHits = [];
                 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);
-                        }
-                    }
+                    scanHits = cg.searchNodes(sym, { limit: 40 });
                 }
-                catch { /* */ }
-                // 2) Callees that look like services/APIs.
-                for (const method of methods.slice(0, 25)) {
-                    let callees = [];
+                catch {
+                    continue;
+                }
+                const esc = sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const callRe = new RegExp(`\\.${esc}\\s*\\(`);
+                const bareRe = new RegExp(`\\b${esc}\\s*\\(`);
+                const seen = new Set();
+                const bullets = [];
+                for (const r of scanHits) {
+                    if ((0, query_utils_1.isTestFile)(r.node.filePath))
+                        continue;
+                    if (/\.d\.ts$/i.test(r.node.filePath) || (0, arkts_1.isOhosApiFilePath)(r.node.filePath))
+                        continue;
+                    const abs = root
+                        ? (0, utils_1.validatePathWithinRoot)(root, r.node.filePath)
+                        : ((0, fs_1.existsSync)(r.node.filePath) ? r.node.filePath : null);
+                    if (!abs)
+                        continue;
+                    let fileLines = [];
                     try {
-                        callees = cg.getCallees(method.id);
+                        fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
                     }
                     catch {
                         continue;
                     }
-                    for (const c of callees) {
-                        if (c?.node)
-                            addEdge(upstream, c.node, method.name, 2);
+                    for (let i = 0; i < fileLines.length; i++) {
+                        const lineText = fileLines[i] ?? '';
+                        if (!callRe.test(lineText) && !bareRe.test(lineText))
+                            continue;
+                        const key = `${rel(r.node.filePath)}:${i + 1}`;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        bullets.push(`- \`${sym}\` ← \`${key}\`  \`${lineText.trim().slice(0, 120)}\``);
+                        if (bullets.length >= 12)
+                            break;
                     }
+                    if (bullets.length >= 12)
+                        break;
                 }
-                if (upstream.size === 0)
+                if (bullets.length > 0) {
+                    lines.push(`### \`${sym}\` (text call sites)`);
+                    lines.push(...bullets);
+                    lines.push('');
+                    substantive += bullets.length;
+                }
+            }
+        }
+        if (substantive === 0) {
+            if ((0, query_utils_1.queryAsReturnValueConsumerSurvey)(query)) {
+                return [
+                    '**Caller inventory**',
+                    '',
+                    '> No in-repo callers of the return-value member in the graph/index. **ANSWER NOW** — do not open SDK `.d.ts` stubs; Grep once for `.member(` only if needed.',
+                    '',
+                ].join('\n');
+            }
+            return '';
+        }
+        // Unique caller files — answers "哪些文件调用了 Type::methods" without Grep.
+        if (listedMethods.size > 0 && substantive > 0) {
+            const callerFiles = new Set();
+            for (const line of lines) {
+                const idx = line.indexOf('←');
+                if (idx < 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}\`)`);
+                for (const m of line.slice(idx).matchAll(/`([^`]+?):(\d+)`/g)) {
+                    callerFiles.add(m[1]);
                 }
-                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.');
+            }
+            if (callerFiles.size > 0) {
                 lines.push('');
+                lines.push('**Unique caller files**');
+                for (const fp of [...callerFiles].sort()) {
+                    lines.push(`- \`${fp}\``);
+                }
             }
         }
-        if (edgeCount === 0)
-            return { section: '', edgeCount: 0 };
-        lines.push('> Data-source survey — answer from upstream symbols above; source bodies omitted.');
+        lines.push('> Caller inventory complete — answer from this section.');
         lines.push('');
-        return { section: lines.join('\n'), edgeCount };
+        return lines.join('\n');
     }
     /**
-     * Main-thread fast path for inventory surveys — skips the worker queue.
+     * Multi-module / circular dependency survey — lean cycle list, not an import flood.
      */
-    tryFastPathResult(toolName, args) {
-        const query = args.query;
-        if (typeof query !== 'string')
+    buildModuleDependencySurveySection(cg, query) {
+        // Prefer leaf module tokens (`launchercommon`) over shared parents (`staticcommon`)
+        // — parent matches flood unrelated windowscene cycles.
+        const leafModules = new Set();
+        for (const p of (query.match(/\b[A-Za-z][\w]*(?:common|service|component|constants)\b/gi) ?? [])) {
+            const low = p.toLowerCase();
+            if (!/^(?:static|feature|product|base|common)$/i.test(low))
+                leafModules.add(low);
+        }
+        for (const seg of query.match(/[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)+/g) ?? []) {
+            const leaf = seg.split(/[/\\]/).pop()?.toLowerCase();
+            if (leaf && leaf.length >= 4 && /common|service|component|constants/i.test(leaf)) {
+                leafModules.add(leaf);
+            }
+        }
+        if (leafModules.size === 0)
+            return { section: '', hitCount: 0 };
+        const rel = (p) => p.replace(/\\/g, '/');
+        const hitLeaf = (fp) => {
+            const low = fp.toLowerCase().replace(/\\/g, '/');
+            for (const n of leafModules) {
+                if (low.includes(`/${n}/`) || low.includes(`/${n}.`) || low.endsWith(`/${n}`))
+                    return n;
+            }
             return null;
+        };
+        let cycles = [];
         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);
-            }
+            cycles = cg.findCircularDependencies();
         }
         catch {
-            return null;
+            cycles = [];
+        }
+        const matchedCycles = cycles
+            .map((c) => {
+            const touched = new Set();
+            const kept = [];
+            for (const p of c) {
+                const leaf = hitLeaf(p);
+                if (leaf) {
+                    touched.add(leaf);
+                    kept.push(p);
+                }
+            }
+            return touched.size >= 2 ? kept : [];
+        })
+            .filter((c) => c.length >= 2)
+            .slice(0, 8);
+        const lines = [
+            '**Module dependency / cycle survey**',
+            '',
+            `> Focused on leaf modules \`${[...leafModules].slice(0, 8).join('`, `')}\`. **ANSWER NOW** — do not glob every \`oh-package.json5\`.`,
+            '',
+        ];
+        if (matchedCycles.length === 0) {
+            lines.push(`- No **circular** import cycle spanning **two or more** of the named leaf modules.`);
+            lines.push('- (Cycles only inside an unrelated sibling under the same parent path are omitted.)');
+            lines.push('');
+            return { section: lines.join('\n'), hitCount: 1 };
         }
-        return null;
+        lines.push(`Found **${matchedCycles.length}** cycle(s) spanning named leaf modules:`);
+        for (const c of matchedCycles) {
+            lines.push(`- ${c.map((p) => `\`${rel(p)}\``).join(' → ')}`);
+        }
+        lines.push('');
+        return { section: lines.join('\n'), hitCount: matchedCycles.length };
     }
     /**
-     * Fast inventory-only explore — skips findRelevantContext for survey/caller/dependency queries.
+     * Path-module / named-Type NAPI export surface — not a 50-file domain dump.
      */
-    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 = [
+    buildModuleExportSurveySection(cg, query, projectRoot) {
+        const paths = (0, query_utils_1.extractPathSegmentsFromQuery)(query);
+        const types = (0, query_utils_1.extractTypeNamesFromQuery)(query).filter((t) => !(0, query_utils_1.isFrameworkUiDecoratorName)(t));
+        const needles = [
+            ...paths.map((p) => p.replace(/\\/g, '/').toLowerCase()),
+            ...types.map((t) => t.toLowerCase()),
+        ].filter((n) => n.length >= 4);
+        if (needles.length === 0)
+            return { section: '', hitCount: 0 };
+        const rel = (p) => p.replace(/\\/g, '/');
+        const inScope = (fp) => {
+            const low = rel(fp).toLowerCase();
+            return needles.some((n) => low.includes(n));
+        };
+        const exports = [];
+        const seen = new Set();
+        const seedNames = [
+            'Export', 'NapiInit', 'napi_init', 'Init', 'napi_module_register',
+            ...types.slice(0, 3),
+        ];
+        for (const seed of seedNames) {
+            let hits = [];
+            try {
+                hits = cg.searchNodes(seed, { limit: 30 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                if (!inScope(r.node.filePath) || (0, query_utils_1.isTestFile)(r.node.filePath))
+                    continue;
+                if (!/\.(cpp|cc|cxx|h|hpp)$/i.test(r.node.filePath) && !/napi/i.test(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++) {
+                    const line = fileLines[i] ?? '';
+                    // napi_define_function / exports / Descriptor { "foo", … }
+                    const m = line.match(/napi_define_(?:function|property)\s*\([^,]+,\s*["']([\w]+)["']/i)
+                        || line.match(/\{\s*["']([\w]+)["']\s*,\s*(?:nullptr|NULL)?\s*,\s*\w+/i)
+                        || line.match(/\.?(?:exports|export)\s*[:=].*["']([\w]+)["']/i);
+                    if (!m?.[1] || m[1].length < 2)
+                        continue;
+                    const key = `${m[1]}:${rel(r.node.filePath)}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    exports.push({
+                        name: m[1],
+                        file: rel(r.node.filePath),
+                        line: i + 1,
+                        snippet: line.trim().slice(0, 100),
+                    });
+                }
+                // Also list Export / Init method nodes in-scope.
+                if (/^(?:Export|Init|NapiInit)$/i.test(r.node.name)) {
+                    const key = `fn:${r.node.name}:${rel(r.node.filePath)}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        exports.push({
+                            name: r.node.name,
+                            file: rel(r.node.filePath),
+                            line: r.node.startLine,
+                            snippet: (r.node.signature || r.node.name).slice(0, 100),
+                        });
+                    }
+                }
+            }
+        }
+        const lines = [
+            '**NAPI / native export survey**',
+            '',
+            `> In-repo NAPI surface for \`${needles.slice(0, 4).join('`, `')}\`. **ANSWER NOW** — do not Grep \`napi_define\` again.`,
+            '',
+        ];
+        if (exports.length === 0) {
+            lines.push('- No `napi_define_*` / Export descriptors found under the named path/Type.');
+            lines.push('');
+            return { section: lines.join('\n'), hitCount: 0 };
+        }
+        for (const e of exports.slice(0, 30)) {
+            lines.push(`- \`${e.name}\` — \`${e.file}:${e.line}\`  \`${e.snippet}\``);
+        }
+        if (exports.length > 30)
+            lines.push(`- … and ${exports.length - 30} more`);
+        lines.push('');
+        return { section: lines.join('\n'), hitCount: Math.min(exports.length, 30) };
+    }
+    /**
+     * Named `.d.ts` wrap — where the basename is imported / called in-repo.
+     */
+    buildDtsWrapSurveySection(cg, query, projectRoot) {
+        const bases = (0, query_utils_1.extractFileBasenamesFromQuery)(query)
+            .map((b) => b.replace(/\.d\.ts$/i, ''))
+            .filter((b) => b.length >= 3);
+        if (bases.length === 0 && /\.d\.ts\b/i.test(query)) {
+            for (const m of query.matchAll(/\b([A-Za-z][\w]*)\.d\.ts\b/g)) {
+                if (m[1])
+                    bases.push(m[1]);
+            }
+        }
+        if (bases.length === 0)
+            return { section: '', hitCount: 0 };
+        const rel = (p) => p.replace(/\\/g, '/');
+        const hits = new Map();
+        for (const base of bases.slice(0, 3)) {
+            let nodes = [];
+            try {
+                nodes = cg.searchNodes(base, { limit: 40 });
+            }
+            catch {
+                continue;
+            }
+            const re = new RegExp(`(?:from\\s+['"].*${base}['"]|import\\s+.*\\b${base}\\b|\\b${base}\\.\\w+)`, 'i');
+            const seen = new Set();
+            for (const r of nodes) {
+                if ((0, query_utils_1.isTestFile)(r.node.filePath))
+                    continue;
+                const fp = rel(r.node.filePath);
+                if (/\.d\.ts$/i.test(fp))
+                    continue;
+                if (seen.has(fp))
+                    continue;
+                seen.add(fp);
+                const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                if (!abs)
+                    continue;
+                let content = '';
+                try {
+                    content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                const fileLines = content.split('\n');
+                for (let i = 0; i < fileLines.length; i++) {
+                    const line = fileLines[i] ?? '';
+                    if (!re.test(line) && !line.includes(base))
+                        continue;
+                    if (!new RegExp(`\\b${base}\\b`, 'i').test(line))
+                        continue;
+                    const prev = hits.get(fp) ?? { lines: [], snippet: '' };
+                    if (!prev.lines.includes(i + 1))
+                        prev.lines.push(i + 1);
+                    if (!prev.snippet)
+                        prev.snippet = line.trim().slice(0, 100);
+                    hits.set(fp, prev);
+                }
+            }
+        }
+        const lines = [
+            '**`.d.ts` wrap / call sites**',
+            '',
+            `> In-repo imports/uses of \`${bases.join('`, `')}\` (stub file itself omitted). **ANSWER NOW.**`,
+            '',
+        ];
+        if (hits.size === 0) {
+            lines.push('- No in-repo import/call sites indexed for this wrap.');
+            lines.push('');
+            return { section: lines.join('\n'), hitCount: 0 };
+        }
+        for (const [fp, info] of [...hits.entries()].sort((a, b) => a[0].localeCompare(b[0])).slice(0, 28)) {
+            const ls = info.lines.slice(0, 4).map((l) => `L${l}`).join(', ');
+            lines.push(info.snippet
+                ? `- \`${fp}\` (${ls})  \`${info.snippet}\``
+                : `- \`${fp}\` (${ls})`);
+        }
+        lines.push('');
+        return { section: lines.join('\n'), hitCount: hits.size };
+    }
+    /**
+     * Named Toggle/control state-sync — which files/modules mention the control
+     * (Type may be missing from FTS; seed stems + text scan).
+     */
+    buildNamedControlStateSyncSection(cg, query, projectRoot) {
+        const types = (0, query_utils_1.extractTypeNamesFromQuery)(query).filter((t) => !(0, query_utils_1.isFrameworkUiDecoratorName)(t));
+        if (types.length === 0)
+            return { section: '', hitCount: 0 };
+        const stems = new Set();
+        for (const t of types) {
+            stems.add(t);
+            for (const m of t.matchAll(/[A-Z][a-z]+/g)) {
+                if (m[0] && m[0].length >= 4)
+                    stems.add(m[0]);
+            }
+        }
+        const rel = (p) => p.replace(/\\/g, '/');
+        const hits = new Map();
+        for (const stem of [...stems].slice(0, 6)) {
+            let nodes = [];
+            try {
+                nodes = cg.searchNodes(stem, { limit: 35 });
+            }
+            catch {
+                continue;
+            }
+            const re = new RegExp(`\\b${stem.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+            const seen = new Set();
+            for (const r of nodes) {
+                if ((0, query_utils_1.isTestFile)(r.node.filePath))
+                    continue;
+                const fp = rel(r.node.filePath);
+                if (seen.has(fp))
+                    continue;
+                seen.add(fp);
+                const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                if (!abs)
+                    continue;
+                let content = '';
+                try {
+                    content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                const fileLines = content.split('\n');
+                let matched = false;
+                for (let i = 0; i < fileLines.length; i++) {
+                    const line = fileLines[i] ?? '';
+                    if (!re.test(line) && !line.includes(stem))
+                        continue;
+                    const prev = hits.get(fp) ?? { lines: [], snippet: '', score: 0 };
+                    if (!prev.lines.includes(i + 1))
+                        prev.lines.push(i + 1);
+                    if (!prev.snippet)
+                        prev.snippet = line.trim().slice(0, 100);
+                    if (/Manager|Service|Store|Controller|Provider/i.test(fp) || /Manager|Service|Store/.test(line)) {
+                        prev.score += 5;
+                    }
+                    prev.score += 1;
+                    hits.set(fp, prev);
+                    matched = true;
+                }
+                if (!matched && /Toggle|Switch|Hotspot|Manager/i.test(r.node.name)) {
+                    hits.set(fp, {
+                        lines: [r.node.startLine],
+                        snippet: (r.node.signature || r.node.name).slice(0, 100),
+                        score: 2,
+                    });
+                }
+            }
+        }
+        const ranked = [...hits.entries()].sort((a, b) => b[1].score - a[1].score || a[0].localeCompare(b[0]));
+        const lines = [
+            '**Control / Toggle state-sync sites**',
+            '',
+            `> In-repo references to \`${types.join('`, `')}\` (and stems). Prefer Manager/Service files for \"which module guarantees consistency\". **ANSWER NOW.**`,
+            '',
+        ];
+        if (ranked.length === 0) {
+            lines.push('- No indexed sites for the named control; answer from domain knowledge only if sure.');
+            lines.push('');
+            return { section: lines.join('\n'), hitCount: 0 };
+        }
+        for (const [fp, info] of ranked.slice(0, 24)) {
+            const ls = info.lines.slice(0, 3).map((l) => `L${l}`).join(', ');
+            lines.push(info.snippet
+                ? `- \`${fp}\` (${ls})  \`${info.snippet}\``
+                : `- \`${fp}\` (${ls})`);
+        }
+        lines.push('');
+        return { section: lines.join('\n'), hitCount: Math.min(ranked.length, 24) };
+    }
+    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|account|osAccount|AppAccount|distributedAccount|userId|getOsAccount/i;
+        const lines = ['**Data sources / upstream services**', ''];
+        let edgeCount = 0;
+        const addEdge = (bucket, node, via, rank, opts) => {
+            if ((0, query_utils_1.isTestFile)(node.filePath))
+                return;
+            const sig = `${node.name} ${node.filePath} ${node.signature || ''}`;
+            // Same-file @ohos/@kit imports are always data-source candidates (BadgeManager
+            // → notificationManager), even when the import local name fails SERVICE_RE.
+            if (!opts?.importAlways && !SERVICE_RE.test(sig))
+                return;
+            if (opts?.importAlways && !/@ohos\.|@kit\.|ohos\./i.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, { importAlways: true });
+                    }
+                    for (const r of cg.searchNodes('@kit', { kinds: ['import'], limit: 40 })) {
+                        if (r.node.filePath !== cls.filePath)
+                            continue;
+                        addEdge(upstream, r.node, 'import', 0, { importAlways: true });
+                    }
+                    for (const term of [
+                        'notification', 'badge', 'NumBadge', 'subscribe', 'bundle', 'ability',
+                        'account', 'osAccount', 'AppAccount', 'distributedAccount',
+                    ]) {
+                        for (const r of cg.searchNodes(term, { kinds: ['import'], limit: 30 })) {
+                            if (r.node.filePath !== cls.filePath)
+                                continue;
+                            addEdge(upstream, r.node, 'import', 1, { importAlways: true });
+                        }
+                    }
+                }
+                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) {
+            lines.push('- No `@ohos`/`@kit` / service-like upstream edges indexed for the named Manager. ' +
+                '**ANSWER NOW** from the Manager definition file (prefer in-repo `AccountManager` / `*Manager.ets`, not SDK `.d.ts`).');
+            lines.push('');
+            return { section: lines.join('\n'), edgeCount: 0 };
+        }
+        lines.push('> Data-source survey — **ANSWER NOW** from upstream symbols above (system `@ohos`/`@kit` imports first). ' +
+            'Do not Grep/search/callers the same Manager for the service name.');
+        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;
+        const deferKind = (0, query_utils_1.queryShouldDeferToBuiltinTools)(query);
+        if (deferKind) {
+            return this.textResult((0, query_utils_1.homegraphDeferGuidance)(deferKind, query));
+        }
+        try {
+            const cg = this.getHomeGraph(args.projectPath);
+            const projectRoot = cg.getProjectRoot();
+            if (toolName === 'homegraph_explore') {
+                return this.tryFastInventoryExplore(cg, query, projectRoot)
+                    ?? this.tryLightMechanismExplore(cg, query, projectRoot)
+                    ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot);
+            }
+            if (toolName === 'homegraph_search') {
+                return this.tryFastInventoryExplore(cg, query, projectRoot)
+                    ?? this.tryLightMechanismExplore(cg, query, projectRoot)
+                    ?? this.tryCompactLocalSymbolExplore(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, projectRoot)
+                : '';
+            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.'
+                        ? 'Type surface: inheritance + method caller inventory below — **ANSWER NOW**; 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.',
+                            ? 'Inheritance survey above lists all direct subtypes found. **ANSWER NOW** — do not Grep `extends`.'
+                            : 'Caller inventory lists method→caller sites — **ANSWER NOW**; do not fan out `homegraph_callers` per method.',
                 ];
                 if (inheritanceSection)
                     parts.push(inheritanceSection);
@@ -3201,47 +3988,128 @@ class ToolHandler {
                     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))
+            // Empty inheritance graph: stop only for *explicit* subclass intent
+            // (子类/extends/subclass). Bare `search("IntGrid")` must fall through to
+            // compact definition — an empty subtype ANSWER NOW blocked visibility/use
+            // questions that reuse a type name after callers().
+            if ((0, query_utils_1.queryAsInheritanceSurvey)(query)) {
+                return this.textResult([
+                    `**Exploration: ${query}**`,
+                    '',
+                    'No direct subtypes / inheritance edges indexed for the named type(s). **ANSWER NOW** — do not Grep `extends` unless you need a second opinion.',
+                    '',
+                ].join('\n'));
+            }
+            // Bare type-name focus with no subtypes — fall through to compact / other
+            // inventory (definition + usage), not a fat full explore.
+        }
+        const importResult = (inheritanceOnly
+            || (0, query_utils_1.queryIsTypeNameFocus)(query)
+            || (0, query_utils_1.queryAsInheritanceSurvey)(query)
+            || (0, query_utils_1.queryAsDataSourceSurvey)(query)
+            || (0, query_utils_1.shouldBuildApiUsageSurvey)(query)
+            || (0, query_utils_1.queryAsInRepoSystemCapabilityHowto)(query)
+            || (0, query_utils_1.queryAsReturnValueConsumerSurvey)(query)
+            || (0, query_utils_1.queryAsDeclarationSiteSurvey)(query)
+            || (0, query_utils_1.queryAsModuleExportSurvey)(query)
+            || (0, query_utils_1.queryAsModuleDependencySurvey)(query)
+            // Kit install-deps needs oh-package lines — skip bare import inventory.
+            || (0, query_utils_1.queryAsksKitInstallDeps)(query))
             ? { section: '', siteCount: 0, compactListing: false }
             : this.buildImportSitesSection(cg, query, projectRoot);
         if (importResult.section)
             lines.push(importResult.section);
+        // Kit usage section is redundant when a focused import inventory already listed
+        // every matching `@kit`/`export` site (avoids a second dump + Grep temptation).
+        // Install-deps questions always take the kit survey (oh-package + imports).
         const kitUsageResult = (0, query_utils_1.shouldBuildKitModuleUsageSurvey)(query)
+            && ((0, query_utils_1.queryAsksKitInstallDeps)(query)
+                || !(importResult.compactListing && importResult.siteCount > 0))
             ? this.buildKitModuleUsageSection(cg, query, projectRoot)
             : { section: '', symbolCount: 0 };
         if (kitUsageResult.section)
             lines.push(kitUsageResult.section);
-        const domainFileResult = (0, query_utils_1.shouldBuildDomainFileSurvey)(query)
+        const domainFileResult = (0, query_utils_1.shouldBuildDomainFileSurvey)(query) && !(0, query_utils_1.queryAsDataSourceSurvey)(query)
+            && !(0, query_utils_1.queryAsInRepoSystemCapabilityHowto)(query)
+            && !(0, query_utils_1.queryAsModuleDependencySurvey)(query)
+            && !(0, query_utils_1.queryAsModuleExportSurvey)(query)
+            && !(0, query_utils_1.queryAsDtsWrapSurvey)(query)
+            && !(0, query_utils_1.queryAsDeclarationSiteSurvey)(query)
             ? this.buildDomainFileSurveySection(cg, query)
             : { section: '', fileCount: 0 };
         if (domainFileResult.section)
             lines.push(domainFileResult.section);
+        const systemCapResult = (0, query_utils_1.queryAsInRepoSystemCapabilityHowto)(query)
+            ? this.buildSystemCapabilityHowtoSection(cg, query, projectRoot)
+            : { section: '', hitCount: 0 };
+        if (systemCapResult.section)
+            lines.push(systemCapResult.section);
+        const declarationResult = (0, query_utils_1.queryAsDeclarationSiteSurvey)(query)
+            ? this.buildDeclarationSiteSurveySection(cg, query, projectRoot)
+            : { section: '', hitCount: 0, attempted: false };
+        if (declarationResult.section)
+            lines.push(declarationResult.section);
+        // Kit usage surveys already list @kit import sites — a second API-usage dump
+        // (taskpool × 32 files) doubles tokens without new signal.
         const apiUsageResult = (0, query_utils_1.shouldBuildApiUsageSurvey)(query)
+            && !(0, query_utils_1.queryAsDeclarationSiteSurvey)(query)
+            && !(0, query_utils_1.shouldBuildKitModuleUsageSurvey)(query)
             ? this.buildApiUsageSection(cg, query, projectRoot)
             : { section: '', fileCount: 0 };
         if (apiUsageResult.section)
             lines.push(apiUsageResult.section);
+        const moduleDepResult = (0, query_utils_1.queryAsModuleDependencySurvey)(query)
+            ? this.buildModuleDependencySurveySection(cg, query)
+            : { section: '', hitCount: 0 };
+        if (moduleDepResult.section)
+            lines.push(moduleDepResult.section);
+        const moduleExportResult = (0, query_utils_1.queryAsModuleExportSurvey)(query)
+            ? this.buildModuleExportSurveySection(cg, query, projectRoot)
+            : { section: '', hitCount: 0 };
+        if (moduleExportResult.section)
+            lines.push(moduleExportResult.section);
+        const dtsWrapResult = (0, query_utils_1.queryAsDtsWrapSurvey)(query)
+            ? this.buildDtsWrapSurveySection(cg, query, projectRoot)
+            : { section: '', hitCount: 0 };
+        if (dtsWrapResult.section)
+            lines.push(dtsWrapResult.section);
+        const controlSyncResult = (0, query_utils_1.queryAsNamedControlStateSyncSurvey)(query)
+            ? this.buildNamedControlStateSyncSection(cg, query, projectRoot)
+            : { section: '', hitCount: 0 };
+        if (controlSyncResult.section)
+            lines.push(controlSyncResult.section);
         const dataSourceResult = (0, query_utils_1.queryAsDataSourceSurvey)(query)
             ? this.buildDataSourceSection(cg, query)
             : { section: '', edgeCount: 0 };
         if (dataSourceResult.section)
             lines.push(dataSourceResult.section);
+        const hoverResult = (0, query_utils_1.shouldBuildHoverHandlerSurvey)(query)
+            ? this.buildHoverHandlerSurveySection(cg, query, projectRoot)
+            : { section: '', hitCount: 0 };
+        if (hoverResult.section)
+            lines.push(hoverResult.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 skipFlow = typeSurface || (0, query_utils_1.queryAsCallerOrMethodSurvey)(query)
+            || (0, query_utils_1.queryAsDeclarationSiteSurvey)(query)
+            || (0, query_utils_1.queryAsInRepoSystemCapabilityHowto)(query)
+            || (0, query_utils_1.queryAsReturnValueConsumerSurvey)(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 listedTypeMethods = (0, query_utils_1.extractListedTypeMethodsFromQuery)(query).length > 0;
+        // Type + listed methods (BinaryGrid Set/Test/Fill) must keep caller inventory even
+        // when multi-anchor would otherwise skip it into a fat source dump.
+        const callerSection = !hasFlowPath && (!multiAnchor || listedTypeMethods) && (0, query_utils_1.shouldBuildCallerInventory)(query)
+            ? this.buildCallerListingSection(cg, query, projectRoot) : '';
+        // Field new/delete inventories already list text sites — skip redundant member scan.
         const memberSection = !hasFlowPath && !multiAnchor && (0, query_utils_1.shouldBuildMemberSurvey)(query)
+            && !((0, query_utils_1.queryAsFieldUsageSurvey)(query) && apiUsageResult.fileCount > 0)
             ? this.buildMemberSurveySection(cg, query, projectRoot) : '';
         const configSection = (0, query_utils_1.shouldBuildConfigSection)(query)
             ? this.buildConfigFileSection(cg, query, projectRoot) : '';
@@ -3267,10 +4135,60 @@ class ToolHandler {
             ? 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;
+            || apiUsageResult.section || dataSourceResult.section || hoverResult.section || inheritanceSection
+            || callerSection || memberSection || configSection
+            || systemCapResult.section || declarationResult.section || moduleDepResult.section
+            || moduleExportResult.section || dtsWrapResult.section || controlSyncResult.section;
         if (!hasAnySection)
             return null;
+        // Data-source / API usage inventories are complete without source dumps —
+        // stop here so agents do not also get a fat import list + follow-up Read.
+        if (systemCapResult.hitCount > 0) {
+            return finishCompact(`System-capability howto — **${systemCapResult.hitCount}** in-repo site(s). **ANSWER NOW** from \`@ohos\`/\`System\` call sites above.`);
+        }
+        // Declaration intent must NOT fall through to a fat explore / include dump when empty.
+        if (declarationResult.attempted) {
+            return finishCompact(declarationResult.hitCount > 0
+                ? `Declaration-site survey — **${declarationResult.hitCount}** site(s). **ANSWER NOW** from ids + bindings above; do not Grep the same Type.`
+                : 'Declaration-site survey complete (0 sites). **ANSWER NOW** from the note above.');
+        }
+        if (controlSyncResult.section) {
+            return finishCompact(`Control/Toggle state-sync survey — **${controlSyncResult.hitCount}** file(s). **ANSWER NOW** from Manager/Service sites above.`);
+        }
+        if (kitUsageResult.section && (0, query_utils_1.shouldBuildKitModuleUsageSurvey)(query)) {
+            return finishCompact((0, query_utils_1.queryAsksKitInstallDeps)(query)
+                ? 'Kit install/deps survey — **ANSWER NOW** from imports + oh-package lines above; do not Grep oh-package again.'
+                : `Kit module **in-repo usage** — **${kitUsageResult.symbolCount}** imported symbol(s). **ANSWER NOW**; do not Grep the same \`@kit\` path.`);
+        }
+        if (moduleExportResult.section) {
+            return finishCompact(`NAPI / native export survey — **${moduleExportResult.hitCount}** export(s). **ANSWER NOW**; do not Grep napi_define again.`);
+        }
+        if (dtsWrapResult.section) {
+            return finishCompact(`\`.d.ts\` wrap call sites — **${dtsWrapResult.hitCount}** file(s). **ANSWER NOW**; do not Grep the wrap basename again.`);
+        }
+        if (moduleDepResult.hitCount > 0 || ((0, query_utils_1.queryAsModuleDependencySurvey)(query) && moduleDepResult.section)) {
+            return finishCompact(`Module dependency / cycle survey — **ANSWER NOW** from the edges above; do not glob every oh-package.`);
+        }
+        // Data-source intent must stop even when edges=0 (empty still beats a 20k dump).
+        if (dataSourceResult.section && (0, query_utils_1.queryAsDataSourceSurvey)(query)) {
+            return finishCompact(dataSourceResult.edgeCount > 0
+                ? `Data-source survey — **${dataSourceResult.edgeCount}** upstream symbol(s). **ANSWER NOW** from system \`@ohos\`/\`@kit\` imports first.`
+                : 'Data-source survey complete (0 service edges). **ANSWER NOW** from the note + Manager defs above; do not Grep broadly.');
+        }
+        if (apiUsageResult.fileCount > 0 && !dataSourceResult.section) {
+            return finishCompact(`API usage survey — **${apiUsageResult.fileCount}** file(s). **ANSWER NOW** from the list above.`);
+        }
+        if ((0, query_utils_1.queryAsReturnValueConsumerSurvey)(query) && callerBulletCount > 0) {
+            return finishCompact(`Return-value consumers — **${callerBulletCount}** caller site(s). **ANSWER NOW** from the caller inventory; do not Grep the same member.`);
+        }
+        // Return-value intent with empty graph callers — stop before SDK .d.ts dumps.
+        if ((0, query_utils_1.queryAsReturnValueConsumerSurvey)(query) && callerSection) {
+            return finishCompact('Return-value consumer survey complete. **ANSWER NOW** from the inventory above; do not open SDK `.d.ts` stubs.');
+        }
+        // Type + listed methods (Set/Test/Fill) — multi-anchor would block omit-source; stop here.
+        if (listedTypeMethods && callerBulletCount > 0) {
+            return finishCompact(`Caller inventory — **${callerBulletCount}** site(s) for listed methods. **ANSWER NOW**; do not fan out callers per method.`);
+        }
         const omitSource = (0, query_utils_1.shouldOmitSourceBodies)({
             importSiteCount: importResult.siteCount,
             hasFilteredImports: importInventoryFilter && importResult.siteCount > 0,
@@ -3282,36 +4200,41 @@ class ToolHandler {
             inheritanceListed,
             domainFileCount: domainFileResult.fileCount,
             dataSourceEdgeCount: dataSourceResult.edgeCount,
-        }, hasFlowPath, multiAnchor);
+        }, hasFlowPath, multiAnchor) || hoverResult.hitCount > 0;
         if (!omitSource)
             return null;
         if (configSection)
-            return finishCompact('Config/manifest content above — answer from it directly.');
+            return finishCompact('Config/manifest content above — answer from it directly. **ANSWER NOW.**');
+        if (hoverResult.section) {
+            return finishCompact(`Hover/pointer handler survey — **${hoverResult.hitCount}** site(s). **ANSWER NOW** from the list + snippets; do not Grep \`onHover\` again.`);
+        }
         if (kitUsageResult.section) {
-            return finishCompact(`Kit module usage survey — **${kitUsageResult.symbolCount}** imported symbol(s) across the repo.`);
+            return finishCompact(`Kit module **in-repo usage** survey — **${kitUsageResult.symbolCount}** imported symbol(s). ` +
+                'This is not an SDK catalog. **ANSWER NOW** from the usage list; do not Grep the same `@kit` path.');
         }
         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.');
+                'This is the exhaustive related-file inventory; **ANSWER NOW** — no glob/search needed.');
         }
         if (apiUsageResult.fileCount > 0) {
-            return finishCompact(`API usage survey — **${apiUsageResult.fileCount}** file(s) referencing the queried symbol(s).`);
+            return finishCompact(`API usage survey — **${apiUsageResult.fileCount}** file(s). **ANSWER NOW** from the list above.`);
         }
         if (dataSourceResult.edgeCount > 0) {
-            return finishCompact(`Data-source survey — **${dataSourceResult.edgeCount}** upstream symbol(s) listed above.`);
+            return finishCompact(`Data-source survey — **${dataSourceResult.edgeCount}** upstream symbol(s). **ANSWER NOW.**`);
+        }
+        if (inheritanceListed) {
+            return finishCompact('Inheritance survey above lists all direct subtypes found. **ANSWER NOW** — do not grep `extends`.');
         }
-        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).`);
+            return finishCompact(`Listed **${importResult.siteCount}** import site(s). **ANSWER NOW** from the dependency list.`);
         }
         if (callerBulletCount >= 1) {
-            return finishCompact(`Caller inventory lists **${callerBulletCount}** call site(s) — answer from the section above.`);
+            return finishCompact(`Caller inventory lists **${callerBulletCount}** call site(s). **ANSWER NOW** from the section above.`);
         }
         if (memberFileCount >= 2) {
-            return finishCompact(`Member/pattern usage in **${memberFileCount}** file(s) — answer from the inventory above.`);
+            return finishCompact(`Member/pattern usage in **${memberFileCount}** file(s). **ANSWER NOW** from the inventory above.`);
         }
-        return finishCompact('Inventory sections above are complete for this query.');
+        return finishCompact('Inventory sections above are complete for this query. **ANSWER NOW.**');
     }
     /**
      * Render a compact symbol-bounded slice of one file (lightweight mechanism path).
@@ -3359,6 +4282,8 @@ class ToolHandler {
         const fileNodes = new Map();
         const seedIds = new Set();
         const addNode = (n) => {
+            if ((0, arkts_1.isOhosApiFilePath)(n.filePath))
+                return;
             if (isTestPath(n.filePath))
                 return;
             if (n.kind !== 'import' && !STRUCTURE_KINDS.has(n.kind))
@@ -3369,6 +4294,39 @@ class ToolHandler {
                 list.push(n);
             fileNodes.set(n.filePath, list);
         };
+        const domainTermsEarly = (0, query_utils_1.extractDomainSearchTerms)(query);
+        const distinctiveEarly = domainTermsEarly.filter((t) => /^[\x00-\x7F]+$/.test(t) && !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase()));
+        // Distinctive-token IMPORT seeds first — `@ohos.convertxml` / `XmlParse*` before
+        // structure FTS fills the budget with unrelated Parser* hits.
+        for (const term of distinctiveEarly.slice(0, 4)) {
+            const termLc = term.toLowerCase();
+            let hits = [];
+            try {
+                hits = cg.searchNodes(term, { kinds: ['import'], limit: 40 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                if ((0, arkts_1.isOhosApiFilePath)(r.node.filePath))
+                    continue;
+                const line = (0, query_utils_1.resolveImportLineFromNode)(r.node, projectRoot).toLowerCase();
+                const nameLc = r.node.name.toLowerCase();
+                const sigLc = (r.node.signature || '').toLowerCase();
+                if (!nameLc.includes(termLc) && !line.includes(termLc) && !sigLc.includes(termLc))
+                    continue;
+                addNode(r.node);
+                try {
+                    for (const n of cg.getNodesInFile(r.node.filePath)) {
+                        if (STRUCTURE_KINDS.has(n.kind) && n.name.toLowerCase().includes(termLc))
+                            addNode(n);
+                    }
+                }
+                catch { /* optional */ }
+                if (seedIds.size >= 16)
+                    break;
+            }
+        }
         for (const seed of (0, query_utils_1.extractMechanismEntrySeeds)(query)) {
             if (seed.startsWith('@')) {
                 let hits = [];
@@ -3387,35 +4345,91 @@ class ToolHandler {
                     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)) {
+        if (seedIds.size < 2 || distinctiveEarly.length > 0) {
+            const domainTerms = domainTermsEarly;
+            // Prefer distinctive ASCII (xml) then Chinese nouns — never seed on bare verbs
+            // when a distinctive token exists (xml parse → convertxml, not ParseNotification*).
+            const distinctive = distinctiveEarly;
+            const ranked = distinctive.length > 0
+                ? [
+                    ...distinctive,
+                    ...domainTerms.filter((t) => !/^[\x00-\x7F]+$/.test(t) && t.length >= 2 && t.length <= 8),
+                ]
+                : [
+                    ...domainTerms.filter((t) => /^[\x00-\x7F]+$/.test(t) && !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase())),
+                    ...domainTerms.filter((t) => !/^[\x00-\x7F]+$/.test(t) && t.length >= 2 && t.length <= 8),
+                    ...domainTerms.filter((t) => /^[\x00-\x7F]+$/.test(t) && query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase())),
+                ];
+            for (const term of ranked.slice(0, 10)) {
                 let hits = [];
                 try {
                     hits = cg.searchNodes(term, {
                         kinds: ['class', 'struct', 'interface', 'function', 'method', 'import'],
-                        limit: 16,
+                        limit: 20,
                     });
                 }
                 catch {
                     continue;
                 }
+                const termIsVerb = query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(term.toLowerCase());
+                const termLc = term.toLowerCase();
                 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 ((0, arkts_1.isOhosApiFilePath)(r.node.filePath))
+                        continue;
+                    const nameLc = r.node.name.toLowerCase();
+                    const pathLc = r.node.filePath.toLowerCase();
+                    const sigLc = (r.node.signature || '').toLowerCase();
+                    const nameHit = nameLc.includes(termLc);
+                    const pathHit = pathLc.includes(termLc);
+                    const sigHit = sigLc.includes(termLc);
+                    // Verb-only hits need path affinity; imports for verbs are dropped when
+                    // distinctive tokens exist (handled by ranked list above).
+                    if (termIsVerb && !pathHit)
+                        continue;
+                    // Distinctive token: require name/path/signature to actually mention it
+                    // (drops FTS neighbors that only share an unrelated Parser suffix).
+                    if (!termIsVerb && distinctive.length > 0 && !nameHit && !pathHit && !sigHit)
+                        continue;
+                    const entryOk = r.node.kind === 'import'
+                        || ((r.node.kind === 'function' || r.node.kind === 'method' || r.node.kind === 'class'
+                            || r.node.kind === 'interface' || r.node.kind === 'struct')
+                            && (nameHit || pathHit));
                     if (!entryOk)
                         continue;
                     addNode(r.node);
-                    if (seedIds.size >= 10)
+                    if (seedIds.size >= 16)
                         break;
                 }
-                if (seedIds.size >= 10)
+                if (seedIds.size >= 12)
                     break;
             }
+            // Prefer seeds that mention a distinctive token when we have any.
+            if (distinctive.length > 0 && seedIds.size > 0) {
+                const keep = new Set();
+                for (const id of seedIds) {
+                    const n = cg.getNode(id);
+                    if (!n)
+                        continue;
+                    const line = n.kind === 'import' ? (0, query_utils_1.resolveImportLineFromNode)(n, projectRoot) : '';
+                    const blob = `${n.name}\n${n.filePath}\n${n.signature || ''}\n${line}`.toLowerCase();
+                    if (distinctive.some((t) => blob.includes(t.toLowerCase())))
+                        keep.add(id);
+                }
+                if (keep.size > 0) {
+                    for (const id of [...seedIds]) {
+                        if (!keep.has(id)) {
+                            seedIds.delete(id);
+                        }
+                    }
+                    for (const [fp, nodes] of [...fileNodes.entries()]) {
+                        const filtered = nodes.filter((n) => keep.has(n.id));
+                        if (filtered.length === 0)
+                            fileNodes.delete(fp);
+                        else
+                            fileNodes.set(fp, filtered);
+                    }
+                }
+            }
         }
         if (seedIds.size === 0)
             return null;
@@ -3424,18 +4438,109 @@ class ToolHandler {
         const lines = [
             `**Exploration: ${query}**`,
             '',
+            '> **ANSWER NOW from this response.** Do **not** Grep or Read listed files in parallel — Source below is authoritative.',
+            '',
             `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);
+        // Import inventory: prefer concrete API seeds (convertxml / XmlParseUtil) over
+        // bare domain tokens like `xml` that flood every path containing the substring.
+        const seedImportFocus = (0, query_utils_1.extractMechanismEntrySeeds)(query).filter((s) => !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(s.toLowerCase())
+            && (s.length >= 6 || /convert|xml|parse|manager|service/i.test(s)));
+        const distinctiveDeps = (0, query_utils_1.extractDependencySymbolsFromQuery)(query)
+            .filter((s) => !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(s.toLowerCase()));
+        const importQuery = (seedImportFocus.length > 0
+            ? seedImportFocus
+            : distinctiveDeps.length > 0
+                ? distinctiveDeps
+                : (0, query_utils_1.extractDomainSearchTerms)(query)
+                    .filter((t) => /^[\x00-\x7F]+$/.test(t) && !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase()))).slice(0, 4).join(' ');
+        const importResult = importQuery
+            ? this.buildImportSitesSection(cg, importQuery, projectRoot)
+            : { section: '', siteCount: 0, compactListing: false };
+        // Light path: keep ≤8 import bullets (full inventory belongs to kit/API surveys).
+        if (importResult.section) {
+            const trimmed = this.trimLightImportSection(importResult.section, 8);
+            if (trimmed)
+                lines.push(trimmed);
+        }
         if (flow.text)
             lines.push(flow.text);
+        // Shared-lib + GLES/EGL thread: surface CMake link lines before bodies.
+        if ((0, query_utils_1.queryAsNativeRenderThreadSurvey)(query)) {
+            const cmakeHits = [];
+            try {
+                for (const f of cg.getFiles()) {
+                    const fp = f.path.replace(/\\/g, '/');
+                    if (!/CMakeLists\.txt$/i.test(fp))
+                        continue;
+                    if (!/foldeffect|effectrender|render|egl/i.test(fp) && (0, query_utils_1.extractPathSegmentsFromQuery)(query).length > 0) {
+                        const segs = (0, query_utils_1.extractPathSegmentsFromQuery)(query);
+                        if (!segs.some((s) => fp.toLowerCase().includes(s.toLowerCase().split('/').pop() || s))) {
+                            // still allow any CMake with GLESv3/EGL
+                        }
+                    }
+                    const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, f.path);
+                    if (!abs)
+                        continue;
+                    let content = '';
+                    try {
+                        content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!/GLES|EGL|OpenGL/i.test(content))
+                        continue;
+                    const fileLines = content.split('\n');
+                    for (let i = 0; i < fileLines.length; i++) {
+                        const line = fileLines[i] ?? '';
+                        if (/GLES|EGL|OpenGL|target_link|pthread|thread/i.test(line)) {
+                            cmakeHits.push(`- \`${fp}:${i + 1}\`  \`${line.trim().slice(0, 100)}\``);
+                        }
+                    }
+                    if (cmakeHits.length >= 12)
+                        break;
+                }
+            }
+            catch { /* optional */ }
+            if (cmakeHits.length > 0) {
+                lines.push('**CMake / link + GL libs**', '');
+                lines.push(...cmakeHits.slice(0, 12));
+                lines.push('');
+            }
+        }
+        const distinctiveForScore = (0, query_utils_1.extractDomainSearchTerms)(query).filter((t) => /^[\x00-\x7F]+$/.test(t) && !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase()));
+        const apiSeeds = (0, query_utils_1.extractMechanismEntrySeeds)(query).map((s) => s.toLowerCase());
         const fileScores = new Map();
         for (const [fp, nodes] of fileNodes) {
+            if ((0, arkts_1.isOhosApiFilePath)(fp))
+                continue;
             let score = 0;
+            const fpLc = fp.toLowerCase();
+            if (distinctiveForScore.some((t) => fpLc.includes(t.toLowerCase())))
+                score += 30;
+            // Prefer real wrappers (XmlParseUtil / convertxml) over incidental Xml* paths.
+            if (apiSeeds.some((s) => s.length >= 6 && fpLc.includes(s)))
+                score += 40;
+            if (/convertxml|xmlparseutil/i.test(fpLc))
+                score += 50;
             for (const n of nodes) {
+                const line = n.kind === 'import' ? (0, query_utils_1.resolveImportLineFromNode)(n, projectRoot) : '';
+                const blob = `${n.name}\n${n.signature || ''}\n${line}`.toLowerCase();
+                if (distinctiveForScore.some((t) => blob.includes(t.toLowerCase())))
+                    score += 20;
+                if (apiSeeds.some((s) => s.length >= 6 && blob.includes(s)))
+                    score += 25;
+                if (n.kind === 'import'
+                    && distinctiveForScore.some((t) => {
+                        const tLc = t.toLowerCase();
+                        return (line.includes(tLc) || blob.includes(tLc)) && (line.includes('@ohos.') || line.includes('@kit.'));
+                    })) {
+                    score += 20;
+                }
+                if (/convertxml|@kit\.|@ohos\./i.test(line))
+                    score += 30;
                 if (flow.pathNodeIds.has(n.id))
                     score += 20;
                 else if (flow.uniqueNamedNodeIds.has(n.id))
@@ -3448,17 +4553,17 @@ class ToolHandler {
         const sortedFiles = [...fileScores.entries()]
             .filter(([, s]) => s > 0)
             .sort((a, b) => b[1] - a[1])
-            .slice(0, 4);
+            .slice(0, 3);
         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('> Line-numbered source below — treat as already Read. Do **not** grep/read/`homegraph_node` these files again.');
         lines.push('');
         let totalChars = lines.join('\n').length;
         let filesRendered = 0;
         for (const [fp] of sortedFiles) {
-            if (filesRendered >= 4 || totalChars > 14_000)
+            // Token budget: light howto must stay ~3–5k so explore+answer can beat Grep/Read.
+            if (filesRendered >= 2 || totalChars > 4_800)
                 break;
-            const chunk = this.renderLightMechanismSource(projectRoot, fp, fileNodes.get(fp) ?? [], 4000);
+            const chunk = this.renderLightMechanismSource(projectRoot, fp, fileNodes.get(fp) ?? [], 2000);
             if (!chunk)
                 continue;
             lines.push(chunk);
@@ -3468,11 +4573,35 @@ class ToolHandler {
         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('> **Mechanism explore complete — ANSWER NOW.** Sections above cover the wired mechanism. ' +
+            'Do **not** call `homegraph_node`, Read, or Grep for symbols/files already shown (that multiplies tokens). ' +
+            'Only one tighter `homegraph_explore` if a **named** symbol essential to the answer is still missing.');
         lines.push('');
         return this.textResult(lines.join('\n'));
     }
+    /** Cap import bullets inside a light-mechanism response. */
+    trimLightImportSection(section, maxBullets) {
+        const lines = section.split('\n');
+        const out = [];
+        let bullets = 0;
+        let truncated = false;
+        for (const line of lines) {
+            if (line.startsWith('- `')) {
+                if (bullets >= maxBullets) {
+                    truncated = true;
+                    continue;
+                }
+                bullets++;
+            }
+            if (/^\s*- … and \d+ more/i.test(line))
+                continue;
+            out.push(line);
+        }
+        if (truncated) {
+            out.push(`- … (light-mechanism: showing ${maxBullets} sites — **ANSWER NOW**, do not Grep the same import)`);
+        }
+        return out.join('\n');
+    }
     /**
      * Compact explore for local-symbol behavior questions — skips findRelevantContext
      * and caps to 1–2 defining files (avoids the ~24K related-file dump).
@@ -3485,8 +4614,26 @@ class ToolHandler {
         // 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.
+        // Mechanism / domain-mechanism bags belong to light-mechanism (or full explore),
+        // never compact — agents rewrite "如何实现 xml 解析" to "xml parse" and would
+        // otherwise seed every method named `parse`.
+        // Light-mechanism owns domain howtos. Bare "how/如何" NL must NOT veto compact
+        // when a local/flag/lifecycle shape already owns the query (flag impact was
+        // falling through to a 20k Dynamic-dispatch dump).
+        if ((0, query_utils_1.shouldTryLightMechanismExplore)(query))
+            return null;
+        if ((0, query_utils_1.queryAsMechanismSurvey)(query)
+            && !(0, query_utils_1.queryAsLocalSymbolDetail)(query)
+            && !(0, query_utils_1.queryAsAssignedFlagImpactSurvey)(query)
+            && !(0, query_utils_1.queryAsTypeLifecycleSurvey)(query)) {
+            return null;
+        }
         const bareId = /^[A-Za-z_][\w]*$/.test(query.trim());
-        if (!(0, query_utils_1.queryAsLocalSymbolDetail)(query) && !bareId && !(0, query_utils_1.queryHasFocusedNamedAnchors)(query)) {
+        if (!(0, query_utils_1.queryAsLocalSymbolDetail)(query)
+            && !(0, query_utils_1.queryAsFocusedUiCluster)(query)
+            && !(0, query_utils_1.queryAsComponentSurfaceSurvey)(query)
+            && !bareId
+            && !(0, query_utils_1.queryHasFocusedNamedAnchors)(query)) {
             return null;
         }
         const STRUCTURE_KINDS = new Set([
@@ -3496,17 +4643,28 @@ class ToolHandler {
         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.
+        // Multi-anchor bags that form a Flow / Dynamic-dispatch section normally fall
+        // through to full explore. EXCEPT focused UI Type clusters / local-detail /
+        // Type.member — full explore is a 15–30k dump for a local composition question.
+        const stayOnCompact = (0, query_utils_1.queryAsFocusedUiCluster)(query)
+            || (0, query_utils_1.queryAsComponentSurfaceSurvey)(query)
+            || (0, query_utils_1.queryAsNamedComponentAction)(query)
+            || (0, query_utils_1.queryHasNamedMemberFocus)(query)
+            || (0, query_utils_1.queryAsLocalSymbolDetail)(query);
         const rawTokens = query.split(/[\s,()[\]]+/).filter((t) => t.length >= 3 && /^[A-Za-z_][\w]*$/.test(t));
+        // Multi-anchor: prefer full explore when Flow / Dynamic-dispatch has content.
+        // Type.member / UI-cluster bags stay on compact UNLESS the flow surfaces
+        // @Prop/@Link state transfers — those hops are the answer for decorator
+        // dependency questions and must not be buried under a compact UI trail.
         if (names.length >= 2 || rawTokens.length >= 2) {
             try {
                 const flow = this.buildFlowFromNamedSymbols(cg, query);
-                if (flow.text.length > 0)
-                    return null;
+                if (flow.text.length > 0) {
+                    if (!stayOnCompact)
+                        return null;
+                    if (/state: @(?:Prop|Link)\b/.test(flow.text))
+                        return null;
+                }
             }
             catch {
                 // Probe is best-effort — stay on compact if flow build fails.
@@ -3525,9 +4683,95 @@ class ToolHandler {
                 list.push(n);
             fileNodes.set(n.filePath, list);
         };
+        const typeNames = (0, query_utils_1.extractTypeNamesFromQuery)(query).filter((t) => !(0, query_utils_1.isFrameworkUiDecoratorName)(t));
+        const typeNameSet = new Set(typeNames.map((t) => t.toLowerCase()));
+        const bridge = (0, query_utils_1.queryNeedsCoNamedUseBridge)(query);
+        const memberFocus = (0, query_utils_1.queryHasNamedMemberFocus)(query);
+        const uiCluster = (0, query_utils_1.queryAsFocusedUiCluster)(query);
+        const typeLifecycle = (0, query_utils_1.queryAsTypeLifecycleSurvey)(query);
+        const componentSurface = (0, query_utils_1.queryAsComponentSurfaceSurvey)(query)
+            || uiCluster
+            || typeLifecycle
+            || names.some(query_utils_1.queryLooksLikeUiComponentType);
+        // Page/Dialog surface & UI clusters: trail only — pulling callee files ballooned
+        // ThemeHome-style answers by 5–10k without adding the UI-child / nav answer.
+        const surfaceTrailOnly = (componentSurface || uiCluster || typeLifecycle) && !memberFocus
+            && !(0, query_utils_1.queryAsNamedComponentAction)(query);
+        const bareMemberOnly = bareId && (0, query_utils_1.isMemberLikeIdentifier)(query.trim());
+        const ownedByNamedType = (n) => {
+            if (typeNameSet.size === 0)
+                return true;
+            const qn = (n.qualifiedName || '').toLowerCase();
+            if ([...typeNameSet].some((t) => qn === t || qn.startsWith(`${t}.`) || qn.startsWith(`${t}::`) || qn.includes(`::${t}.`) || qn.endsWith(`::${t}`))) {
+                return true;
+            }
+            // Same file as a named type definition.
+            try {
+                for (const t of typeNames) {
+                    for (const owner of cg.getNodesByName(t)) {
+                        if ((owner.kind === 'class' || owner.kind === 'struct' || owner.kind === 'interface' || owner.kind === 'component')
+                            && owner.filePath === n.filePath) {
+                            return true;
+                        }
+                    }
+                }
+            }
+            catch { /* */ }
+            return false;
+        };
         for (const seed of names) {
-            for (const n of cg.getNodesByName(seed)) {
+            const candidates = cg.getNodesByName(seed);
+            const preferOwned = memberFocus
+                && (0, query_utils_1.isMemberLikeIdentifier)(seed)
+                && typeNameSet.size > 0;
+            // Prefer in-repo implementations over SDK `.d.ts` / @ohos API stubs when both exist.
+            const projectFirst = [...candidates].sort((a, b) => {
+                const score = (n) => {
+                    let s = 0;
+                    if ((0, arkts_1.isOhosApiFilePath)(n.filePath) || /\.d\.ts$/i.test(n.filePath))
+                        s -= 50;
+                    if ((0, query_utils_1.isTestFile)(n.filePath))
+                        s -= 20;
+                    if (n.kind === 'class' || n.kind === 'struct' || n.kind === 'component')
+                        s += 5;
+                    return s;
+                };
+                return score(b) - score(a);
+            });
+            const filtered = preferOwned
+                ? (() => {
+                    const owned = projectFirst.filter(ownedByNamedType);
+                    return owned.length > 0 ? owned : projectFirst;
+                })()
+                : projectFirst;
+            for (const n of filtered) {
+                // Skip SDK stubs when a project definition of the same name exists.
+                if (((0, arkts_1.isOhosApiFilePath)(n.filePath) || /\.d\.ts$/i.test(n.filePath))
+                    && filtered.some((o) => o.name === n.name
+                        && !(0, arkts_1.isOhosApiFilePath)(o.filePath)
+                        && !/\.d\.ts$/i.test(o.filePath))) {
+                    continue;
+                }
                 addNode(n);
+                // Page/Component surface digests need build/aboutToAppear as their own
+                // nodes — otherwise we only have the outer struct and dump the whole body.
+                if (componentSurface || uiCluster || typeLifecycle) {
+                    if (n.kind === 'component' || n.kind === 'class' || n.kind === 'struct') {
+                        try {
+                            for (const e of cg.getOutgoingEdges(n.id)) {
+                                if (e.kind !== 'contains')
+                                    continue;
+                                const child = cg.getNode(e.target);
+                                if (child
+                                    && (child.kind === 'method' || child.kind === 'function')
+                                    && isUiSurfaceDigestMethod(child.name, uiCluster)) {
+                                    addNode(child);
+                                }
+                            }
+                        }
+                        catch { /* */ }
+                    }
+                }
                 if (seedIds.size >= 12)
                     break;
             }
@@ -3554,33 +4798,69 @@ class ToolHandler {
         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
+        // - Type.member / UI action / pinpoint local-detail: callers + callees
+        // - Type.member: expand on the *member* (isExpired), not only the Type, and
+        //   do not path-filter callers — UI marking often lives in another package.
+        const callersOnly = surfaceTrailOnly
+            || bareMemberOnly
+            || (bareId && !componentSurface)
             || bridge
-            || ((0, query_utils_1.shouldBuildCallerInventory)(query) && !(0, query_utils_1.queryAsNamedComponentAction)(query));
+            || ((0, query_utils_1.shouldBuildCallerInventory)(query) && !(0, query_utils_1.queryAsNamedComponentAction)(query) && !memberFocus && !componentSurface)
+            // Conditional wiring ("失败时还会…") — method body + callers, not logInfo fan-out.
+            || /失败时|还会被注册|还会被|still\s+(?:be\s+)?(?:register|call)|if\s+.+\s+fails?/i.test(query);
         const primaryName = names[0];
+        const memberNames = new Set([
+            ...(0, query_utils_1.extractMemberAccessFromQuery)(query).map((m) => m.member),
+            ...names.filter((n) => (0, query_utils_1.isMemberLikeIdentifier)(n)),
+        ]);
+        // UI Type clusters: expand every named *Page/*Dialog seed — not only the first
+        // token — so Page↔Dialog composition stays in one compact answer.
+        const expandNameSet = new Set(uiCluster || componentSurface
+            ? [...typeNames, primaryName]
+            : [primaryName]);
         const expandIds = [...seedIds].filter((id) => {
             try {
-                return cg.getNode(id)?.name === primaryName;
+                const n = cg.getNode(id);
+                if (!n)
+                    return false;
+                if (memberFocus && memberNames.size > 0)
+                    return memberNames.has(n.name);
+                return expandNameSet.has(n.name);
             }
             catch {
                 return false;
             }
         });
+        // Fall back to primary type seeds if member name wasn't indexed as its own node.
+        const expandIdsFinal = expandIds.length > 0
+            ? 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) {
+        for (const id of expandIdsFinal) {
             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))
+                for (const { node: c } of cg.getCallers(id).slice(0, callersOnly ? 8 : 12)) {
+                    // Type.member / UI-marking: keep cross-package callers (path filter drops them).
+                    if (!memberFocus
+                        && !(0, query_utils_1.queryAsNamedComponentAction)(query)
+                        && !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
@@ -3591,8 +4871,16 @@ class ToolHandler {
                 }
                 if (!callersOnly) {
                     for (const { node: c } of cg.getCallees(id).slice(0, 10)) {
-                        if (!nearSeed(c.filePath) && seedPath && !pathAffinity(seedPath, c.filePath))
+                        // Skip log*/hilog helpers — Export→logInfo homonyms ballooned seeds.
+                        if (/^log(?:Info|Error|Warn|Debug|Fatal)?$/i.test(c.name) || /^hilog$/i.test(c.name)) {
                             continue;
+                        }
+                        if (!memberFocus
+                            && !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);
@@ -3607,6 +4895,8 @@ class ToolHandler {
         const lines = [
             `**Exploration: ${query}**`,
             '',
+            '> **ANSWER NOW from this response.** Do **not** Grep/Read/search/explore/node/callers for the same symbols — trail + Source below are authoritative.',
+            '',
             `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).',
@@ -3637,7 +4927,7 @@ class ToolHandler {
         {
             const trail = ['**Call / use trail**', ''];
             let trailBullets = 0;
-            const trailIds = (callersOnly ? expandIds : [...seedIds]).slice(0, 6);
+            const trailIds = (callersOnly ? expandIdsFinal : [...seedIds]).slice(0, 6);
             for (const id of trailIds) {
                 let seedNode;
                 try {
@@ -3651,7 +4941,7 @@ class ToolHandler {
                 let callers = [];
                 let callees = [];
                 try {
-                    callers = cg.getCallers(id).slice(0, 8);
+                    callers = cg.getCallers(id).slice(0, memberFocus ? 12 : 8);
                 }
                 catch { /* */ }
                 if (!callersOnly) {
@@ -3660,8 +4950,10 @@ class ToolHandler {
                     }
                     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 (!memberFocus) {
+                    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}`);
@@ -3678,7 +4970,7 @@ class ToolHandler {
             }
             if (trailBullets > 0) {
                 trail.push('');
-                trail.push('> Prefer answering from this trail + Source below. Do not grep/search the same symbols again.');
+                trail.push('> **ANSWER NOW** from this trail + Source below. Do not grep/search/read the same symbols again.');
                 trail.push('');
                 lines.push(...trail);
             }
@@ -3689,15 +4981,20 @@ class ToolHandler {
         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));
+        const needUsageScan = !componentSurface
+            && (neighborIds.size === 0
+                || memberFocus
+                || /上下游|上游|下游|注册|挂到|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);
+            // Prefer member-like names for Type.member UI questions (isExpired over Type).
+            const scanNames = memberFocus && memberNames.size > 0
+                ? [...memberNames].slice(0, 3)
+                : names.slice(0, 3);
             if (scanNames.length > 0) {
                 try {
                     const defLineKeys = new Set();
@@ -3707,57 +5004,90 @@ class ToolHandler {
                                 defLineKeys.add(`${n.filePath}:${n.startLine}`);
                         }
                     }
-                    const defDirs = new Set([...fileNodes.keys()].map((fp) => fp.split('/').slice(0, 4).join('/')));
+                    const norm = (fp) => fp.replace(/\\/g, '/');
+                    const defDirs = new Set([...fileNodes.keys()].map((fp) => norm(fp).split('/').slice(0, 4).join('/')));
+                    // Large monorepos: never rely on getFiles() order + hard slice — Type.member
+                    // call sites (LauncherCardInfo.isExpired filters) live near the defining
+                    // package and must be scanned first or Grep wins.
+                    const rankScanFile = (fp) => {
+                        const n = norm(fp);
+                        let score = 0;
+                        if ([...defDirs].some((d) => n === d || n.startsWith(`${d}/`)))
+                            score += 100;
+                        if (typeSeeds.some((t) => n.toLowerCase().includes(t.toLowerCase())))
+                            score += 40;
+                        return score;
+                    };
                     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)
+                        .filter((fp) => !isTestPath(fp))
+                        .map((fp) => ({ fp, score: rankScanFile(fp) }))
+                        .sort((a, b) => b.score - a.score || a.fp.localeCompare(b.fp))
+                        .map((x) => x.fp);
+                    const hitCap = bareMemberOnly ? 6 : memberFocus ? 10 : 8;
+                    const scanFileList = (list, requireTypeMention) => {
+                        for (const fp of list) {
+                            if (textUsageHits.length >= hitCap)
+                                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;
+                            }
+                            if (requireTypeMention
+                                && typeSeeds.length > 0
+                                && !typeSeeds.some((t) => content.includes(t))) {
+                                continue;
+                            }
+                            // Prefer files that also mention a co-named type when both present
+                            // (skip for single-anchor upstream/registration scans and Type.member).
+                            if (!memberFocus
+                                && 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; prefer Type.member when typed.
+                                const typeAlt = typeSeeds.length > 0
+                                    ? `(?:\\b(?:${typeSeeds.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\.)?`
+                                    : '';
+                                const re = new RegExp(`${typeAlt}\\b${escaped}\\b`);
+                                const defRe = new RegExp(`^\\s*(?:export\\s+|public\\s+|private\\s+|protected\\s+|static\\s+|async\\s+)*${escaped}\\s*\\(`);
+                                for (let i = 0; i < fileLines.length; i++) {
+                                    const lineText = fileLines[i] ?? '';
+                                    if (!re.test(lineText))
+                                        continue;
+                                    if (defLineKeys.has(`${fp}:${i + 1}`))
+                                        continue;
+                                    // Skip the method's own definition line (no Type. prefix / no call punctuation).
+                                    if (defRe.test(lineText) && !lineText.includes(`.${sym}`))
+                                        continue;
+                                    textUsageHits.push({ filePath: fp, line: i + 1, text: lineText.trim(), symbol: sym });
+                                    if (!fileNodes.has(fp))
+                                        fileNodes.set(fp, []);
+                                    if (textUsageHits.length >= hitCap)
+                                        break;
+                                }
+                                if (textUsageHits.length >= hitCap)
                                     break;
                             }
-                            if (textUsageHits.length >= 12)
-                                break;
                         }
+                    };
+                    // Pass 1: same package / type-path affinity (score > 0), require Type mention when known.
+                    const nearFiles = files.filter((fp) => rankScanFile(fp) > 0).slice(0, memberFocus ? 80 : 40);
+                    scanFileList(nearFiles, memberFocus && typeSeeds.length > 0);
+                    // Pass 2: broader if still empty / thin (still bounded).
+                    if (textUsageHits.length < 3) {
+                        const rest = files.filter((fp) => rankScanFile(fp) === 0).slice(0, memberFocus ? 160 : 80);
+                        scanFileList(rest, false);
                     }
                 }
                 catch {
@@ -3770,9 +5100,14 @@ class ToolHandler {
                     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(memberFocus
+                    ? '> These lines are the in-repo **call/filter sites** for the named member. **ANSWER NOW** from them + Source — do not Grep/`homegraph_callers` the same member.'
+                    : '> These lines are the in-repo use sites. Answer from them + Source; do not grep the same names again.');
                 lines.push('');
             }
+            else if (memberFocus) {
+                lines.push('> No in-repo text call sites found for this member beyond its definition. Answer from Source; avoid a broad Grep unless needed.', '');
+            }
         }
         // Also surface #include / import lines that make a co-named type visible
         // near the primary symbol's use sites (IntGrid ↔ SortWidgets shapes).
@@ -3827,39 +5162,72 @@ class ToolHandler {
             }
         }
         const callerSection = (0, query_utils_1.shouldBuildCallerInventory)(query)
-            ? this.buildCallerListingSection(cg, query)
+            ? this.buildCallerListingSection(cg, query, projectRoot)
             : '';
         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.
+        // UI clusters: co-occurrence of 2+ named Types beats a lonely homonym elsewhere.
         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 maxFiles = bareMemberOnly
+            ? 2
+            : memberFocus
+                // Call/filter sites already listed above — dumping caller file bodies
+                // (FormStack…) burns tokens and invites a follow-up Read of isExpired.
+                ? 1
+                : ((0, query_utils_1.queryAsNamedComponentAction)(query) || componentSurface || usageFiles.size > 0 || bridge)
+                    ? (uiCluster ? 2 : (componentSurface ? 2 : 3))
+                    : 2;
         const ranked = [...fileNodes.entries()]
+            .filter(([, nodes]) => {
+            if (!memberFocus || memberNames.size === 0)
+                return true;
+            return nodes.some((n) => memberNames.has(n.name) || typeNameSet.has(n.name.toLowerCase()));
+        })
             .map(([fp, nodes]) => {
             const exact = nodes.filter((n) => nameSet.has(n.name)).length;
+            const typeHits = typeNames.filter((t) => nodes.some((n) => n.name === t)).length;
+            const clusterCoOccur = typeHits >= 2 ? 250 : typeHits === 1 ? 80 : 0;
             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;
+            const usageHit = usageFiles.has(fp) ? (memberFocus ? 60 : 15) : 0;
             return {
                 fp,
                 nodes,
                 exact,
-                score: primaryHit + exact * 20 + neighborHit * 5 + usageHit + nodes.length,
+                score: (uiCluster || componentSurface ? clusterCoOccur : 0)
+                    + 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('> Line-numbered source — treat as already Read. **ANSWER NOW** — do not Read/Grep/search/explore/node the same symbols again.');
         lines.push('');
         let totalChars = lines.join('\n').length;
-        const maxTotal = 9000;
-        const maxPerFile = 4000;
+        // Lean ceilings: without-HG Grep/Read stacks were ~15k session tokens; a 10–14k
+        // compact body + follow-up Read is what loses the token A/B.
+        const maxTotal = bareMemberOnly
+            ? 4500
+            : componentSurface || uiCluster
+                ? 7000
+                : memberFocus && usageFiles.size > 0
+                    ? 6500
+                    : 5500;
+        const maxPerFile = bareMemberOnly
+            ? 2800
+            : componentSurface || uiCluster
+                ? 4500
+                : memberFocus
+                    ? 2800
+                    : 3200;
         let rendered = 0;
         for (const { fp, nodes } of ranked) {
             if (rendered >= maxFiles || totalChars > maxTotal)
@@ -3883,23 +5251,114 @@ class ToolHandler {
             let start = 1;
             let end = Math.min(fileLines.length, 120);
             const usageLine = textUsageHits.find((h) => h.filePath === fp)?.line;
+            const surfaceMethodsRaw = (componentSurface || uiCluster)
+                ? focusNodes
+                    .filter((n) => (n.kind === 'method' || n.kind === 'function') && isUiSurfaceDigestMethod(n.name, uiCluster))
+                    .sort((a, b) => surfaceMethodPriority(a.name) - surfaceMethodPriority(b.name) || a.startLine - b.startLine)
+                : [];
+            // When build/PageMap answer the surface question, skip lifecycle — it ate
+            // the budget and agents re-Read PageMap anyway.
+            const hasBuildOrPageMap = surfaceMethodsRaw.some((n) => /^(build|PageMap)$/i.test(n.name));
+            const surfaceMethods = hasBuildOrPageMap
+                ? surfaceMethodsRaw.filter((n) => !/^(aboutToAppear|aboutToDisappear)$/i.test(n.name))
+                : surfaceMethodsRaw;
+            // Type.member: keep the member body, not the whole owning class dump.
+            const memberOnlyNodes = memberFocus && memberNames.size > 0
+                ? focusNodes.filter((n) => memberNames.has(n.name) && (n.kind === 'method' || n.kind === 'function' || n.kind === 'property' || n.kind === 'field'))
+                : [];
             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) {
+                const surfaceNodes = componentSurface
+                    ? use.filter((n) => (n.kind === 'component' || n.kind === 'class' || n.kind === 'struct'
+                        || (0, query_utils_1.queryLooksLikeUiComponentType)(n.name))
+                        && (typeNameSet.size === 0 || typeNameSet.has(n.name.toLowerCase()) || nameSet.has(n.name)))
+                    : [];
+                if (surfaceNodes.length === 0 && componentSurface) {
+                    const one = use.find((n) => n.kind === 'component' || n.kind === 'class' || n.kind === 'struct'
+                        || (0, query_utils_1.queryLooksLikeUiComponentType)(n.name)) ?? use[0];
+                    if (one)
+                        surfaceNodes.push(one);
+                }
+                if (memberOnlyNodes.length > 0) {
+                    start = Math.max(1, Math.min(...memberOnlyNodes.map((n) => n.startLine)) - 2);
+                    end = Math.min(fileLines.length, Math.max(...memberOnlyNodes.map((n) => n.endLine)) + 2);
+                }
+                else if (surfaceMethods.length > 0) {
+                    // Per-method chunks below — placeholder window unused.
+                    start = 1;
+                    end = 1;
+                }
+                else if (surfaceNodes.length > 0 && surfaceNodes.some((n) => n.endLine > n.startLine)) {
+                    start = Math.max(1, Math.min(...surfaceNodes.map((n) => n.startLine)) - 2);
+                    end = Math.min(fileLines.length, Math.max(...surfaceNodes.map((n) => n.endLine)) + 2);
+                }
+                else {
+                    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 (non-surface paths)
+                if (surfaceMethods.length === 0 && (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);
+                start = Math.max(1, usageLine - 10);
+                end = Math.min(fileLines.length, usageLine + 18);
             }
             const header = fileSectionHeader(fp, focusNodes.map((n) => `${n.name}(${n.kind})`).slice(0, 6).join(', '));
             const withLineNumbers = exploreLineNumbersEnabled();
             const bodyLines = [header, '```' + (nodes[0]?.language || ''), ''];
+            if (surfaceMethods.length > 0) {
+                // Do NOT span aboutToAppear→build as one window — ThemeHome-sized pages
+                // always trim before PageMap/build. Emit imports + each method separately,
+                // prioritizing build/PageMap/preview.
+                let lastImportLine = 0;
+                for (let i = 0; i < Math.min(fileLines.length, 60); i++) {
+                    if (/^\s*import\s+/.test(fileLines[i] ?? ''))
+                        lastImportLine = i + 1;
+                }
+                const inventory = extractUiSurfaceInventory(fileLines, surfaceMethods);
+                // Inventory is prepended outside the code fence below via chunk assembly.
+                const methodBudget = Math.max(900, Math.floor((maxPerFile - Math.min(lastImportLine, 40) * 40) / Math.max(1, Math.min(surfaceMethods.length, 4))));
+                if (lastImportLine > 0) {
+                    const importCap = Math.min(lastImportLine, 45);
+                    for (let i = 1; i <= importCap; i++) {
+                        const code = fileLines[i - 1] ?? '';
+                        bodyLines.push(withLineNumbers ? `${i}\t${code}` : code);
+                    }
+                    bodyLines.push(withLineNumbers ? `…\t// …` : '// …');
+                }
+                let methodsEmitted = 0;
+                for (const m of surfaceMethods) {
+                    if (methodsEmitted >= 5)
+                        break;
+                    const mStart = Math.max(1, m.startLine - 1);
+                    let mEnd = Math.min(fileLines.length, m.endLine + 1);
+                    // Cap each method so later build/PageMap still fit.
+                    const maxLines = Math.max(25, Math.floor(methodBudget / 40));
+                    if (mEnd - mStart + 1 > maxLines) {
+                        mEnd = mStart + maxLines - 1;
+                    }
+                    bodyLines.push(withLineNumbers ? `…\t// --- ${m.name} ---` : `// --- ${m.name} ---`);
+                    for (let i = mStart; i <= mEnd; i++) {
+                        const code = fileLines[i - 1] ?? '';
+                        bodyLines.push(withLineNumbers ? `${i}\t${code}` : code);
+                    }
+                    methodsEmitted++;
+                }
+                bodyLines.push('```', '');
+                let chunk = (inventory ? inventory + '\n' : '') + bodyLines.join('\n');
+                if (chunk.length > maxPerFile + (inventory ? 1200 : 0)) {
+                    chunk = `${chunk.slice(0, maxPerFile + (inventory ? 1200 : 0))}\n... (trimmed — answer from inventory + visible methods; do not Read the rest)\n\`\`\`\n`;
+                }
+                if (totalChars + chunk.length > maxTotal && rendered > 0)
+                    break;
+                lines.push(chunk);
+                totalChars += chunk.length;
+                rendered++;
+                continue;
+            }
             for (let i = start; i <= end; i++) {
                 const code = fileLines[i - 1] ?? '';
                 bodyLines.push(withLineNumbers ? `${i}\t${code}` : code);
@@ -3907,7 +5366,7 @@ class ToolHandler {
             bodyLines.push('```', '');
             let chunk = bodyLines.join('\n');
             if (chunk.length > maxPerFile) {
-                chunk = `${chunk.slice(0, maxPerFile)}\n... (trimmed)\n\`\`\`\n`;
+                chunk = `${chunk.slice(0, maxPerFile)}\n... (trimmed — answer from visible lines; do not Read the rest)\n\`\`\`\n`;
             }
             if (totalChars + chunk.length > maxTotal && rendered > 0)
                 break;
@@ -3918,11 +5377,100 @@ class ToolHandler {
         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('> **Compact local explore complete — ANSWER NOW.** ' +
+            'Do **not** Read/Grep/`homegraph_search`/`homegraph_explore`/`homegraph_node` for the same symbols.');
         lines.push('');
         return this.textResult(lines.join('\n'));
     }
+    /**
+     * Hover / pointer-handler inventory — onHover / Hover* symbols + short snippets.
+     * Used when the agent asks about hover effects without naming a Type yet.
+     */
+    buildHoverHandlerSurveySection(cg, query, projectRoot) {
+        const topicBoost = /图标|icon|appicon|dock|launcher/i.test(query);
+        const searchTerms = ['onHover', 'HoverAnimation', 'HoverEffect', 'HoverConstants', 'hover'];
+        const seen = new Set();
+        const hits = [];
+        for (const term of searchTerms) {
+            let results = [];
+            try {
+                results = cg.searchNodes(term, {
+                    kinds: ['method', 'function', 'property', 'field', 'variable', 'constant', 'class', 'component'],
+                    limit: 30,
+                });
+            }
+            catch {
+                continue;
+            }
+            for (const r of results) {
+                if ((0, arkts_1.isOhosApiFilePath)(r.node.filePath) || (0, query_utils_1.isTestFile)(r.node.filePath))
+                    continue;
+                const nameLc = r.node.name.toLowerCase();
+                const pathLc = r.node.filePath.toLowerCase();
+                const termLc = term.toLowerCase();
+                if (!nameLc.includes(termLc) && !pathLc.includes(termLc))
+                    continue;
+                const key = `${r.node.filePath}:${r.node.startLine}:${r.node.name}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                let score = nameLc === 'onhover' || nameLc.startsWith('onhover') ? 40 : 10;
+                if (/hover/.test(nameLc))
+                    score += 15;
+                if (topicBoost && /icon|appicon|dock|launcher|smartdock|appcenter/i.test(pathLc))
+                    score += 25;
+                let snippet = (r.node.signature || r.node.name).slice(0, 120);
+                try {
+                    const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                    if (abs && (0, fs_1.existsSync)(abs) && r.node.startLine > 0) {
+                        const lines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+                        const from = Math.max(0, r.node.startLine - 1);
+                        const to = Math.min(lines.length, from + 4);
+                        snippet = lines.slice(from, to).map((l) => l.trim()).filter(Boolean).join(' / ').slice(0, 160);
+                    }
+                }
+                catch { /* keep signature */ }
+                hits.push({
+                    file: r.node.filePath,
+                    line: r.node.startLine,
+                    name: r.node.name,
+                    kind: r.node.kind,
+                    score,
+                    snippet,
+                });
+            }
+        }
+        if (hits.length === 0) {
+            return {
+                section: [
+                    '**Hover / pointer handler survey**',
+                    '',
+                    'No `onHover` / Hover* handlers found in the indexed project graph.',
+                    '',
+                    '> Next: Grep `onHover` / `Hover` in `*.ets` if the index is incomplete.',
+                    '',
+                ].join('\n'),
+                hitCount: 0,
+            };
+        }
+        hits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+        const lines = [
+            '**Hover / pointer handler survey**',
+            '',
+            '> **ANSWER NOW** from these in-repo hover handlers + snippets. Do not Grep `onHover` again unless a named Type is still missing.',
+            '',
+        ];
+        const shown = hits.slice(0, 12);
+        for (const h of shown) {
+            lines.push(`- \`${h.name}\` (${h.kind}) — \`${h.file}:${h.line}\``);
+            if (h.snippet)
+                lines.push(`  \`${h.snippet.slice(0, 100)}\``);
+        }
+        if (hits.length > shown.length)
+            lines.push(`- … and ${hits.length - shown.length} more`);
+        lines.push('');
+        return { section: lines.join('\n'), hitCount: shown.length };
+    }
     /**
      * @kit module capability survey — repo import/usage only (SDK defs are not indexed).
      */
@@ -3963,11 +5511,49 @@ class ToolHandler {
             });
         };
         const resolveImportLine = (node) => (0, query_utils_1.resolveImportLineFromNode)(node, projectRoot);
+        const tryPushImport = (node) => {
+            if ((0, arkts_1.isOhosApiFilePath)(node.filePath))
+                return;
+            const lineText = resolveImportLine(node);
+            const lineLc = lineText.toLowerCase();
+            const symbols = parseImportedSymbols(lineText);
+            if (!matchesSubmodule(lineText, symbols))
+                return;
+            if (kitTerms.length > 0) {
+                const matchesKit = kitTerms.some((k) => lineLc.includes(`@kit.${k.toLowerCase()}`));
+                if (!matchesKit)
+                    return;
+            }
+            const key = `${node.filePath}:${node.startLine}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            imports.push({
+                file: node.filePath,
+                line: node.startLine,
+                lineText,
+                symbols,
+            });
+        };
+        // Prefer searching the named export/API (taskpool, util, …) — kit-only FTS
+        // with a low limit misses focused import sites among popular @kit modules.
+        const focusSearch = submodules.length > 0 ? submodules : [];
+        for (const sym of focusSearch) {
+            let hits = [];
+            try {
+                hits = cg.searchNodes(sym, { kinds: ['import'], limit: 200 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits)
+                tryPushImport(r.node);
+        }
         for (const term of kitSearchTerms) {
             const termLc = term.toLowerCase().replace(/^@kit\./, '');
             let hits = [];
             try {
-                hits = cg.searchNodes(term, { kinds: ['import'], limit: 80 });
+                hits = cg.searchNodes(term, { kinds: ['import'], limit: focusSearch.length > 0 ? 40 : 120 });
             }
             catch {
                 continue;
@@ -3976,19 +5562,7 @@ class ToolHandler {
                 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,
-                });
+                tryPushImport(r.node);
             }
         }
         if (imports.length === 0) {
@@ -4014,6 +5588,7 @@ class ToolHandler {
                 symbolFiles.set(sym, set);
             }
         }
+        const importCap = submodules.length > 0 ? 16 : 28;
         const lines = [
             '**Kit module usage (this repo)**',
             '',
@@ -4022,25 +5597,73 @@ class ToolHandler {
             `Imports from ${kitTerms.map((k) => `\`@kit.${k}\``).join(', ')} (${imports.length} site(s)):`,
             '',
         ];
-        for (const imp of imports.slice(0, 35)) {
+        for (const imp of imports.slice(0, importCap)) {
             const symStr = imp.symbols.length > 0 ? imp.symbols.join(', ') : '(namespace)';
-            lines.push(`- \`${imp.file}:${imp.line}\` — \`${imp.lineText}\` (${symStr})`);
+            lines.push(`- \`${imp.file}:${imp.line}\` — \`${imp.lineText.slice(0, 120)}\` (${symStr})`);
         }
-        if (imports.length > 35)
-            lines.push(`- … and ${imports.length - 35} more import site(s)`);
+        if (imports.length > importCap)
+            lines.push(`- … and ${imports.length - importCap} 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` : '';
+            const focused = submodules.length > 0
+                ? [...symbolFiles.entries()].filter(([sym]) => submodules.some((sm) => sym.toLowerCase() === sm.toLowerCase() || sym.toLowerCase().startsWith(`${sm.toLowerCase()}.`)))
+                : [...symbolFiles.entries()];
+            const ranked = (focused.length > 0 ? focused : [...symbolFiles.entries()])
+                .sort((a, b) => a[0].localeCompare(b[0]))
+                .slice(0, submodules.length > 0 ? 8 : 20);
+            for (const [sym, files] of ranked) {
+                const fileList = [...files].slice(0, 4).map((f) => `\`${f}\``).join(', ');
+                const more = files.size > 4 ? ` +${files.size - 4} files` : '';
                 lines.push(`- \`${sym}\` — imported in ${fileList}${more}`);
             }
         }
+        // "需要额外安装哪些依赖" — surface oh-package.json5 lines naming the kit.
+        if (/额外安装|还需.*依赖|需要.*依赖|install(?:ing)?\s+(?:extra\s+)?deps?|which\s+deps?/i.test(query)) {
+            const depLines = [];
+            try {
+                for (const f of cg.getFiles()) {
+                    const fp = f.path.replace(/\\/g, '/');
+                    if (!/oh-package\.json5?$/i.test(fp))
+                        continue;
+                    const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, f.path);
+                    if (!abs)
+                        continue;
+                    let content = '';
+                    try {
+                        content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!kitTerms.some((k) => content.toLowerCase().includes(k.toLowerCase())))
+                        continue;
+                    const fileLines = content.split('\n');
+                    for (let i = 0; i < fileLines.length; i++) {
+                        const line = fileLines[i] ?? '';
+                        if (!kitTerms.some((k) => line.toLowerCase().includes(k.toLowerCase())))
+                            continue;
+                        depLines.push(`- \`${fp}:${i + 1}\`  \`${line.trim().slice(0, 100)}\``);
+                    }
+                    if (depLines.length >= 16)
+                        break;
+                }
+            }
+            catch { /* optional */ }
+            lines.push('');
+            lines.push('**oh-package dependencies naming this Kit**');
+            if (depLines.length === 0) {
+                lines.push('- No `oh-package.json5` dependency line naming this Kit was indexed. ' +
+                    '**ANSWER NOW**: calling `@kit.*` typically needs **no extra npm install** beyond the HarmonyOS SDK / DevEco kit — only what `oh-package.json5` already lists.');
+            }
+            else {
+                lines.push(...depLines.slice(0, 16));
+            }
+        }
         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('> Kit usage survey complete — **ANSWER NOW** from this section; do not Grep `oh-package` / SDK docs again.');
         lines.push('');
-        return { section: lines.join('\n'), symbolCount: symbolFiles.size };
+        return { section: lines.join('\n'), symbolCount: Math.max(symbolFiles.size, imports.length, 1) };
     }
     /** Disambiguate homonymous types (Configuration, Rectangle) when several defs exist. */
     buildHomonymDefinitionsSection(cg, query) {
@@ -4072,20 +5695,51 @@ class ToolHandler {
         const rel = (p) => p.replace(/\\/g, '/');
         const lines = ['**Inheritance survey**', ''];
         let listed = 0;
+        const projectRoot = (() => {
+            try {
+                return cg.getProjectRoot();
+            }
+            catch {
+                return '';
+            }
+        })();
         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 = [];
+                const publicSubs = [];
+                const otherSubs = [];
                 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);
+                        if (!child || (0, query_utils_1.isTestFile)(child.filePath))
+                            continue;
+                        const isCpp = /\.(hpp|h|hh|hxx|cpp|cc|cxx)$/i.test(child.filePath);
+                        if (isCpp && projectRoot) {
+                            const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, child.filePath);
+                            if (abs && (0, fs_1.existsSync)(abs) && child.startLine > 0) {
+                                try {
+                                    const fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+                                    // Class decl may span a few lines (`class Foo\n: public Bar`).
+                                    const from = Math.max(0, child.startLine - 1);
+                                    const decl = fileLines.slice(from, Math.min(fileLines.length, from + 4)).join(' ');
+                                    const pub = cppExtendsLooksPublic(decl, base.name);
+                                    if (pub === false) {
+                                        otherSubs.push(child);
+                                        continue;
+                                    }
+                                }
+                                catch { /* keep as public-ish */ }
+                            }
+                        }
+                        publicSubs.push(child);
                     }
                     catch { /* skip */ }
                 }
+                // Prefer public / language-default is-a; only fall back to private if
+                // nothing else is indexed (avoids empty answers).
+                const subs = publicSubs.length > 0 ? publicSubs : otherSubs;
                 if (subs.length === 0)
                     continue;
                 lines.push(`### Subtypes of \`${base.name}\` (\`${rel(base.filePath)}\`)`);
@@ -4095,6 +5749,10 @@ class ToolHandler {
                 }
                 if (subs.length > 30)
                     lines.push(`- … and ${subs.length - 30} more`);
+                if (publicSubs.length > 0 && otherSubs.length > 0) {
+                    lines.push(`- _(also private/protected C++ inherits, omitted: ${otherSubs.map((s) => s.name).slice(0, 8).join(', ')})` +
+                        `${otherSubs.length > 8 ? ', …' : ''})_`);
+                }
                 lines.push('');
             }
         }
@@ -4120,6 +5778,10 @@ class ToolHandler {
         for (const m of query.matchAll(/(\.[a-zA-Z_][\w]*\s*\([^)]*\))/g)) {
             patterns.push(m[1].replace(/\s+/g, ''));
         }
+        // Bare field / mutex names (m_eglMutex) — text-scan without a leading dot.
+        for (const f of (0, query_utils_1.extractFieldLikeSymbolsFromQuery)(query)) {
+            patterns.push(f);
+        }
         if (patterns.length === 0)
             return '';
         const rel = (p) => p.replace(/\\/g, '/');
@@ -4145,21 +5807,264 @@ class ToolHandler {
         }
         // Scan top FTS files for literal pattern in source
         for (const pat of patterns.slice(0, 3)) {
-            const literal = pat.startsWith('.') ? pat : `.${pat}`;
+            const literal = pat.startsWith('.') || pat.startsWith('m_') || /(?:Mutex|Lock)$/.test(pat)
+                ? pat
+                : `.${pat}`;
             const re = new RegExp(literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
             let files = [];
             try {
-                files = cg.searchNodes(patterns[0].replace(/^\./, ''), { limit: 25 });
+                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);
+                }
+            }
+        }
+        // Field patterns with zero FTS: seed from co-named methods/types in the query.
+        const fieldPats = patterns.filter((p) => p.startsWith('m_') || /(?:Mutex|Lock)$/.test(p));
+        if (fieldPats.length > 0 && hits.size < 2) {
+            const seeds = [
+                ...(0, query_utils_1.extractLocalDetailAnchors)(query),
+                ...(0, query_utils_1.extractTypeNamesFromQuery)(query),
+            ].filter((n) => !fieldPats.some((p) => p === n || p.endsWith(n)));
+            const seen = new Set(hits.keys());
+            for (const seed of seeds.slice(0, 5)) {
+                let seedHits = [];
+                try {
+                    seedHits = cg.searchNodes(seed, { limit: 20 });
+                }
+                catch {
+                    continue;
+                }
+                for (const r of seedHits) {
+                    if ((0, query_utils_1.isTestFile)(r.node.filePath))
+                        continue;
+                    const fp = rel(r.node.filePath);
+                    if (seen.has(fp))
+                        continue;
+                    seen.add(fp);
+                    const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                    if (!abs)
+                        continue;
+                    let content;
+                    try {
+                        content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    const fileLines = content.split('\n');
+                    for (const pat of fieldPats) {
+                        const re = new RegExp(pat.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+                        for (let i = 0; i < fileLines.length; i++) {
+                            if (re.test(fileLines[i] ?? ''))
+                                addHit(fp, 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.
+     */
+    /**
+     * In-repo how-to for system settings/capabilities (language/locale/…).
+     * Lists concrete `@ohos.i18n` / `getSystemLanguage` call sites — not every
+     * file that mentions the word "language".
+     */
+    buildSystemCapabilityHowtoSection(cg, query, projectRoot) {
+        const searchTerms = [
+            'getSystemLanguage',
+            'getSystemRegion',
+            'System.getSystemLanguage',
+            '@ohos.i18n',
+            'i18n.System',
+        ];
+        // Topic tokens from the question (language/locale) only as secondary filters.
+        if (/\blanguage\b|语言/i.test(query))
+            searchTerms.push('getSystemLanguage');
+        if (/\blocale\b|地区/i.test(query))
+            searchTerms.push('getSystemRegion');
+        const rel = (p) => p.replace(/\\/g, '/');
+        const rows = [];
+        const seen = new Set();
+        for (const term of searchTerms) {
+            let hits = [];
+            try {
+                hits = cg.searchNodes(term.replace(/^@/, ''), { limit: 35 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of hits) {
+                if ((0, query_utils_1.isTestFile)(r.node.filePath) || (0, arkts_1.isOhosApiFilePath)(r.node.filePath))
+                    continue;
+                if (/\.d\.ts$/i.test(r.node.filePath))
+                    continue;
+                const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                if (!abs || !(0, fs_1.existsSync)(abs))
+                    continue;
+                let content;
+                try {
+                    content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                const fileLines = content.split('\n');
+                const re = new RegExp(term.startsWith('@')
+                    ? term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+                    : `\\b${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+                for (let i = 0; i < fileLines.length; i++) {
+                    const lineText = fileLines[i] ?? '';
+                    if (!re.test(lineText))
+                        continue;
+                    // Prefer real get/import sites over comments.
+                    if (/getSystemLanguage|getSystemRegion|@ohos\.i18n|i18n\.System/i.test(lineText)
+                        || /import\s+.*i18n/i.test(lineText)) {
+                        const key = `${r.node.filePath}:${i + 1}`;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        rows.push(`- \`${rel(r.node.filePath)}:${i + 1}\`  \`${lineText.trim().slice(0, 120)}\``);
+                        if (rows.length >= 16)
+                            break;
+                    }
+                }
+                if (rows.length >= 16)
+                    break;
+            }
+            if (rows.length >= 16)
+                break;
+        }
+        if (rows.length === 0) {
+            return {
+                section: [
+                    '**System capability howto (in-repo)**',
+                    '',
+                    'No `getSystemLanguage` / `@ohos.i18n` call sites indexed. **ANSWER NOW** from SDK docs if the project does not wrap this API.',
+                    '',
+                ].join('\n'),
+                hitCount: 0,
+            };
+        }
+        return {
+            section: [
+                '**System capability howto (in-repo)**',
+                '',
+                '> Concrete call/import sites for system language/locale. **ANSWER NOW** — do not Grep `language` broadly.',
+                '',
+                ...rows,
+                '',
+            ].join('\n'),
+            hitCount: rows.length,
+        };
+    }
+    /**
+     * Declaration / id / native-binding sites for a named UI/native Type (XComponent…).
+     */
+    buildDeclarationSiteSurveySection(cg, query, projectRoot) {
+        const types = (0, query_utils_1.extractTypeNamesFromQuery)(query)
+            .filter((t) => !(0, query_utils_1.isFrameworkUiDecoratorName)(t))
+            .slice(0, 3);
+        if (types.length === 0)
+            return { section: '', hitCount: 0, attempted: false };
+        const rel = (p) => p.replace(/\\/g, '/');
+        const rows = [];
+        const seen = new Set();
+        for (const typeName of types) {
+            let hits = [];
+            try {
+                hits = cg.searchNodes(typeName, { limit: 80 });
             }
             catch {
                 continue;
             }
-            for (const r of files) {
+            // Also pull same-name defs (component/class) even when FTS ranks them low.
+            try {
+                for (const n of cg.getNodesByName(typeName).slice(0, 40)) {
+                    hits.push({ node: n, score: 1 });
+                }
+            }
+            catch { /* optional */ }
+            const files = new Map(); // abs → rel
+            for (const r of hits) {
                 if ((0, query_utils_1.isTestFile)(r.node.filePath))
                     continue;
+                if ((0, arkts_1.isOhosApiFilePath)(r.node.filePath) && /\.d\.ts$/i.test(r.node.filePath))
+                    continue;
                 const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
-                if (!abs)
+                if (!abs || !(0, fs_1.existsSync)(abs))
                     continue;
+                files.set(abs, rel(r.node.filePath));
+            }
+            // Framework UI tags (XComponent…) often have no indexed symbol at the JSX
+            // site — expand to sibling .ets under the same feature/staticcommon roots
+            // already touched by native/header hits.
+            const featureRoots = new Set();
+            for (const fp of files.values()) {
+                const m = fp.match(/^(feature\/[^/]+|staticcommon\/[^/]+)/);
+                if (m?.[1])
+                    featureRoots.add(m[1]);
+            }
+            if (featureRoots.size > 0 && featureRoots.size <= 6) {
+                try {
+                    for (const f of cg.getFiles()) {
+                        const fp = rel(f.path);
+                        if (!/\.ets$/i.test(fp) || (0, query_utils_1.isTestFile)(fp))
+                            continue;
+                        if (![...featureRoots].some((root) => fp.startsWith(`${root}/`)))
+                            continue;
+                        const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, f.path);
+                        if (!abs || !(0, fs_1.existsSync)(abs))
+                            continue;
+                        files.set(abs, fp);
+                    }
+                }
+                catch { /* optional */ }
+            }
+            const typeRe = new RegExp(`\\b${typeName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+            const jsxRe = new RegExp(`<${typeName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+            const callRe = new RegExp(`${typeName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\(`);
+            for (const [abs, fp] of files) {
                 let content;
                 try {
                     content = (0, fs_1.readFileSync)(abs, 'utf-8');
@@ -4168,68 +6073,123 @@ class ToolHandler {
                     continue;
                 }
                 const fileLines = content.split('\n');
+                const isUi = /\.(ets|ts|tsx|jsx)$/i.test(fp);
+                const isNative = /\.(cpp|cc|cxx|h|hpp)$/i.test(fp);
                 for (let i = 0; i < fileLines.length; i++) {
-                    if (re.test(fileLines[i] ?? ''))
-                        addHit(rel(r.node.filePath), i + 1);
+                    const lineText = fileLines[i] ?? '';
+                    if (!typeRe.test(lineText))
+                        continue;
+                    const window = [lineText, fileLines[i + 1] ?? '', fileLines[i + 2] ?? ''].join('\n');
+                    const uiHit = isUi
+                        && (jsxRe.test(lineText)
+                            || callRe.test(lineText)
+                            || (/id\s*[:=]/.test(window) && !/Log(?:Error|Info|Warn|Debug|Message)/i.test(lineText)));
+                    const nativeHit = isNative
+                        && /OH_Native|RegisterCallback|Export\s*\(|napi_/i.test(window)
+                        && !/Log(?:Error|Info|Warn|Debug|Message)/i.test(lineText);
+                    // Prefer construction / JSX / id / native bind; skip log-only mentions.
+                    if (!uiHit && !nativeHit)
+                        continue;
+                    const key = `${fp}:${i + 1}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    const clip = [lineText, fileLines[i + 1] ?? '', fileLines[i + 2] ?? '']
+                        .map((l) => l.trim())
+                        .filter(Boolean)
+                        .join(' / ')
+                        .slice(0, 160);
+                    rows.push(`- \`${typeName}\` — \`${fp}:${i + 1}\`  \`${clip}\``);
+                    if (rows.length >= 24)
+                        break;
                 }
+                if (rows.length >= 24)
+                    break;
             }
-        }
-        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)
+            if (rows.length >= 24)
                 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');
+        // Prefer UI (.ets) rows first so C++ includes don't dominate.
+        rows.sort((a, b) => {
+            const score = (s) => (/\.ets`/.test(s) ? 0 : /\.cpp`|\.h`/.test(s) ? 2 : 1);
+            return score(a) - score(b);
+        });
+        if (rows.length === 0) {
+            return {
+                section: [
+                    '**Declaration / id / native-binding survey**',
+                    '',
+                    `> No UI/native construction sites for \`${types.join('`, `')}\` in the index. **ANSWER NOW** — do not Grep the same Type for "declaration"; at most one Grep for \`<${types[0]}\` if you must.`,
+                    '',
+                ].join('\n'),
+                hitCount: 0,
+                attempted: true,
+            };
+        }
+        return {
+            section: [
+                '**Declaration / id / native-binding survey**',
+                '',
+                '> Construction / JSX / `id` / native register sites. **ANSWER NOW** — do not Grep the same Type again.',
+                '',
+                ...rows.slice(0, 20),
+                '',
+            ].join('\n'),
+            hitCount: Math.min(rows.length, 20),
+            attempted: true,
+        };
     }
-    /**
-     * 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)
+        const rawSymbols = (0, query_utils_1.extractApiUsageTokens)(query).slice(0, 6);
+        if (rawSymbols.length === 0)
             return { section: '', fileCount: 0 };
+        // Expand Telephony → telephony / @ohos.telephony so import call sites hit.
+        const symbols = [];
+        for (const sym of rawSymbols) {
+            symbols.push(sym);
+            if (/^[A-Z][A-Za-z0-9]+$/.test(sym) && sym.length >= 4) {
+                const lc = sym.toLowerCase();
+                if (!symbols.includes(lc))
+                    symbols.push(lc);
+                const ohos = `@ohos.${lc}`;
+                if (!symbols.includes(ohos))
+                    symbols.push(ohos);
+            }
+        }
         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);
+            const stub = /\.d\.ts$/i.test(fp) || /windowsceneinterfaces|@ohos\.|\/api\//i.test(fp);
+            const prev = hits.get(fp) ?? { lines: [], stub };
+            if (!prev.lines.includes(line))
+                prev.lines.push(line);
+            prev.stub = prev.stub && stub;
+            hits.set(fp, prev);
         };
-        for (const sym of symbols.slice(0, 4)) {
+        for (const sym of symbols.slice(0, 6)) {
             const symLc = sym.toLowerCase();
             let nodes = [];
             try {
-                nodes = cg.searchNodes(sym, { limit: 40 });
+                nodes = cg.searchNodes(sym.replace(/^@/, ''), { limit: 40 });
             }
             catch { /* skip */ }
             for (const r of nodes) {
                 const n = r.node;
-                if (n.name.toLowerCase() === symLc || (n.signature || '').toLowerCase().includes(symLc)) {
+                const hay = `${n.name} ${n.signature || ''} ${n.filePath}`.toLowerCase();
+                if (hay.includes(symLc) || n.name.toLowerCase() === symLc) {
                     addHit(n.filePath, n.startLine);
                 }
             }
-            const wordRe = new RegExp(`\\b${sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+            const wordRe = new RegExp(sym.startsWith('@')
+                ? sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+                : `\\b${sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i');
             let scanHits = [];
             try {
-                scanHits = cg.searchNodes(sym, { limit: 30 });
+                scanHits = cg.searchNodes(sym.replace(/^@/, ''), { limit: 35 });
             }
             catch {
                 continue;
@@ -4259,30 +6219,210 @@ class ToolHandler {
                 }
             }
         }
+        // Field/mutex tokens often have zero FTS hits (not extracted as nodes). Seed
+        // scan files from co-named methods/types in the query (drawOnSubThread…).
+        const fieldSyms = (0, query_utils_1.extractFieldLikeSymbolsFromQuery)(query);
+        if (fieldSyms.length > 0) {
+            const seedNames = [
+                ...(0, query_utils_1.extractLocalDetailAnchors)(query),
+                ...(0, query_utils_1.extractTypeNamesFromQuery)(query),
+            ].filter((n) => !fieldSyms.includes(n) && n.length >= 4);
+            const seenSeedFiles = new Set([...hits.keys()]);
+            for (const seed of seedNames.slice(0, 5)) {
+                let seedHits = [];
+                try {
+                    seedHits = cg.searchNodes(seed, { limit: 20 });
+                }
+                catch {
+                    continue;
+                }
+                for (const r of seedHits) {
+                    if ((0, query_utils_1.isTestFile)(r.node.filePath))
+                        continue;
+                    const fp = rel(r.node.filePath);
+                    if (seenSeedFiles.has(fp))
+                        continue;
+                    seenSeedFiles.add(fp);
+                    const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                    if (!abs)
+                        continue;
+                    let content;
+                    try {
+                        content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    const fileLines = content.split('\n');
+                    for (const field of fieldSyms) {
+                        const re = new RegExp(`\\b${field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+                        for (let i = 0; i < fileLines.length; i++) {
+                            if (re.test(fileLines[i] ?? ''))
+                                addHit(fp, i + 1);
+                        }
+                    }
+                }
+            }
+        }
         if (hits.size === 0)
             return { section: '', fileCount: 0 };
+        // Prefer project call/import sites over SDK .d.ts stubs.
+        const rankedFiles = [...hits.entries()].sort((a, b) => {
+            if (a[1].stub !== b[1].stub)
+                return a[1].stub ? 1 : -1;
+            return a[0].localeCompare(b[0]);
+        });
+        const projectHits = rankedFiles.filter(([, v]) => !v.stub);
+        const display = projectHits.length > 0 ? projectHits : rankedFiles;
+        // In files that import the API, also record alias.method( call sites so
+        // "which call methods" answers don't stop at import lines.
+        const aliasCallRe = /\b((?:call|radio|data|sim|observer|telephony|i18n|sensor|wifi)(?:\.\w+)*)\.([A-Za-z_][\w]*)\s*\(/gi;
+        const wantLifetime = (0, query_utils_1.queryAsFieldUsageSurvey)(query)
+            && /new|delete|allocat|释放|free/i.test(query);
+        for (const [fp] of display.slice(0, 40)) {
+            const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, fp);
+            if (!abs || !(0, fs_1.existsSync)(abs))
+                continue;
+            let fileLines = [];
+            try {
+                fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+            }
+            catch {
+                continue;
+            }
+            for (let i = 0; i < fileLines.length; i++) {
+                const lineText = fileLines[i] ?? '';
+                if (aliasCallRe.test(lineText))
+                    addHit(fp, i + 1);
+                aliasCallRe.lastIndex = 0;
+                if (wantLifetime) {
+                    for (const sym of rawSymbols) {
+                        if (!lineText.includes(sym))
+                            continue;
+                        if (/\b(?:new|delete|free|reset)\b/i.test(lineText) || /=\s*new\b/.test(lineText)) {
+                            addHit(fp, i + 1);
+                        }
+                    }
+                }
+            }
+        }
+        // Recompute display after call-site enrichment.
+        const rankedFiles2 = [...hits.entries()].sort((a, b) => {
+            if (a[1].stub !== b[1].stub)
+                return a[1].stub ? 1 : -1;
+            return a[0].localeCompare(b[0]);
+        });
+        const projectHits2 = rankedFiles2.filter(([, v]) => !v.stub);
+        const display2 = projectHits2.length > 0 ? projectHits2 : rankedFiles2;
+        // Extract concrete API method names from snippets (telephony.call.xxx / radio.getY).
+        const methodNames = new Set();
+        for (const [fp, info] of display2.slice(0, 40)) {
+            const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, fp);
+            if (!abs || !(0, fs_1.existsSync)(abs))
+                continue;
+            let fileLines = [];
+            try {
+                fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+            }
+            catch {
+                continue;
+            }
+            for (const ln of info.lines.slice(0, 12)) {
+                const lineText = fileLines[ln - 1] ?? '';
+                for (const m of lineText.matchAll(/\b((?:call|radio|data|sim|observer|telephony)(?:\.\w+)*)\.([A-Za-z_][\w]*)\s*\(/gi)) {
+                    if (m[2] && m[2].length >= 2)
+                        methodNames.add(`${m[1]}.${m[2]}`);
+                }
+                for (const sym of rawSymbols) {
+                    const esc = sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                    const re = new RegExp(`(?:@ohos\\.)?${esc}(?:\\.[A-Za-z_][\\w]*)*\\.([A-Za-z_][\\w]*)\\s*\\(`, 'g');
+                    for (const m of lineText.matchAll(re)) {
+                        if (m[1] && m[1].length >= 2)
+                            methodNames.add(`${sym}.${m[1]}`);
+                    }
+                    // import X from '@ohos.telephony.call' → module surface
+                    const imp = lineText.match(new RegExp(`from\\s+['"]@ohos\\.${esc}(?:\\.(\\w+))?['"]`, 'i'));
+                    if (imp)
+                        methodNames.add(imp[1] ? `@ohos.${sym.toLowerCase()}.${imp[1]}` : `@ohos.${sym.toLowerCase()}`);
+                }
+            }
+        }
         const lines = [
             '**API usage sites**',
             '',
-            `> Files referencing \`${symbols.join('`, `')}\` in this repo (${hits.size} file(s)). Answer from this list; source bodies omitted.`,
+            `> In-repo references to \`${rawSymbols.join('`, `')}\` (${display2.length} file(s)` +
+                `${projectHits2.length > 0 && projectHits2.length < rankedFiles2.length ? `; SDK stubs omitted` : ''}). ` +
+                '**ANSWER NOW** from this list (+ snippets); do not Grep the same API again.',
             '',
         ];
+        if (methodNames.size > 0) {
+            lines.push('**Called / imported API surfaces**');
+            for (const m of [...methodNames].sort().slice(0, 24))
+                lines.push(`- \`${m}\``);
+            if (methodNames.size > 24)
+                lines.push(`- … and ${methodNames.size - 24} more`);
+            lines.push('');
+        }
         let shown = 0;
-        for (const [fp, lineNos] of [...hits.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
-            if (shown >= 45)
+        const isImportish = (s) => /^\s*import\b/.test(s) || /\bfrom\s+['"]@/.test(s);
+        const isLifetimeish = (s) => /\b(?:new|delete|free|reset)\b/i.test(s) || /=\s*new\b/.test(s);
+        for (const [fp, info] of display2) {
+            if (shown >= 28)
                 break;
-            const sortedLines = [...lineNos].sort((a, b) => a - b).slice(0, 6);
+            const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, fp);
+            let fileLines = [];
+            if (abs && (0, fs_1.existsSync)(abs)) {
+                try {
+                    fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+                }
+                catch { /* */ }
+            }
+            // Prefer call / new-delete lines over bare imports for the displayed snippet.
+            const rankedLines = [...info.lines].sort((a, b) => {
+                const ta = fileLines[a - 1] ?? '';
+                const tb = fileLines[b - 1] ?? '';
+                const score = (t) => {
+                    let s = 0;
+                    if (wantLifetime && isLifetimeish(t))
+                        s += 4;
+                    if (/\.\w+\s*\(/.test(t) && !isImportish(t))
+                        s += 3;
+                    if (isImportish(t))
+                        s -= 2;
+                    return s;
+                };
+                return score(tb) - score(ta) || a - b;
+            });
+            // For field new/delete, surface both sides when present (not only `new`).
+            let sortedLines = rankedLines.slice(0, 4);
+            if (wantLifetime && fileLines.length > 0) {
+                const news = rankedLines.filter((l) => /\bnew\b/i.test(fileLines[l - 1] ?? ''));
+                const dels = rankedLines.filter((l) => /\bdelete\b|\bfree\b|=\s*nullptr/i.test(fileLines[l - 1] ?? ''));
+                sortedLines = [...new Set([...news.slice(0, 2), ...dels.slice(0, 2), ...rankedLines])].slice(0, 4);
+            }
+            let snippet = '';
+            if (fileLines.length > 0) {
+                const ln = sortedLines[0];
+                snippet = (fileLines[ln - 1] ?? '').trim().slice(0, 100);
+                if (wantLifetime && sortedLines.length > 1) {
+                    const sn2 = (fileLines[sortedLines[1] - 1] ?? '').trim().slice(0, 80);
+                    if (sn2 && sn2 !== snippet)
+                        snippet = `${snippet}` + ` | ${sn2}`;
+                }
+            }
             const lineStr = sortedLines.map((l) => `L${l}`).join(', ');
-            const more = lineNos.length > sortedLines.length ? ` +${lineNos.length - sortedLines.length} more` : '';
-            lines.push(`- \`${fp}\` (${lineStr}${more})`);
+            const more = info.lines.length > sortedLines.length ? ` +${info.lines.length - sortedLines.length} more` : '';
+            lines.push(snippet
+                ? `- \`${fp}\` (${lineStr}${more})  \`${snippet}\``
+                : `- \`${fp}\` (${lineStr}${more})`);
             shown++;
         }
-        if (hits.size > shown)
-            lines.push(`- … and ${hits.size - shown} more file(s)`);
+        if (display2.length > shown)
+            lines.push(`- … and ${display2.length - shown} more file(s)`);
         lines.push('');
-        lines.push(`> API usage survey complete — **${hits.size}** file(s) listed.`);
+        lines.push(`> API usage survey complete — **${display2.length}** file(s). **ANSWER NOW.**`);
         lines.push('');
-        return { section: lines.join('\n'), fileCount: hits.size };
+        return { section: lines.join('\n'), fileCount: display2.length };
     }
     /**
      * Domain file inventory — related files, usage existence, or concept comparison.
@@ -4445,12 +6585,37 @@ class ToolHandler {
             const callerFiles = [...new Set(uniq.map((n) => rel(n.filePath)))];
             const testFiles = callerFiles.filter((f) => (0, query_utils_1.isTestFile)(f));
             const nonTest = callerFiles.filter((f) => !(0, query_utils_1.isTestFile)(f));
+            // Indirect test coverage via one hop of callers (tests that call a
+            // direct caller) when nothing calls the root from a test file.
+            let indirectTests = [];
+            if (testFiles.length === 0) {
+                const seenTest = new Set();
+                for (const c of uniq.slice(0, 8)) {
+                    let next = [];
+                    try {
+                        next = cg.getCallers(c.id);
+                    }
+                    catch {
+                        continue;
+                    }
+                    for (const n of next) {
+                        const fp = rel(n.node.filePath);
+                        if ((0, query_utils_1.isTestFile)(fp) && !seenTest.has(fp)) {
+                            seenTest.add(fp);
+                            indirectTests.push(fp);
+                        }
+                    }
+                }
+                indirectTests = indirectTests.slice(0, FILE_CAP);
+            }
             const shown = nonTest.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ');
             const more = nonTest.length > FILE_CAP ? ` +${nonTest.length - FILE_CAP} more` : '';
             const where = nonTest.length > 0 ? ` in ${shown}${more}` : '';
             const tests = testFiles.length > 0
                 ? `; tests: ${testFiles.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ')}${testFiles.length > FILE_CAP ? ` +${testFiles.length - FILE_CAP}` : ''}`
-                : '; ⚠️ no covering tests found';
+                : indirectTests.length > 0
+                    ? `; tests (via callers): ${indirectTests.map((f) => `\`${f}\``).join(', ')}`
+                    : '; ⚠️ no covering tests found';
             entries.push(`- \`${root.name}\` (${rel(root.filePath)}:${root.startLine}) — ${uniq.length} caller${uniq.length === 1 ? '' : 's'}${where}${tests}`);
         }
         if (entries.length === 0)
@@ -4562,15 +6727,18 @@ class ToolHandler {
         // 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 deferKind = (0, query_utils_1.queryShouldDeferToBuiltinTools)(query);
+        if (deferKind) {
+            return this.textResult((0, query_utils_1.homegraphDeferGuidance)(deferKind, query));
+        }
         const cg = this.getHomeGraph(args.projectPath);
         const projectRoot = cg.getProjectRoot();
         const compactLocal = this.tryFastInventoryExplore(cg, query, projectRoot)
+            ?? this.tryLightMechanismExplore(cg, query, projectRoot)
             ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot);
         if (compactLocal)
             return compactLocal;
-        const lightMechanism = this.tryLightMechanismExplore(cg, query, projectRoot);
-        if (lightMechanism)
-            return lightMechanism;
+        // Light mechanism already attempted above.
         // 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.
@@ -4994,8 +7162,10 @@ class ToolHandler {
         // Test/spec/icon/i18n file detector — used both for the pre-sort hard
         // filter (tiny tier) and the comparator deprioritization (all tiers).
         const isLowValue = (p) => {
-            const lp = p.toLowerCase();
-            return (/\/(tests?|__tests?__|spec)\//.test(lp) ||
+            const lp = p.toLowerCase().replace(/\\/g, '/');
+            return (
+            // Top-level test/ / spec/ as well as nested …/tests?/…
+            /(?:^|\/)(tests?|specs?|__tests?__|testdata|mocks?|fixtures?)\//.test(lp) ||
                 /_test\.go$/.test(lp) ||
                 /(?:^|\/)test_[^/]+\.py$/.test(lp) ||
                 /_test\.py$/.test(lp) ||
@@ -5009,6 +7179,10 @@ class ToolHandler {
                 /\bicons?\b/.test(lp) ||
                 /\bi18n\b/.test(lp));
         };
+        /** Hand-written ambient `.d.ts` — down-rank for behavior/flow questions (CG-28). */
+        const isAmbientDts = (p) => /\.d\.ts$/i.test(p.replace(/\\/g, '/'));
+        /** Path convention OR persisted content-banner flag. */
+        const isGeneratedCandidate = (fp) => this.isGeneratedCandidate(cg, fp);
         // Hard-exclude test/spec files (ALL tiers, not just tiny). One slipped test
         // file dominates the per-file budget on small repos (cobra's `command_test.go`
         // displaced `args.go`) AND wastes budget on large ones (Django's
@@ -5198,16 +7372,17 @@ class ToolHandler {
             const bLow = isLowValue(bPath);
             if (aLow !== bLow)
                 return aLow ? 1 : -1;
-            // Deprioritize generated source (.pb.go / .pulsar.go / _mocks.go / …) —
-            // the agent rarely needs to see the protobuf scaffold or gomock output
-            // when asking about the actual flow, and dumping their bodies inflates
-            // the response (the cosmos Q3 explore otherwise leads with
-            // `expected_keepers_mocks.go`, displacing the real `tally.go` content
-            // and forcing the agent to Read tally.go anyway).
-            const aGen = (0, generated_detection_1.isGeneratedFile)(a[0]);
-            const bGen = (0, generated_detection_1.isGeneratedFile)(b[0]);
+            // Deprioritize generated source (path suffixes OR content banner).
+            const aGen = isGeneratedCandidate(a[0]);
+            const bGen = isGeneratedCandidate(b[0]);
             if (aGen !== bGen)
                 return aGen ? 1 : -1;
+            // Hand-written ambient `.d.ts` — demote unless the agent named a type
+            // defined there (behavior questions want implementations, not typings).
+            const aAmbient = isAmbientDts(a[0]) && !namedSeedFiles.has(a[0]) ? 1 : 0;
+            const bAmbient = isAmbientDts(b[0]) && !namedSeedFiles.has(b[0]) ? 1 : 0;
+            if (aAmbient !== bAmbient)
+                return aAmbient - bAmbient;
             if (a[1].score !== b[1].score)
                 return b[1].score - a[1].score;
             return b[1].nodes.length - a[1].nodes.length;
@@ -5231,13 +7406,17 @@ class ToolHandler {
                 'production handlers are out of scope unless explicitly referenced in the test.');
             lines.push('');
         }
-        const importResult = this.buildImportSitesSection(cg, query, projectRoot);
+        const importResult = (0, query_utils_1.queryAsksKitInstallDeps)(query)
+            ? { section: '', siteCount: 0, compactListing: false }
+            : 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)
+            && ((0, query_utils_1.queryAsksKitInstallDeps)(query)
+                || !(importResult.compactListing && importResult.siteCount > 0))
             ? this.buildKitModuleUsageSection(cg, query, projectRoot)
             : { section: '', symbolCount: 0 };
         if (kitUsageResult.section)
@@ -5248,6 +7427,7 @@ class ToolHandler {
         if (domainFileResult.section)
             lines.push(domainFileResult.section);
         const apiUsageResult = (0, query_utils_1.shouldBuildApiUsageSurvey)(query)
+            && !(0, query_utils_1.shouldBuildKitModuleUsageSurvey)(query)
             ? this.buildApiUsageSection(cg, query, projectRoot)
             : { section: '', fileCount: 0 };
         if (apiUsageResult.section)
@@ -5293,9 +7473,14 @@ class ToolHandler {
         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 listedTypeMethods = (0, query_utils_1.extractListedTypeMethodsFromQuery)(query).length > 0;
+        // Type + listed methods (BinaryGrid Set/Test/Fill) must keep caller inventory even
+        // when multi-anchor would otherwise skip it into a fat source dump.
+        const callerSection = !hasFlowPath && (!multiAnchor || listedTypeMethods) && (0, query_utils_1.shouldBuildCallerInventory)(query)
+            ? this.buildCallerListingSection(cg, query, projectRoot) : '';
+        // Field new/delete inventories already list text sites — skip redundant member scan.
         const memberSection = !hasFlowPath && !multiAnchor && (0, query_utils_1.shouldBuildMemberSurvey)(query)
+            && !((0, query_utils_1.queryAsFieldUsageSurvey)(query) && apiUsageResult.fileCount > 0)
             ? this.buildMemberSurveySection(cg, query, projectRoot) : '';
         const configSection = (0, query_utils_1.shouldBuildConfigSection)(query)
             ? this.buildConfigFileSection(cg, query, projectRoot) : '';
@@ -5337,28 +7522,32 @@ class ToolHandler {
                 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.`);
+                return finishCompact(`Kit module **in-repo usage** survey — **${kitUsageResult.symbolCount}** imported symbol(s). ` +
+                    'Not an SDK catalog. **ANSWER NOW** from the usage list; do not Grep the same `@kit` path.');
             }
             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.`);
+                return finishCompact(`Domain file survey — **${domainFileResult.fileCount}** related file(s) listed above. **ANSWER NOW.**`);
             }
             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.`);
+                return finishCompact(`API usage survey — **${apiUsageResult.fileCount}** file(s). **ANSWER NOW** from the list above.`);
+            }
+            if (listedTypeMethods && callerBulletCount > 0) {
+                return finishCompact(`Caller inventory — **${callerBulletCount}** site(s) for listed methods. **ANSWER NOW**; do not fan out callers per method.`);
             }
             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.`);
+                return finishCompact(`Data-source survey — **${dataSourceResult.edgeCount}** upstream symbol(s). **ANSWER NOW.**`);
             }
             if (inheritanceListed) {
-                return finishCompact('Inheritance survey above lists all direct subtypes found — source bodies omitted.');
+                return finishCompact('Inheritance survey above lists all direct subtypes found. **ANSWER NOW** — do not grep `extends`.');
             }
             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.`);
+                return finishCompact(`Listed **${importResult.siteCount}** import site(s). **ANSWER NOW** from the dependency list above.`);
             }
             if (callerBulletCount >= 1) {
-                return finishCompact(`Caller inventory above lists **${callerBulletCount}** method(s) with external callers — source bodies omitted.`);
+                return finishCompact(`Caller inventory above lists **${callerBulletCount}** method(s). **ANSWER NOW.**`);
             }
             if (memberSection && memberFileCount >= 2) {
-                return finishCompact(`Member/pattern usage in **${memberFileCount}** file(s) — source bodies omitted; answer from the inventory above.`);
+                return finishCompact(`Member/pattern usage in **${memberFileCount}** file(s). **ANSWER NOW** from the inventory above.`);
             }
         }
         // Blast radius only for structural flow / mechanism answers — skip on local-detail
@@ -5458,6 +7647,9 @@ class ToolHandler {
         };
         lines.push('**Source Code**');
         lines.push('');
+        // Recorded so the drift pass below (#1474) can append a per-file exception
+        // to this guarantee after the render loop knows which files drifted.
+        const verbatimHeaderIdx = lines.length;
         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.');
@@ -5468,6 +7660,28 @@ class ToolHandler {
         // (#1046) — it must reflect what we show, not the raw candidate gather.
         const renderedFilePaths = [];
         let anyFileTrimmed = false;
+        // Files that changed on disk after their last index sync (#1474).
+        const staleRendered = [];
+        const staleOmitted = [];
+        // What this session has already been served for THIS project (CG-17), and
+        // whether this call may act on it (CG-18). Dedup is off on the session's
+        // first call by construction — there is nothing to point back AT — and off
+        // entirely under `HOMEGRAPH_EXPLORE_DEDUP=0`.
+        const priorCalls = (0, explore_session_state_1.viewForProject)((0, explore_session_state_1.readExploreSessionView)(args), projectRoot);
+        const dedupEnabled = (0, explore_dedup_1.exploreDedupEnabled)() && (priorCalls?.calls.length ?? 0) > 0;
+        const emittedByFile = new Map();
+        const noteEmitted = (fp, ranges, bytes, fingerprint) => {
+            const existing = emittedByFile.get(fp);
+            if (existing) {
+                existing.ranges.push(...ranges);
+                existing.bytes += bytes;
+                if (fingerprint)
+                    existing.fingerprint = fingerprint;
+            }
+            else {
+                emittedByFile.set(fp, { ranges: [...ranges], bytes, fingerprint });
+            }
+        };
         const limitSingleFile = (0, query_utils_1.shouldLimitToQueryNamedFile)(query, hasFlowPath, multiAnchor)
             || (interpretationQuery && queryFileBasenames.length === 1);
         let filesToRender = sortedFiles;
@@ -5553,6 +7767,49 @@ class ToolHandler {
             }
             const fileLines = fileContent.split('\n');
             const lang = group.nodes[0]?.language || '';
+            // Disk-drift gate (#1474): every render branch below except whole-file
+            // slices fileContent (CURRENT bytes) at INDEXED line ranges.
+            const fileStale = this.isFileStaleOnDisk(cg, filePath, fileContent);
+            // Cross-call dedup (CG-18). `served` is what THIS session already sent the
+            // agent for THIS file, and it is empty unless the file still hashes to the
+            // bytes those spans were sliced from — an edit between calls means the
+            // agent's copy is wrong, so nothing is withheld.
+            const fingerprint = (0, explore_dedup_1.fileFingerprint)(fileContent);
+            const served = dedupEnabled ? (0, explore_dedup_1.servedRangesForFile)(priorCalls, filePath, fingerprint) : [];
+            const withLineNumbers = exploreLineNumbersEnabled();
+            const renderSpan = (r) => {
+                const slice = fileLines.slice(r.start - 1, r.end).join('\n');
+                return withLineNumbers ? numberSourceLines(slice, r.start) : slice;
+            };
+            /**
+             * Emit one file's section — header, optional back-reference for held spans,
+             * and the fence for what is new. Fully-held files become pointers and do
+             * not consume a `maxFiles` slot (budget goes to unseen files).
+             */
+            const emitFileSection = (opts) => {
+                const folded = opts.covered.length > 0 && opts.body.length < explore_dedup_1.EXPLORE_DEDUP.MIN_DELTA_CHARS;
+                const body = folded ? '' : opts.body;
+                const ranges = folded ? [] : opts.ranges;
+                lines.push(opts.header, '');
+                totalChars += opts.header.length + 2;
+                if (opts.covered.length > 0) {
+                    const pointer = (0, explore_dedup_1.formatBackReference)(filePath, opts.covered, (0, explore_dedup_1.symbolsInSpans)(group.nodes, opts.covered), { partial: body.length > 0 });
+                    lines.push(pointer, '');
+                    totalChars += pointer.length + 2;
+                }
+                if (body.length > 0) {
+                    lines.push('```' + lang, body, '```', '');
+                    totalChars += body.length + lang.length + 11;
+                    noteEmitted(filePath, [...ranges, ...opts.covered], body.length, fingerprint);
+                    renderedFilePaths.push(filePath);
+                    filesIncluded++;
+                    return;
+                }
+                // Fully held — pointer only; still record spans at zero bytes.
+                noteEmitted(filePath, opts.covered, 0, fingerprint);
+                renderedFilePaths.push(filePath);
+                // Do not increment filesIncluded: slot goes to a file the agent has not seen.
+            };
             // Adaptive sizing (HOMEGRAPH_ADAPTIVE_EXPLORE, default on): collapse a file
             // to a per-symbol view when it's a redundant member of a polymorphic family.
             // Engages iff ALL hold:
@@ -5591,7 +7848,7 @@ class ToolHandler {
             const onSpineGodFile = hasSpineNode
                 && namedBodyChars > budget.maxCharsPerFile
                 && group.nodes.some(n => CALLABLE_BODY.has(n.kind) && flow.uniqueNamedNodeIds.has(n.id) && !flow.pathNodeIds.has(n.id));
-            if (adaptiveExploreEnabled() && flow.pathNodeIds.size > 0
+            if (!fileStale && adaptiveExploreEnabled() && flow.pathNodeIds.size > 0
                 && (onSpineGodFile || (!hasSpineNode && isPolymorphicSibling(group.nodes) && !spared))) {
                 const syms = group.nodes
                     .filter(n => n.kind !== 'import' && n.kind !== 'export' && n.startLine > 0)
@@ -5673,12 +7930,32 @@ class ToolHandler {
                     // a Read of the very file just skeletonized; on a central, wanted file
                     // (Session.swift, DataRequest.swift) that fired an over-investigation
                     // spiral (the agent Read the skeletonized file, then kept digging).
-                    // CLAUDE.md: explore output must never tell the agent to Read.
+                    // AGENTS.md: explore output must never tell the agent to Read.
                     const tag = bodyIds.size > 0
                         ? 'focused (the methods you named in full, the rest as signatures — homegraph_explore a signature by name for its body; do NOT Read)'
                         : 'skeleton (signatures only — homegraph_explore a name for its full body; do NOT Read)';
-                    lines.push(fileSectionHeader(filePath, `${names} · ${tag}`), '', '```' + lang, skel.join('\n'), '```', '');
-                    totalChars += skel.join('\n').length + 120;
+                    const skelHeader = fileSectionHeader(filePath, `${names} · ${tag}`);
+                    // If this session already holds the whole file, replace the skeleton
+                    // with a pointer rather than re-serving signatures/bodies.
+                    const wholeRange = { start: 1, end: Math.max(1, fileLines.length) };
+                    const ddWhole = (0, explore_dedup_1.dedupeRange)(wholeRange, served);
+                    if (ddWhole.covered.length > 0 && ddWhole.emit.length === 0) {
+                        emitFileSection({
+                            header: skelHeader,
+                            body: '',
+                            ranges: [],
+                            covered: ddWhole.covered,
+                        });
+                        continue;
+                    }
+                    const skelBody = skel.join('\n');
+                    const bodyRanges = [...bodyIds].map((id) => {
+                        const n = group.nodes.find((x) => x.id === id);
+                        return n ? { start: n.startLine, end: n.endLine || n.startLine } : null;
+                    }).filter((r) => !!r);
+                    lines.push(skelHeader, '', '```' + lang, skelBody, '```', '');
+                    totalChars += skelBody.length + 120;
+                    noteEmitted(filePath, bodyRanges.length > 0 ? bodyRanges : [wholeRange], skelBody.length, fingerprint);
                     renderedFilePaths.push(filePath);
                     filesIncluded++;
                     continue;
@@ -5709,25 +7986,45 @@ class ToolHandler {
                 ? Math.min(Math.max(0, budget.maxOutputChars - totalChars - 200), Math.round(budget.maxCharsPerFile * 1.5))
                 : budget.maxCharsPerFile * 3;
             if (fileLines.length <= WHOLE_FILE_MAX_LINES && fileContent.length <= WHOLE_FILE_MAX_CHARS) {
-                const body = fileContent.replace(/\n+$/, '');
-                let wholeSection = exploreLineNumbersEnabled() ? numberSourceLines(body, 1) : body;
+                const wholeRange = { start: 1, end: Math.max(1, fileLines.length) };
+                const dd = (0, explore_dedup_1.dedupeRange)(wholeRange, served);
                 const uniqSymbols = [...new Set(group.nodes
                         .filter(n => n.kind !== 'import' && n.kind !== 'export')
                         .map(n => `${n.name}(${n.kind})`))];
                 const headerNames = uniqSymbols.slice(0, budget.maxSymbolsInFileHeader);
                 const omitted = uniqSymbols.length - headerNames.length;
-                const wholeHeader = fileSectionHeader(filePath, omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', '));
-                if (!fileNecessary && totalChars + wholeSection.length + 200 > budget.maxOutputChars) {
+                // A drifted file rendered WHOLE is still correct (current bytes) —
+                // only index-derived symbol list / line refs may be shifted (#1474).
+                const staleSuffix = fileStale ? ' · ⚠ changed since last index sync — source below is current; the symbol list may be outdated' : '';
+                const wholeHeader = fileSectionHeader(filePath, (omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', ')) + staleSuffix);
+                const emitParts = dd.emit.length > 0
+                    ? dd.emit.map((r) => ({ range: r, text: renderSpan(r) }))
+                    : [];
+                const wholeSection = emitParts.map((p) => p.text).join('\n');
+                const emitRanges = emitParts.map((p) => p.range);
+                if (!fileNecessary && totalChars + Math.max(wholeSection.length, 80) + 200 > budget.maxOutputChars && dd.covered.length === 0) {
                     // Don't slice a whole file mid-method: an incidental file that doesn't
                     // fit is skipped; a necessary one (below) renders in full. Half a file
                     // forces the Read this is meant to prevent.
                     anyFileTrimmed = true;
                     continue;
                 }
-                lines.push(wholeHeader, '', '```' + lang, wholeSection, '```', '');
-                totalChars += wholeSection.length + 200;
-                renderedFilePaths.push(filePath);
-                filesIncluded++;
+                emitFileSection({
+                    header: wholeHeader,
+                    body: wholeSection,
+                    ranges: emitRanges,
+                    covered: dd.covered,
+                });
+                if (fileStale && wholeSection.length > 0)
+                    staleRendered.push(filePath);
+                continue;
+            }
+            // Drifted file too big for the whole-file window (#1474): omit rather
+            // than risk a mis-sliced cluster/skeleton render.
+            if (fileStale) {
+                staleOmitted.push(filePath);
+                lines.push(fileSectionHeader(filePath, '⚠ changed on disk after the last index sync — source omitted (indexed line ranges no longer match, so a slice could show the wrong code). Read this file directly for current content; the change is picked up on that project\'s next index sync.'), '');
+                totalChars += 260;
                 continue;
             }
             // Cluster nearby symbols to avoid reading huge gaps between distant symbols.
@@ -5887,7 +8184,6 @@ class ToolHandler {
             // until the per-file char cap is hit. Truly enormous single clusters
             // get tail-trimmed with a marker.
             const contextPadding = 3;
-            const withLineNumbers = exploreLineNumbersEnabled();
             // Language-neutral separator (no `//` — not a comment in Python, Ruby,
             // etc.). With line numbers on, the line-number jump also signals the gap.
             const GAP_MARKER = '\n\n... (gap) ...\n\n';
@@ -5898,29 +8194,38 @@ class ToolHandler {
             // the exact gap this closes. Bounded, so a god-method can't blow the budget yet
             // the spine's call still appears in context.
             const OVERSIZE_SPINE_LINES = 200;
+            const OVERSIZE_BODY_LINES = 160;
             const SPINE_WINDOW = 28; // lines each side of the next-hop call site
-            const buildSection = (c) => {
-                if (c.hasSpine && c.spineCallLine && (c.end - c.start + 1) > OVERSIZE_SPINE_LINES) {
+            const BODY_WINDOW = 40;
+            const buildSectionRange = (c) => {
+                const span = c.end - c.start + 1;
+                if (c.hasSpine && c.spineCallLine && span > OVERSIZE_SPINE_LINES) {
                     const call = c.spineCallLine;
                     const winStart = Math.max(c.start, call - SPINE_WINDOW);
                     const winEnd = Math.min(c.end, call + SPINE_WINDOW);
-                    const parts = [];
-                    // Signature head, only when it sits clearly above the window (else the
-                    // window already covers the method opening).
+                    const ranges = [];
                     const headEnd = Math.min(c.start + 4, winStart - 2);
-                    if (headEnd >= c.start) {
-                        const head = fileLines.slice(c.start - 1, headEnd).join('\n');
-                        parts.push(withLineNumbers ? numberSourceLines(head, c.start) : head);
-                    }
-                    const win = fileLines.slice(winStart - 1, winEnd).join('\n');
-                    parts.push(withLineNumbers ? numberSourceLines(win, winStart) : win);
-                    return parts.join(GAP_MARKER);
-                }
-                const startIdx = Math.max(0, c.start - 1 - contextPadding);
-                const endIdx = Math.min(fileLines.length, c.end + contextPadding);
-                const slice = fileLines.slice(startIdx, endIdx).join('\n');
-                // startIdx is 0-based, so the slice's first line is line startIdx + 1.
-                return withLineNumbers ? numberSourceLines(slice, startIdx + 1) : slice;
+                    if (headEnd >= c.start)
+                        ranges.push({ start: c.start, end: headEnd });
+                    ranges.push({ start: winStart, end: winEnd });
+                    return ranges;
+                }
+                // Long non-spine functions get a bounded window, not a full dump.
+                if (!c.hasSpine && span > OVERSIZE_BODY_LINES) {
+                    const headEnd = Math.min(c.end, c.start + BODY_WINDOW);
+                    const midStart = Math.max(headEnd + 1, Math.floor((c.start + c.end) / 2) - Math.floor(BODY_WINDOW / 2));
+                    const midEnd = Math.min(c.end, midStart + BODY_WINDOW);
+                    const ranges = [{ start: c.start, end: headEnd }];
+                    if (midStart > headEnd)
+                        ranges.push({ start: midStart, end: midEnd });
+                    return ranges;
+                }
+                const start = Math.max(1, c.start - contextPadding);
+                const end = Math.min(fileLines.length, c.end + contextPadding);
+                return [{ start, end }];
+            };
+            const buildSection = (c) => {
+                return buildSectionRange(c).map((r) => renderSpan(r)).join(GAP_MARKER);
             };
             // Rank clusters for inclusion under the per-file cap. Entry-point
             // clusters come first: a cluster containing a query entry point
@@ -5951,18 +8256,19 @@ class ToolHandler {
                     return b.c.score - a.c.score;
                 return a.span - b.span;
             });
-            // Per-file budget is the SMALLER of the per-file cap and what's left of the
-            // total output cap — so selection (which ranks by importance) keeps the
-            // high-importance clusters and drops peripheral ones, instead of the
-            // downstream source-order trim slicing off whatever comes last in the file.
-            // That source-order slice is what cut Django's `_fetch_all` (L2237, importance
-            // 9 — agent-named) when query.py was the last of four big files to be emitted.
-            const fileBudget = Math.min(budget.maxCharsPerFile, Math.max(0, budget.maxOutputChars - totalChars - 200));
+            // Per-file budget fairness: reserve a fair share of remaining envelope for
+            // files still waiting, so the first file cannot steal later files' budget.
+            // Still capped by maxCharsPerFile; necessary/spine files can exceed via
+            // SPINE_CEILING below.
+            const filesLeft = Math.max(1, Math.min(maxFiles - filesIncluded, filesToRender.length - filesIncluded));
+            const remainingEnvelope = Math.max(0, budget.maxOutputChars - totalChars - 200);
+            const fairShare = Math.floor(remainingEnvelope / filesLeft);
+            const fileBudget = Math.min(budget.maxCharsPerFile, Math.max(fairShare, Math.min(budget.maxCharsPerFile, remainingEnvelope)));
             // Spine ceiling: a flow-path cluster may exceed the per-file cap (the call
             // path is the answer), but bounded — at most ~2.5× the per-file cap and never
             // past what's left of the total output cap — so a pathological long in-file
             // spine can't run away or starve co-flow files entirely.
-            const SPINE_CEILING = Math.min(budget.maxCharsPerFile * 2.5, Math.max(0, budget.maxOutputChars - totalChars - 200));
+            const SPINE_CEILING = Math.min(budget.maxCharsPerFile * 2.5, remainingEnvelope);
             const chosenIndices = new Set();
             let projectedChars = 0;
             for (const rc of rankedClusters) {
@@ -6041,21 +8347,46 @@ class ToolHandler {
                 anyFileTrimmed = true;
                 continue;
             }
-            lines.push(fileHeader);
-            lines.push('');
-            lines.push('```' + lang);
-            lines.push(fileSection);
-            lines.push('```');
-            lines.push('');
-            totalChars += fileSection.length + 200;
-            renderedFilePaths.push(filePath);
-            filesIncluded++;
+            // Apply session history to the chosen clusters' spans (CG-18).
+            const intendedRanges = [];
+            for (let i = 0; i < clusters.length; i++) {
+                if (!chosenIndices.has(i))
+                    continue;
+                intendedRanges.push(...buildSectionRange(clusters[i]));
+            }
+            const coveredParts = [];
+            const emitParts = [];
+            for (const range of intendedRanges) {
+                const split = (0, explore_dedup_1.dedupeRange)(range, served);
+                coveredParts.push(...split.covered);
+                for (const r of split.emit)
+                    emitParts.push({ range: r, text: renderSpan(r) });
+            }
+            const dedupedBody = emitParts.map((p) => p.text).join(GAP_MARKER);
+            const dedupedRanges = emitParts.map((p) => p.range);
+            const covered = (0, explore_dedup_1.mergeRanges)(coveredParts);
+            emitFileSection({
+                header: fileHeader,
+                body: dedupedBody.length > 0 ? dedupedBody : (covered.length > 0 ? '' : fileSection),
+                ranges: dedupedRanges.length > 0 ? dedupedRanges : (covered.length > 0 ? [] : intendedRanges),
+                covered,
+            });
         }
         // The curated header count is computed from the files that SURVIVE the final
         // truncation (see end of method) — `filesIncluded` can over-count when the
         // hard ceiling drops trailing sections — so leave a sentinel here and fill it
         // in once the output is final.
         lines[summaryLineIdx] = SUMMARY_SENTINEL;
+        // Drift epilogue (#1474). Everything actually rendered is still byte-accurate
+        // (drifted files ship whole or not at all), but omitted files need Reading and
+        // index-derived line references to drifted files may be shifted.
+        if (staleOmitted.length > 0) {
+            lines[verbatimHeaderIdx] += ' (Exception: files flagged "⚠ changed on disk" below drifted from the index after their last sync — their source is omitted rather than risk a mis-sliced block; Read those specific files.)';
+        }
+        const staleAll = [...new Set([...staleOmitted, ...staleRendered])];
+        if (staleAll.length > 0) {
+            lines.push('', `> ⚠ Changed on disk after the last index sync: ${staleAll.join(', ')}. Line numbers referencing ${staleAll.length === 1 ? 'this file' : 'these files'} elsewhere in this response (flow steps, blast radius, symbol lists) may be shifted until that project's next sync re-indexes ${staleAll.length === 1 ? 'it' : 'them'}.`);
+        }
         // Add remaining files as references (from both relevant and peripheral files).
         // Small projects (per budget) skip this — the relevant story already fits
         // in the source section, and a trailing pointer list is pure overhead.
@@ -6096,7 +8427,9 @@ class ToolHandler {
                 const stats = cg.getStats();
                 const callBudget = getExploreBudget(stats.fileCount);
                 lines.push('');
-                lines.push(`> **Explore budget: ${callBudget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).** Each call covers ~6 files; if your question spans more, spend your remaining calls on the uncovered area BEFORE falling back to Read — another explore is cheaper and more complete than reading those files. Synthesize once you've used ${callBudget}.`);
+                lines.push(`> **Usually one explore is enough** (budget ≤${callBudget} for ${stats.fileCount.toLocaleString()} files). ` +
+                    'Answer from Flow + Source above. Extra explore/`homegraph_node`/Read for the **same** symbols multiplies tokens — ' +
+                    'only call again for a missing **named** symbol.');
             }
             catch {
                 // Stats unavailable — skip budget note
@@ -6114,16 +8447,54 @@ class ToolHandler {
         const hardCeiling = Math.min(Math.round(budget.maxOutputChars * 1.5), 25000);
         let finalText;
         if (output.length > hardCeiling) {
-            // Cut at a FILE-SECTION boundary (the last ``**` `` file header before the
-            // ceiling) so we drop whole trailing file-sections rather than slicing
-            // through a method body — a half-rendered method just forces the Read this
-            // tool exists to prevent. Fall back to a line boundary only if no section
-            // header sits in the back half (degenerate single-giant-section case).
-            const cut = output.slice(0, hardCeiling);
-            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 uncovered files/symbols, run another homegraph_explore with their exact names — not grep/read/node for symbols already shown.)';
+            // Prefer dropping trailing notes ("Not shown above", completeness, budget)
+            // over dropping a whole file's source — notes are recoverable, source isn't.
+            let trimmed = output;
+            const noteMarkers = [
+                '\n**Not shown above — explore these names for their source**',
+                '\n---\n> **Complete source for ',
+                '\n> Some file sections were trimmed for size.',
+                '\n> **Usually one explore is enough**',
+            ];
+            for (const marker of noteMarkers) {
+                if (trimmed.length <= hardCeiling)
+                    break;
+                const at = trimmed.lastIndexOf(marker);
+                if (at > hardCeiling * 0.4)
+                    trimmed = trimmed.slice(0, at).replace(/\n+$/, '');
+            }
+            if (trimmed.length > hardCeiling) {
+                // Cut at a FILE-SECTION boundary so we drop whole trailing file-sections
+                // rather than slicing through a method body. Prefer dropping sections for
+                // files that are NOT agent-named / spine-necessary when possible.
+                const cut = trimmed.slice(0, hardCeiling);
+                let boundary = -1;
+                let searchFrom = cut.length;
+                while (searchFrom > hardCeiling * 0.5) {
+                    const at = cut.lastIndexOf('\n' + FILE_SECTION_PREFIX, searchFrom - 1);
+                    if (at < 0)
+                        break;
+                    // Extract path between **` and `**
+                    const after = cut.slice(at + 1 + FILE_SECTION_PREFIX.length);
+                    const endTick = after.indexOf('`');
+                    const fp = endTick > 0 ? after.slice(0, endTick) : '';
+                    const necessary = fp && (namedSeedFiles.has(fp) || entryFiles.has(fp) || centralFiles.has(fp));
+                    if (!necessary) {
+                        boundary = at;
+                        break;
+                    }
+                    searchFrom = at;
+                }
+                if (boundary < 0) {
+                    const lastSection = cut.lastIndexOf('\n' + FILE_SECTION_PREFIX);
+                    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 uncovered files/symbols, run another homegraph_explore with their exact names — not grep/read/node for symbols already shown.)';
+            }
+            else {
+                finalText = trimmed;
+            }
         }
         else {
             finalText = output;
@@ -6131,7 +8502,7 @@ class ToolHandler {
         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. ' +
+                    'Do **not** grep/read/`homegraph_node`/`homegraph_search` for the same symbols or files (multiplies tokens). ' +
                     '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
@@ -6152,7 +8523,40 @@ class ToolHandler {
             ? `Found ${shownSymbols} symbol${shownSymbols === 1 ? '' : 's'} across ${survivors.length} file${survivors.length === 1 ? '' : 's'}.`
             : `Found ${subgraph.nodes.size} symbol${subgraph.nodes.size === 1 ? '' : 's'} across ${fileGroups.size} file${fileGroups.size === 1 ? '' : 's'}.`;
         finalText = finalText.replace(SUMMARY_SENTINEL, summaryLine);
-        return this.textResult(finalText);
+        // Session record (CG-17): only the files that SURVIVED the hard ceiling —
+        // a section the truncation dropped was never delivered, and recording it
+        // would let a later call withhold source the agent has never seen.
+        const emittedFiles = [];
+        let sourceBytes = 0;
+        for (const fp of survivors) {
+            const emitted = emittedByFile.get(fp);
+            if (!emitted || emitted.ranges.length === 0)
+                continue;
+            emittedFiles.push({
+                path: fp,
+                ranges: emitted.ranges,
+                bytes: emitted.bytes,
+                fingerprint: emitted.fingerprint,
+            });
+            sourceBytes += emitted.bytes;
+        }
+        return this.exploreResult(finalText, {
+            projectRoot,
+            query,
+            files: emittedFiles,
+            sourceBytes,
+            responseBytes: finalText.length,
+        });
+    }
+    /**
+     * An explore response plus the record of what it emitted (CG-17). The record
+     * rides the result only as far as {@link execute}, which files it into the
+     * calling session's state and deletes it — see {@link EXPLORE_EMISSION_KEY}.
+     */
+    exploreResult(text, emission) {
+        const result = this.textResult(text);
+        result[explore_session_state_1.EXPLORE_EMISSION_KEY] = emission;
+        return result;
     }
     /**
      * Handle homegraph_node
@@ -6406,6 +8810,11 @@ class ToolHandler {
     }
     /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
     async renderNodeSection(cg, node, includeCode) {
+        // Disk-drift gate (issue #1474): body is CURRENT bytes sliced at INDEXED
+        // line ranges. Never emit a slice from a drifted file.
+        if (this.isFileStaleOnDisk(cg, node.filePath)) {
+            return this.renderStaleNodeSection(cg, node, includeCode);
+        }
         let code = null;
         let outline = null;
         if (includeCode) {
@@ -6422,6 +8831,48 @@ class ToolHandler {
         }
         return this.formatNodeDetails(node, code, outline) + this.formatTrail(cg, node);
     }
+    // Whole-file fallback caps for a drifted file (#1474).
+    static STALE_WHOLE_FILE_MAX_LINES = 300;
+    static STALE_WHOLE_FILE_MAX_CHARS = 12000;
+    /**
+     * homegraph_node render for a symbol whose file changed on disk after the
+     * last index sync (issue #1474). Indexed line ranges are untrustworthy, so
+     * no slice is emitted: small files get full CURRENT source; large ones get
+     * an explicit notice.
+     */
+    renderStaleNodeSection(cg, node, includeCode) {
+        const lines = [
+            `**${node.name}** (${node.kind})`,
+            '',
+            `**Location:** ${node.filePath}${node.startLine ? `:${node.startLine}` : ''} — ⚠ as of the last index sync; the file has changed on disk since, so this line may be shifted`,
+        ];
+        if (node.signature) {
+            lines.push(...formatNodeSignatureBlock(node.signature));
+        }
+        lines.push('');
+        let embedded = false;
+        if (includeCode) {
+            try {
+                const absPath = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), node.filePath);
+                if (absPath && (0, fs_1.existsSync)(absPath) && !(0, utils_1.isConfigLeafNode)(node)) {
+                    const content = (0, fs_1.readFileSync)(absPath, 'utf-8');
+                    const body = content.replace(/\n+$/, '');
+                    if (body.length <= ToolHandler.STALE_WHOLE_FILE_MAX_CHARS &&
+                        body.split('\n').length <= ToolHandler.STALE_WHOLE_FILE_MAX_LINES) {
+                        lines.push(`> ⚠ \`${node.filePath}\` changed on disk after it was last indexed, so the indexed line range for this symbol may no longer match. Showing the file's full CURRENT source instead (Read-parity — treat it as already Read):`, '', '```' + (node.language || ''), numberSourceLines(body, 1), '```');
+                        embedded = true;
+                    }
+                }
+            }
+            catch {
+                /* fall through to the notice */
+            }
+        }
+        if (!embedded) {
+            lines.push(`> ⚠ \`${node.filePath}\` changed on disk after it was last indexed — the indexed line range for this symbol no longer reliably matches, so its body is omitted rather than risk showing a different symbol's code. For current content, call homegraph_node with \`file: "${node.filePath}"\` (no symbol; \`offset\`/\`limit\` narrow it like Read), or Read the file. The change is picked up automatically on that project's next index sync.`);
+        }
+        return lines.join('\n') + this.formatTrail(cg, node);
+    }
     /**
      * Build the "trail" for a symbol: its direct callees (what it calls) and
      * callers (what calls it), each with file:line — so homegraph_node doubles as
@@ -6466,6 +8917,16 @@ class ToolHandler {
      * Handle homegraph_status
      */
     async handleStatus(args) {
+        const sourcesMode = (0, graph_sources_1.resolveGraphSources)();
+        if (!(0, graph_sources_1.graphSourceFlags)(sourcesMode).openProjectDb) {
+            return this.textResult([
+                '**HomeGraph Status**',
+                '',
+                `**Graph sources:** ${sourcesMode}`,
+                '',
+                (0, graph_sources_1.graphSourcesDisabledGuidance)(sourcesMode),
+            ].join('\n'));
+        }
         let cg = this.getHomeGraph(args.projectPath);
         // Same trick as withStalenessNotice — when an explicit projectPath
         // resolves to the same project as the default session cg, prefer the
@@ -6493,7 +8954,9 @@ class ToolHandler {
         if (mismatch) {
             lines.push(`> ⚠ ${(0, worktree_1.worktreeMismatchWarning)(mismatch).replace(/\n/g, '\n> ')}`, '');
         }
-        lines.push(`**Files indexed:** ${stats.fileCount}`, `**Total nodes:** ${stats.nodeCount}`, `**Total edges:** ${stats.edgeCount}`, `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`);
+        lines.push(`**Files indexed:** ${stats.fileCount}`, `**Total nodes:** ${stats.nodeCount}`, `**Total edges:** ${stats.edgeCount}`, `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`, ...(stats.walSizeBytes > 0
+            ? [`**WAL size:** ${(stats.walSizeBytes / 1024 / 1024).toFixed(2)} MB`]
+            : []), `**Graph sources:** ${cg.getGraphSources()}`);
         // Surface the active SQLite backend: node:sqlite → better-sqlite3 → wasm.
         const backend = cg.getBackend();
         if (backend === 'node-sqlite') {
@@ -6552,6 +9015,27 @@ class ToolHandler {
         }
         return this.textResult(lines.join('\n'));
     }
+    /**
+     * Handle homegraph_arkui_migrate — one-shot ArkUI migrate / state snapshot (spec 0007).
+     */
+    async handleArkuiMigrate(args) {
+        const scope = this.validateString(args.scope, 'scope');
+        if (typeof scope !== 'string')
+            return scope;
+        const cg = this.getHomeGraph(args.projectPath);
+        try {
+            const snapshot = cg.getArkUIMigrateSnapshot(scope);
+            return this.textResult(JSON.stringify(snapshot, null, 2));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return this.textResult([
+                `No ArkUI migrate snapshot for scope "${scope}".`,
+                message,
+                'Pass a component name, relative .ets path, or directory prefix. Ensure the project is indexed (`homegraph init` / `index`).',
+            ].join('\n'));
+        }
+    }
     /**
      * Handle homegraph_files - get project file structure from the index
      */
@@ -7108,6 +9592,19 @@ class ToolHandler {
         const segments = node.filePath.split('/').filter((s) => s.length > 0);
         return containerHints.every((hint) => segments.some((seg) => seg === hint || seg.replace(/\.[^.]+$/, '') === hint));
     }
+    /**
+     * Generated-file demotion signal: path convention OR persisted content banner.
+     */
+    isGeneratedCandidate(cg, filePath) {
+        if ((0, generated_detection_1.isGeneratedFile)(filePath))
+            return true;
+        try {
+            return cg.getFile(filePath)?.generated === true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Find ALL definitions matching a name, ranked, so homegraph_node can return
      * every overload instead of guessing one (the wrong guess → a Read). Keepers
@@ -7127,7 +9624,8 @@ class ToolHandler {
         if (!isQualified) {
             const exact = cg.getNodesByName(symbol);
             if (exact.length > 0) {
-                return [...exact].sort((a, b) => ((0, generated_detection_1.isGeneratedFile)(a.filePath) ? 1 : 0) - ((0, generated_detection_1.isGeneratedFile)(b.filePath) ? 1 : 0));
+                return [...exact].sort((a, b) => (this.isGeneratedCandidate(cg, a.filePath) ? 1 : 0) -
+                    (this.isGeneratedCandidate(cg, b.filePath) ? 1 : 0));
             }
             // No exact match — use the single top fuzzy result (e.g. a file basename).
             const fuzzy = cg.searchNodes(symbol, { limit: 10 });
@@ -7152,10 +9650,9 @@ class ToolHandler {
             // hit (#173); a bare name may use the single top fuzzy result.
             return isQualified ? [] : results[0] ? [results[0].node] : [];
         }
-        // Down-rank generated files (.pb.go, .pulsar.go, _grpc.pb.go, …) so a flow
-        // query prefers the keeper implementation over the protobuf-generated stub.
         return [...exactMatches]
-            .sort((a, b) => ((0, generated_detection_1.isGeneratedFile)(a.node.filePath) ? 1 : 0) - ((0, generated_detection_1.isGeneratedFile)(b.node.filePath) ? 1 : 0))
+            .sort((a, b) => (this.isGeneratedCandidate(cg, a.node.filePath) ? 1 : 0) -
+            (this.isGeneratedCandidate(cg, b.node.filePath) ? 1 : 0))
             .map((r) => r.node);
     }
     /**
@@ -7206,8 +9703,8 @@ class ToolHandler {
         // /impact aggregation aligned (a query against "Send" returns the
         // hand-written implementations before the protobuf scaffold).
         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;
+            const aGen = this.isGeneratedCandidate(cg, a.filePath) ? 1 : 0;
+            const bGen = this.isGeneratedCandidate(cg, b.filePath) ? 1 : 0;
             return aGen - bGen;
         });
         const locations = ranked.map(n => `${n.kind} at ${n.filePath}:${n.startLine}`);
@@ -7253,6 +9750,62 @@ class ToolHandler {
         }
         return lines.join('\n');
     }
+    /**
+     * At caller sites, list nearby `#include` / `import` lines — answers
+     * "which call makes Type X's definition visible" without a second Grep/Read
+     * when the agent only called `homegraph_callers`.
+     */
+    formatCallerIncludeVisibility(cg, callers) {
+        if (callers.length === 0)
+            return '';
+        let projectRoot = '';
+        try {
+            projectRoot = cg.getProjectRoot();
+        }
+        catch {
+            return '';
+        }
+        const rows = [];
+        const seen = new Set();
+        for (const caller of callers.slice(0, 8)) {
+            const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, caller.filePath);
+            if (!abs || !(0, fs_1.existsSync)(abs))
+                continue;
+            let content;
+            try {
+                content = (0, fs_1.readFileSync)(abs, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const fileLines = content.split('\n');
+            const scanTo = Math.min(fileLines.length, Math.max(120, (caller.startLine || 1) + 5));
+            for (let i = 0; i < scanTo; i++) {
+                const lineText = fileLines[i] ?? '';
+                if (!/^\s*(?:#\s*include|import\s)/.test(lineText))
+                    continue;
+                const key = `${caller.filePath}:${i + 1}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                rows.push(`- \`${caller.filePath}:${i + 1}\`  \`${lineText.trim().slice(0, 140)}\``);
+                if (rows.length >= 12)
+                    break;
+            }
+            if (rows.length >= 12)
+                break;
+        }
+        if (rows.length === 0)
+            return '';
+        return [
+            '',
+            '**Include / import at caller files** (definition visibility cues)',
+            '',
+            ...rows,
+            '',
+            '> Use these includes with the caller list when asking which call makes another type visible.',
+        ].join('\n');
+    }
     /**
      * Relationship label for a non-`calls` edge in callers/callees lists. A
      * function-as-value edge (#756) is the high-signal one: `callers(cb)`