homegraph 1.5.4 → 1.5.6

package/dist/mcp/tools.js

@@ -16,6 +16,10 @@ exports.formatStaleBanner = formatStaleBanner;
 exports.formatStaleFooter = formatStaleFooter;
 exports.formatDegradedBanner = formatDegradedBanner;
 exports.getStaticTools = getStaticTools;
+exports.extractBareUsageSymbols = extractBareUsageSymbols;
+exports.queryAsBareSymbolInventory = queryAsBareSymbolInventory;
+exports.hasPositiveAnswerNowDirective = hasPositiveAnswerNowDirective;
+exports.reconcilePartialAnswerNow = reconcilePartialAnswerNow;
 const query_pool_1 = require("./query-pool");
 const memory_budget_1 = require("./memory-budget");
 const directory_1 = require("../directory");
@@ -35,6 +39,7 @@ function __setLoadHomeGraphForTests(cls) {
     loadHomeGraphForTests = cls;
 }
 const worktree_1 = require("../sync/worktree");
+const update_check_1 = require("../upgrade/update-check");
 const graph_sources_1 = require("../graph-sources");
 const query_utils_1 = require("../search/query-utils");
 const fs_1 = require("fs");
@@ -874,6 +879,60 @@ exports.tools = [
         },
         annotations: READ_ONLY_ANNOTATIONS,
     },
+    {
+        name: 'homegraph_usages',
+        description: 'Focused in-repo usage inventory for one named API, `.member`, ALL_CAPS constant, field, or mutex. ' +
+            'Required: `query`. Returns usage files/lines only; it does not build a general flow or source dump. ' +
+            'Use directly for a narrow where-used question; `homegraph_explore` auto-routes equivalent high-confidence queries here.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Required. Exact API/member/constant/field name, with or without where-used wording.',
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['query'],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
+    {
+        name: 'homegraph_modules',
+        description: 'Focused dependency/cycle inventory for named path modules or `*common` / `*service` / `*component` / `*constants` modules. ' +
+            'Required: `query`. It does not build a general code flow or scan unrelated survey families. ' +
+            '`homegraph_explore` auto-routes equivalent high-confidence dependency questions here.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Required. Dependency/cycle question containing the exact module names or paths.',
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['query'],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
+    {
+        name: 'homegraph_native',
+        description: 'Focused NAPI/native export inventory for one named path or Type. Required: `query`. ' +
+            'Returns indexed export descriptors/registration sites without a general domain file dump. ' +
+            '`homegraph_explore` auto-routes equivalent high-confidence NAPI/export questions here.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Required. NAPI/native export question containing the exact path or Type name.',
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['query'],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
     {
         name: 'homegraph_status',
         description: 'Index health check (files / nodes / edges). No required args when a default project is loaded. Skip unless debugging.',
@@ -885,6 +944,27 @@ exports.tools = [
         },
         annotations: READ_ONLY_ANNOTATIONS,
     },
+    {
+        name: 'homegraph_project',
+        description: 'Shallow project map: modules + files per module (no symbols/call edges). ' +
+            'PRIMARY for engineering overview while the full index is still building; also useful after full index. ' +
+            'Optional `module` filters by name/path; `includeFiles` defaults true.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                module: {
+                    type: 'string',
+                    description: 'Optional module name or root path substring to filter.',
+                },
+                includeFiles: {
+                    type: 'boolean',
+                    description: 'Include per-module file lists (default true). Set false for module list only.',
+                },
+                projectPath: projectPathProperty,
+            },
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
     {
         name: 'homegraph_arkui_migrate',
         description: 'ArkUI migrate / state-semantics snapshot in ONE call (components, state decorators + args, ' +
@@ -1069,12 +1149,150 @@ function getStaticTools() {
     const allow = new Set(raw.split(',').map(s => s.trim().replace(/^homegraph_/, '').replace(/^homegraph_/, '')).filter(Boolean));
     return allow.size ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, ''))) : exports.tools;
 }
+/** Prose that reads like an identifier but never names a symbol worth scanning. */
+const BARE_USAGE_STOPWORDS = new Set([
+    'class', 'method', 'function', 'interface', 'module', 'import', 'export', 'value',
+    'file', 'files', 'code', 'usage', 'usages', 'where', 'which', 'what', 'when',
+    'call', 'calls', 'called', 'caller', 'callers', 'used', 'uses', 'using',
+    'true', 'false', 'null', 'undefined', 'this', 'return', 'const', 'type',
+    'string', 'number', 'boolean', 'object', 'array', 'void', 'async', 'await',
+]);
+/** Identifier-shaped tokens from a bare symbol bag. */
+function extractBareUsageSymbols(query) {
+    const out = [];
+    const seen = new Set();
+    const re = /\b([A-Z][A-Za-z0-9]{3,}(?:\.[A-Za-z_]\w*)?|[A-Z][A-Z0-9_]{3,}|[a-z]+[A-Z]\w{2,}(?:\.[A-Za-z_]\w*)?)\b/g;
+    for (const m of query.matchAll(re)) {
+        const tok = m[1];
+        const key = tok.toLowerCase();
+        if (seen.has(key) || BARE_USAGE_STOPWORDS.has(key))
+            continue;
+        seen.add(key);
+        out.push(tok);
+    }
+    return out;
+}
+/** Wording that asks how something works — never a plain usage inventory. */
+const FLOW_INTENT_RE = /如何|怎[么样]|机制|流程|原理|为什么|为何|架构|生命周期|时序|调用链|关系|\b(how|why|flow|mechanism|lifecycle|architecture|sequence|pipeline|between|implement|implementation)\b/i;
+/** Action-shaped identifiers are probably call-flow anchors, not inventories. */
+const ACTION_SEGMENTS = new Set([
+    'trigger', 'callback', 'handler', 'listener', 'observer', 'dispatch', 'emit',
+    'notify', 'render', 'draw', 'init', 'start', 'stop', 'update', 'refresh',
+    'subscribe', 'publish', 'invoke', 'execute', 'run', 'process', 'handle',
+    'post', 'send', 'receive', 'load', 'save', 'open', 'close',
+]);
+function identifierSegments(token) {
+    return token
+        .replace(/[._]/g, ' ')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+/**
+ * True only for a short bag of ALL_CAPS constants. Type/method bags remain on
+ * explore-flow because routing those to usages would discard call paths.
+ */
+function queryAsBareSymbolInventory(query) {
+    if (process.env.HOMEGRAPH_EXPLORE_SHAPE_ROUTING === '0')
+        return false;
+    const tokens = String(query || '').split(/[\s,、，]+/).filter(Boolean);
+    if (tokens.length === 0 || tokens.length > 6)
+        return false;
+    if (FLOW_INTENT_RE.test(query))
+        return false;
+    if (tokens.some((t) => identifierSegments(t).some((s) => ACTION_SEGMENTS.has(s))))
+        return false;
+    return tokens.every((t) => /^[A-Z][A-Z0-9_]{3,}$/.test(t));
+}
 /**
  * Tool handler that executes tools against a HomeGraph instance
  *
  * Supports cross-project queries via the projectPath parameter.
  * Other projects are opened on-demand and cached for performance.
  */
+const ANSWER_NOW_TOKEN = /\bANSWER NOW\b/gi;
+/** Whether one ANSWER NOW occurrence is postponed/negated rather than a stop directive. */
+function isNegatedAnswerNowAt(text, index) {
+    const prefix = text
+        .slice(Math.max(0, index - 96), index)
+        .replace(/[*_`]/g, '')
+        .replace(/\s+/g, ' ');
+    return /(?:\b(?:do|should|must|can)\s+not|\bcannot|\bnever|\bbefore|\buntil|\bnot)\s+(?:\S+\s+){0,3}$/i
+        .test(prefix);
+}
+/** True only for a positive instruction to stop and answer, not "do not/before ANSWER NOW". */
+function hasPositiveAnswerNowDirective(text) {
+    const answerNow = new RegExp(ANSWER_NOW_TOKEN.source, ANSWER_NOW_TOKEN.flags);
+    for (let match = answerNow.exec(text); match; match = answerNow.exec(text)) {
+        if (!isNegatedAnswerNowAt(text, match.index))
+            return true;
+    }
+    return false;
+}
+function stripPositiveAnswerNowFromLine(line) {
+    let changed = false;
+    let out = line.replace(/\*\*[^*\n]*\bANSWER NOW\b[^*\n]*\*\*/gi, (span, offset, source) => {
+        const tokenOffset = span.search(/\bANSWER NOW\b/i);
+        if (tokenOffset < 0 || isNegatedAnswerNowAt(source, offset + tokenOffset))
+            return span;
+        changed = true;
+        return '';
+    });
+    out = out.replace(ANSWER_NOW_TOKEN, (token, offset, source) => {
+        if (isNegatedAnswerNowAt(source, offset))
+            return token;
+        changed = true;
+        return '';
+    });
+    if (!changed)
+        return { text: line, changed: false };
+    // A positive close often carries a matching search prohibition. Once the
+    // whole response is Partial, that prohibition is contradictory too.
+    out = out
+        .replace(/\s*(?:[,;—-]\s*)?(?:and\s+)?do\s+\*{0,2}not\*{0,2}\s+(?:(?:re-)?(?:Read|Grep|Glob)|`?homegraph_(?:search|explore|node|callers|callees)`?)[^.;\n]*/gi, '')
+        .replace(/\s*(?:[,;—-]\s*)?no\s+(?:glob|grep|read|search|explore)(?:\s*\/\s*(?:glob|grep|read|search|explore))*\s+needed\b[^.;\n]*/gi, '')
+        .replace(/\(\s*[,;—-]*\s*\)/g, '')
+        .replace(/\s{2,}/g, ' ')
+        .replace(/\s+([.;,])/g, '$1')
+        .replace(/^(>\s*)[\s.;,—-]+/, '$1')
+        .trimEnd();
+    return { text: out, changed: true };
+}
+/**
+ * Drop stop-searching directives from an output that also declares itself partial.
+ *
+ * Section builders each append their own footer and cannot see their siblings, so
+ * one output can carry both `**Partial locator**` ("these are anchors, keep
+ * looking") and `**ANSWER NOW**` ("stop, do not Grep"). Measured on a 54-question
+ * run: 21 such outputs across 17 of 48 questions. Whichever the agent obeys, the
+ * other was wrong — it either answers from an inventory the tool just called
+ * incomplete, or it keeps searching against an explicit prohibition.
+ *
+ * Partial wins: an under-informed agent that keeps looking recovers, while one
+ * that stops on a partial answer cannot. Negated mentions (`do **not** ANSWER
+ * NOW`) are the correct pairing and are preserved.
+ */
+function reconcilePartialAnswerNow(text) {
+    if (!/\*\*Partial locator\*\*/i.test(text))
+        return text;
+    let changed = false;
+    const out = text
+        .split('\n')
+        .map((line) => {
+        if (!/ANSWER NOW/i.test(line))
+            return line;
+        const stripped = stripPositiveAnswerNowFromLine(line);
+        if (stripped.changed)
+            changed = true;
+        return stripped.text;
+    })
+        .filter((line) => line.trim() !== '>')
+        .join('\n');
+    if (!changed)
+        return text;
+    return `${out}\n\n> This survey is a **Partial locator**: the sections above are anchors, not a closed answer. Continue with the narrower lookup named above, or a text search, before answering.`;
+}
 class ToolHandler {
     cg;
     // Cache of opened HomeGraph instances for cross-project queries
@@ -1262,6 +1480,7 @@ class ToolHandler {
                 'homegraph_search',
                 'homegraph_node',
                 'homegraph_diff_impact',
+                'homegraph_project',
             ]);
             if (stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
                 visible = visible.filter(t => TINY_REPO_CORE_TOOLS.has(t.name));
@@ -1671,11 +1890,6 @@ class ToolHandler {
                 this.catchUpGate = null;
                 await this.awaitCatchUpGate(gate);
             }
-            // Hard process RSS ceiling — any tool/path that already pushed us over must
-            // stop with success-shaped Partial (never OOM / multi-GB growth).
-            if ((0, memory_budget_1.isOverRssBudget)()) {
-                return (0, memory_budget_1.rssBudgetPartialResult)(toolName);
-            }
             // Honor the optional tool allowlist (HOMEGRAPH_MCP_TOOLS): a trimmed
             // surface rejects ablated tools defensively even if a client cached them.
             if (!this.isToolAllowed(toolName)) {
@@ -1761,6 +1975,19 @@ class ToolHandler {
             if (toolName === 'homegraph_status') {
                 return await this.handleStatus(args);
             }
+            // While auto-init is still on the fast/indexing phases (no symbols yet),
+            // deep tools return guidance so the agent uses homegraph_project instead
+            // of abandoning HomeGraph after empty explore results.
+            if (toolName !== 'homegraph_project') {
+                try {
+                    const gated = this.maybeDeepToolPhaseGate(this.getHomeGraph(projectPath), toolName);
+                    if (gated)
+                        return gated;
+                }
+                catch {
+                    /* NotIndexed / sources disabled — fall through to normal handlers */
+                }
+            }
             // Every read tool races a deadline ≪ MCP client ~60s hard timeout and
             // Named-member / local-compact questions finish in tens of ms on the warm
             // main connection. Serving them here — before the query-pool offload —
@@ -1772,9 +1999,12 @@ class ToolHandler {
                     try {
                         const cgFast = this.getHomeGraph(projectPath);
                         const rootFast = cgFast.getProjectRoot();
-                        const fast = (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
-                            ? this.tryFastInventoryExplore(cgFast, q, rootFast)
+                        const fast = (toolName === 'homegraph_explore'
+                            ? this.trySpecializedExploreRoute(cgFast, q, rootFast)
                             : null)
+                            ?? (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
+                                ? this.tryFastInventoryExplore(cgFast, q, rootFast)
+                                : null)
                             ?? (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
                                 ? this.tryLightMechanismExplore(cgFast, q, rootFast)
                                 : null)
@@ -1960,7 +2190,8 @@ class ToolHandler {
             || toolName === 'homegraph_node'
             || toolName === 'homegraph_callers'
             || toolName === 'homegraph_callees'
-            || toolName === 'homegraph_files';
+            || toolName === 'homegraph_files'
+            || toolName === 'homegraph_project';
         const work = () => {
             if (!light && this.queryPool && this.queryPool.healthy) {
                 return this.queryPool.run(toolName, args, {
@@ -2045,6 +2276,16 @@ class ToolHandler {
      * NotIndexed/PathRefusal, which {@link executeReadTool} classifies.
      */
     async dispatchTool(toolName, args) {
+        if (toolName !== 'homegraph_project' && toolName !== 'homegraph_status') {
+            try {
+                const gated = this.maybeDeepToolPhaseGate(this.getHomeGraph(args.projectPath), toolName);
+                if (gated)
+                    return gated;
+            }
+            catch {
+                /* fall through */
+            }
+        }
         switch (toolName) {
             case 'homegraph_search': return await this.handleSearch(args);
             case 'homegraph_callers': return await this.handleCallers(args);
@@ -2052,8 +2293,12 @@ class ToolHandler {
             case 'homegraph_impact': return await this.handleImpact(args);
             case 'homegraph_diff_impact': return await this.handleDiffImpact(args);
             case 'homegraph_explore': return await this.handleExplore(args);
+            case 'homegraph_usages': return await this.handleSpecializedUsages(args);
+            case 'homegraph_modules': return await this.handleSpecializedModules(args);
+            case 'homegraph_native': return await this.handleSpecializedNative(args);
             case 'homegraph_node': return await this.handleNode(args);
             case 'homegraph_files': return await this.handleFiles(args);
+            case 'homegraph_project': return await this.handleProject(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);
@@ -2061,6 +2306,36 @@ class ToolHandler {
             default: return this.errorResult(`Unknown tool: ${toolName}`);
         }
     }
+    /**
+     * Gate symbol/graph tools while auto-init is still on the fast map or
+     * background full index (and no nodes exist yet). Success-shaped guidance —
+     * never isError — so agents keep using HomeGraph.
+     */
+    maybeDeepToolPhaseGate(cg, _toolName) {
+        const phase = cg.getBuildPhase();
+        if (phase === 'full')
+            return null;
+        try {
+            if (cg.getStats().nodeCount > 0)
+                return null;
+        }
+        catch {
+            /* ignore */
+        }
+        if (phase === 'fast' || phase === 'indexing') {
+            return this.textResult([
+                `Full symbol index is still building (phase=${phase}).`,
+                'Use `homegraph_project` for the module/file map now, then retry this tool once indexing finishes.',
+            ].join('\n'));
+        }
+        if (phase === 'building_fast' || phase === 'none') {
+            return this.textResult([
+                'HomeGraph is still preparing the project map.',
+                'Retry in a few seconds, or call `homegraph_project` once the fast build completes.',
+            ].join('\n'));
+        }
+        return null;
+    }
     async handleSearch(args) {
         const query = this.validateString(args.query, 'query');
         if (typeof query !== 'string')
@@ -2074,6 +2349,17 @@ class ToolHandler {
         // getProjectRoot) must fall through to FTS search rather than error.
         try {
             const projectRoot = cg.getProjectRoot();
+            // Bare PascalCase type search — agents almost always fan out callers next;
+            // route to caller inventory instead of FTS → node×N.
+            if ((0, query_utils_1.queryIsTypeNameFocus)(query)) {
+                const types = (0, query_utils_1.extractTypeNamesFromQuery)(query);
+                if (types.length === 1) {
+                    const callerQ = `${types[0]} 哪些方法被外部调用`;
+                    const callerRedirect = this.tryFastInventoryExplore(cg, callerQ, projectRoot);
+                    if (callerRedirect)
+                        return callerRedirect;
+                }
+            }
             if ((0, query_utils_1.queryShouldPreferExploreOverSearch)(query)) {
                 const exploreRedirect = this.tryFastInventoryExplore(cg, query, projectRoot)
                     ?? this.tryLightMechanismExplore(cg, query, projectRoot)
@@ -2177,8 +2463,6 @@ class ToolHandler {
             const callers = [];
             const labels = new Map();
             for (const node of defNodes) {
-                if ((0, memory_budget_1.isOverRssBudget)())
-                    break;
                 for (const c of cg.getCallers(node.id)) {
                     if (!seen.has(c.node.id)) {
                         seen.add(c.node.id);
@@ -3604,14 +3888,13 @@ class ToolHandler {
     /**
      * Multi-module / circular dependency survey — lean cycle list, not an import flood.
      */
-    buildModuleDependencySurveySection(cg, query) {
-        // Prefer leaf module tokens (`launchercommon`) over shared parents (`staticcommon`)
-        // — parent matches flood unrelated windowscene cycles.
+    extractFocusedModuleNames(query) {
         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))
+            if (!/^(?:static|staticcommon|feature|product|base|basecommon|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();
@@ -3619,6 +3902,12 @@ class ToolHandler {
                 leafModules.add(leaf);
             }
         }
+        return leafModules;
+    }
+    buildModuleDependencySurveySection(cg, query) {
+        // Prefer leaf module tokens (`launchercommon`) over shared parents (`staticcommon`)
+        // — parent matches flood unrelated windowscene cycles.
+        const leafModules = this.extractFocusedModuleNames(query);
         if (leafModules.size === 0)
             return { section: '', hitCount: 0 };
         const rel = (p) => p.replace(/\\/g, '/');
@@ -3671,6 +3960,155 @@ class ToolHandler {
         lines.push('');
         return { section: lines.join('\n'), hitCount: matchedCycles.length };
     }
+    /** Bounded manifest-only dependency graph for modules named in the query. */
+    buildFocusedModuleManifestSection(projectRoot, query) {
+        const moduleNames = this.extractFocusedModuleNames(query);
+        if (moduleNames.size === 0)
+            return { section: '', manifestCount: 0, cycleCount: 0 };
+        const skipDirs = new Set([
+            'node_modules', 'oh_modules', '.git', '.homegraph', '.hvigor', '.preview',
+            'build', 'dist', 'out', 'test', 'ohosTest',
+        ]);
+        const queue = [{ rel: '', depth: 0 }];
+        const manifests = new Map();
+        const linterFiles = [];
+        const asksDetection = /构建系统|如何检测|怎么检测|检测方式|linter|build\s+system|how.{0,24}detect/i.test(query);
+        let visited = 0;
+        let cursor = 0;
+        while (cursor < queue.length && visited < 8000) {
+            const { rel, depth } = queue[cursor++];
+            visited++;
+            const abs = (0, path_1.resolve)(projectRoot, rel);
+            let entries;
+            try {
+                entries = (0, fs_1.readdirSync)(abs, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            const leaf = rel.split('/').pop()?.toLowerCase() ?? '';
+            if (moduleNames.has(leaf) && entries.some((entry) => entry.isFile() && entry.name === 'oh-package.json5')) {
+                const paths = manifests.get(leaf) ?? [];
+                if (paths.length < 3)
+                    paths.push(rel ? `${rel}/oh-package.json5` : 'oh-package.json5');
+                manifests.set(leaf, paths);
+            }
+            for (const entry of entries) {
+                const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+                if (entry.isFile()) {
+                    if (/^(?:code-)?linter.*\.json5?$/i.test(entry.name) && linterFiles.length < 8) {
+                        linterFiles.push(childRel);
+                    }
+                    continue;
+                }
+                if (!entry.isDirectory() || depth >= 6)
+                    continue;
+                if (entry.name.startsWith('.') || skipDirs.has(entry.name))
+                    continue;
+                queue.push({ rel: childRel, depth: depth + 1 });
+            }
+            if (manifests.size === moduleNames.size && (!asksDetection || linterFiles.length > 0))
+                break;
+        }
+        if (manifests.size === 0)
+            return { section: '', manifestCount: 0, cycleCount: 0 };
+        const normalizeDependency = (name) => {
+            const noProtocol = name.replace(/^file:/i, '').replace(/\\/g, '/');
+            return noProtocol.split('/').filter(Boolean).pop()?.toLowerCase() ?? '';
+        };
+        const graph = new Map();
+        const rows = [];
+        for (const moduleName of [...moduleNames].sort()) {
+            const manifestPaths = manifests.get(moduleName) ?? [];
+            if (manifestPaths.length === 0) {
+                rows.push(`- \`${moduleName}\` — manifest not found within the bounded project scan`);
+                graph.set(moduleName, new Set());
+                continue;
+            }
+            const manifestRel = manifestPaths[0];
+            let parsed;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                parsed = require('jsonc-parser').parse((0, fs_1.readFileSync)((0, path_1.resolve)(projectRoot, manifestRel), 'utf-8'));
+            }
+            catch {
+                rows.push(`- \`${moduleName}\` — could not parse \`${manifestRel}\``);
+                graph.set(moduleName, new Set());
+                continue;
+            }
+            const deps = parsed?.dependencies;
+            const declared = deps && typeof deps === 'object' ? Object.entries(deps) : [];
+            const namedDeps = new Set();
+            for (const [depName, depValue] of declared) {
+                const candidates = [normalizeDependency(depName)];
+                if (typeof depValue === 'string')
+                    candidates.push(normalizeDependency(depValue));
+                for (const candidate of candidates) {
+                    if (candidate !== moduleName && moduleNames.has(candidate))
+                        namedDeps.add(candidate);
+                }
+            }
+            graph.set(moduleName, namedDeps);
+            const target = namedDeps.size > 0
+                ? [...namedDeps].sort().map((name) => `\`${name}\``).join(', ')
+                : '(none among the named modules)';
+            rows.push(`- \`${moduleName}\` → ${target} — \`${manifestRel}\` (${declared.length} declared dependencies total)`);
+        }
+        const cycles = new Set();
+        const visit = (start, current, path, seen) => {
+            for (const next of graph.get(current) ?? []) {
+                if (next === start && path.length > 1) {
+                    const core = path;
+                    const rotations = core.map((_, index) => {
+                        const rotated = [...core.slice(index), ...core.slice(0, index)];
+                        return [...rotated, rotated[0]].join(' -> ');
+                    });
+                    cycles.add(rotations.sort()[0]);
+                    continue;
+                }
+                if (seen.has(next))
+                    continue;
+                visit(start, next, [...path, next], new Set([...seen, next]));
+            }
+        };
+        for (const moduleName of graph.keys())
+            visit(moduleName, moduleName, [moduleName], new Set([moduleName]));
+        const lines = [
+            '**Named module manifest dependencies**', '', ...rows, '',
+            cycles.size > 0
+                ? `Detected **${cycles.size}** cycle(s) among the named modules:`
+                : 'Detected **no cycle** among the named modules.',
+        ];
+        for (const cycle of cycles)
+            lines.push(`- \`${cycle}\``);
+        if (asksDetection) {
+            lines.push('', '**Build / linter cycle checks**', '');
+            let matched = 0;
+            for (const rel of linterFiles) {
+                let fileLines = [];
+                try {
+                    fileLines = (0, fs_1.readFileSync)((0, path_1.resolve)(projectRoot, rel), 'utf-8').split('\n');
+                }
+                catch {
+                    continue;
+                }
+                for (let i = 0; i < fileLines.length; i++) {
+                    const line = fileLines[i] ?? '';
+                    if (!/no-cycle|circular|cycle/i.test(line))
+                        continue;
+                    lines.push(`- \`${rel}:${i + 1}\` — \`${line.trim().slice(0, 140)}\``);
+                    if (++matched >= 12)
+                        break;
+                }
+                if (matched >= 12)
+                    break;
+            }
+            if (matched === 0)
+                lines.push('- No explicit cycle-check rule was found in the bounded linter-config scan.');
+        }
+        lines.push('');
+        return { section: lines.join('\n'), manifestCount: manifests.size, cycleCount: cycles.size };
+    }
     /**
      * Path-module / named-Type NAPI export surface — not a 50-file domain dump.
      */
@@ -4177,6 +4615,9 @@ class ToolHandler {
         const eventFiles = new Set();
         const enumMembers = [];
         const seenMember = new Set();
+        /** Exported `*Event` classes from a named Event module file (not enum members). */
+        const eventClasses = [];
+        const seenEventClass = new Set();
         const considerEventFile = (fp, preferredName) => {
             eventFiles.add(fp);
             if (/Event$/i.test(preferredName))
@@ -4192,10 +4633,21 @@ class ToolHandler {
                         seenMember.add(key);
                         enumMembers.push({ name: sib.name, file: rel(sib.filePath), line: sib.startLine || 1 });
                     }
-                    // Only add sibling Types that are themselves *Event (avoid file-wide enum spam).
+                    // Barrel / module files often export many `*Event` classes (not enums).
                     if ((sib.kind === 'enum' || sib.kind === 'class' || sib.kind === 'type_alias' || sib.kind === 'interface')
                         && /Event$/i.test(sib.name)) {
                         eventNames.add(sib.name);
+                        if (sib.kind === 'class' || sib.kind === 'enum' || sib.kind === 'type_alias') {
+                            const ck = `${sib.name}:${rel(sib.filePath)}`;
+                            if (!seenEventClass.has(ck)) {
+                                seenEventClass.add(ck);
+                                eventClasses.push({
+                                    name: sib.name,
+                                    file: rel(sib.filePath),
+                                    line: sib.startLine || 1,
+                                });
+                            }
+                        }
                     }
                 }
             }
@@ -4262,6 +4714,7 @@ class ToolHandler {
             '**Event types → Manager / handler sites**',
             '',
         ];
+        const rankedClasses = [...eventClasses].sort((a, b) => a.name.localeCompare(b.name));
         if (enumMembers.length > 0) {
             lines.push('### Event enum members (indexed)');
             for (const m of enumMembers.slice(0, 40)) {
@@ -4271,8 +4724,25 @@ class ToolHandler {
                 lines.push(`- … and ${enumMembers.length - 40} more`);
             lines.push('');
         }
+        // Named `*Event` module files often export many Event classes (not enums).
+        // Listing them is the answer to "有哪些事件类型" — don't force Grep for members.
+        if (eventClasses.length > 0) {
+            lines.push('### Event type classes (exported from Event module)');
+            for (const c of rankedClasses.slice(0, 40)) {
+                lines.push(`- \`${c.name}\` — \`${c.file}:${c.line}\``);
+            }
+            if (rankedClasses.length > 40) {
+                lines.push(`- … and ${rankedClasses.length - 40} more Event class(es)`);
+            }
+            lines.push('');
+        }
         lines.push('### Event Type anchors');
-        const sortedEvents = [...eventNames].sort((a, b) => a.localeCompare(b));
+        // Prefer concrete Event classes over the barrel file stem when both exist.
+        const anchorEvents = (eventClasses.length > 0
+            ? eventClasses.map((c) => c.name)
+            : [...eventNames]).filter((n, i, arr) => arr.indexOf(n) === i)
+            .sort((a, b) => a.localeCompare(b));
+        const sortedEvents = anchorEvents;
         for (const ev of sortedEvents.slice(0, 12)) {
             let loc = '';
             try {
@@ -4281,6 +4751,11 @@ class ToolHandler {
                     loc = ` — \`${rel(n.filePath)}:${n.startLine}\``;
             }
             catch { /* */ }
+            if (!loc) {
+                const fromClass = eventClasses.find((c) => c.name === ev);
+                if (fromClass)
+                    loc = ` — \`${fromClass.file}:${fromClass.line}\``;
+            }
             if (!loc) {
                 for (const fp of eventFiles) {
                     const base = rel(fp).split('/').pop() || '';
@@ -4296,7 +4771,7 @@ class ToolHandler {
         lines.push('');
         // Search handlers by primary Event names (+ a few members), not every noisy sibling.
         const searchKeys = [
-            ...sortedEvents.slice(0, 6),
+            ...sortedEvents.slice(0, 12),
             ...enumMembers.slice(0, 12).map((m) => m.name),
         ];
         const hits = new Map();
@@ -4355,13 +4830,112 @@ class ToolHandler {
             }
         }
         const ranked = [...hits.values()].sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+        const consumerHits = [];
+        const consumerSeen = new Set();
+        const eventNamesForConsumers = rankedClasses.length > 0
+            ? rankedClasses.map((c) => c.name)
+            : sortedEvents;
+        const addConsumer = (file, line, snippet, event, score) => {
+            const key = `${file}:${line}:${event}`;
+            if (consumerSeen.has(key))
+                return;
+            consumerSeen.add(key);
+            consumerHits.push({ file, line, snippet: snippet.slice(0, 120), event, score });
+        };
+        for (const ev of eventNamesForConsumers.slice(0, 24)) {
+            let results = [];
+            try {
+                results = cg.searchNodes(ev, { limit: 36 });
+            }
+            catch {
+                continue;
+            }
+            const esc = ev.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const onRe = new RegExp(`(?:InnerEventUtil|evtBus|eventMgr|EventMgr|focusMode\\w*EventMgr)\\.on\\s*\\(\\s*${esc}|\\.on\\s*\\(\\s*${esc}`);
+            const seenFiles = new Set();
+            for (const r of results) {
+                const fp = rel(r.node.filePath);
+                if ((0, query_utils_1.isTestFile)(fp) || eventFiles.has(r.node.filePath))
+                    continue;
+                if (seenFiles.has(fp))
+                    continue;
+                seenFiles.add(fp);
+                const abs = (0, path_1.isAbsolute)(r.node.filePath)
+                    ? r.node.filePath
+                    : (0, path_1.join)(projectRoot, r.node.filePath);
+                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 (!onRe.test(line) && !line.includes(`produceOn(${ev}`) && !line.includes(`produceOn(${ev},`)) {
+                        continue;
+                    }
+                    let score = 4;
+                    if (/Controller|Manager|Handler|Vm$/i.test(fp))
+                        score += 6;
+                    if (/\.on\s*\(/.test(line))
+                        score += 4;
+                    if (/produceOn/.test(line))
+                        score += 3;
+                    addConsumer(fp, i + 1, line.trim(), ev, score);
+                }
+            }
+        }
+        // DataShareManager produceOn registrations (producer side of dispatch).
+        let mgrNodes = [];
+        try {
+            mgrNodes = cg.getNodesByName('DataShareManager').filter((n) => !(0, query_utils_1.isTestFile)(n.filePath));
+        }
+        catch {
+            mgrNodes = [];
+        }
+        for (const n of mgrNodes.slice(0, 2)) {
+            const fp = rel(n.filePath);
+            const abs = (0, path_1.isAbsolute)(n.filePath) ? n.filePath : (0, path_1.join)(projectRoot, n.filePath);
+            try {
+                const fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+                for (let i = 0; i < fileLines.length; i++) {
+                    const line = fileLines[i] ?? '';
+                    if (!/produceOn\s*\(/.test(line))
+                        continue;
+                    const evM = line.match(/produceOn\s*\(\s*([A-Za-z_][\w]*Event)/);
+                    const evName = evM?.[1] ?? 'produceOn';
+                    addConsumer(fp, i + 1, line.trim(), evName, 5);
+                    if (consumerHits.length >= 10)
+                        break;
+                }
+            }
+            catch { /* optional */ }
+        }
+        consumerHits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+        if (consumerHits.length > 0) {
+            lines.push('### Event consumer registrations (`.on` / `produceOn`)');
+            for (const h of consumerHits.slice(0, 16)) {
+                lines.push(`- \`${h.file}:${h.line}\` ← \`${h.event}\`  \`${h.snippet}\``);
+            }
+            if (consumerHits.length > 16) {
+                lines.push(`- … and ${consumerHits.length - 16} more consumer site(s)`);
+            }
+            lines.push('');
+        }
         lines.push('### Manager / handler files referencing these events');
         const memberCount = enumMembers.length;
-        // Complete only when we have enum members (the usual "有哪些类型") + ≥1 handler,
-        // or a small tight Type set with strong handlers — never a huge Type dump alone.
+        const eventClassCount = eventClasses.length;
+        const dispatchAsk = /分发|分发给|DataShareMgr|dispatch|routed?\s+to/i.test(query);
+        // Complete when: enum members + handlers, OR Event classes + consumer wiring
+        // for dispatch asks, OR a tight Event Type set.
         const complete = ranked.length > 0
-            && ((memberCount > 0 && memberCount <= 48)
-                || (sortedEvents.length > 0 && sortedEvents.length <= 4 && ranked.length >= 1 && ranked[0].score >= 5));
+            && ((memberCount > 0 && memberCount <= 48 && ranked.length >= 1)
+                || (eventClassCount >= 3 && eventClassCount <= 64
+                    && (dispatchAsk ? consumerHits.length >= 2 : ranked.length >= 1))
+                || (sortedEvents.length > 0 && sortedEvents.length <= 4 && ranked.length >= 1 && ranked[0].score >= 5)
+                || (dispatchAsk && consumerHits.length >= 3));
         if (ranked.length === 0) {
             lines.push('- No Manager import/use sites indexed for these event types.');
             lines.push('');
@@ -4379,8 +4953,16 @@ class ToolHandler {
                 lines.push(`- … and ${ranked.length - 24} more handler file(s)`);
             lines.push('');
             if (complete) {
-                lines.push('> Event→Manager inventory — **ANSWER NOW** from enum members + handler files above; '
-                    + 'ONE narrow Grep only if a specific `case` branch is still missing.');
+                lines.push(eventClassCount > 0
+                    ? '> Event→Manager inventory — **ANSWER NOW** from Event type classes + consumer `.on` / handler files above; '
+                        + 'ONE narrow Grep only if a specific Manager→event branch is still missing.'
+                    : '> Event→Manager inventory — **ANSWER NOW** from enum members + handler files above; '
+                        + 'ONE narrow Grep only if a specific `case` branch is still missing.');
+            }
+            else if (eventClassCount >= 3 && dispatchAsk && consumerHits.length === 0) {
+                lines.push('> **Partial locator** — Event type list above is complete, but consumer `.on` / dispatch wiring '
+                    + 'was not indexed. ONE Grep for `.on(EventName` or `produceOn` in `*Manager*` files — '
+                    + 'do **not** repo-storm; do **not** ANSWER NOW as a full dispatch map.');
             }
             else {
                 lines.push('> **Partial locator** — handler files are anchors, but enum-member coverage may be incomplete. '
@@ -4390,10 +4972,10 @@ class ToolHandler {
         lines.push('');
         return {
             section: lines.join('\n'),
-            hitCount: ranked.length + memberCount,
-            eventCount: Math.max(sortedEvents.length, memberCount > 0 ? 1 : 0),
+            hitCount: ranked.length + memberCount + eventClassCount,
+            eventCount: Math.max(sortedEvents.length, eventClassCount, memberCount > 0 ? 1 : 0),
             handlerCount: ranked.length,
-            memberCount,
+            memberCount: memberCount + eventClassCount,
             complete,
         };
     }
@@ -4493,19 +5075,61 @@ class ToolHandler {
         lines.push('### Cross links (imports / callers)');
         if (edges.length === 0) {
             lines.push('- No import/caller edges indexed between these Types yet.');
-            lines.push('');
-            lines.push('> **Partial locator** — Type files above are anchors. '
-                + '`homegraph_node` / `homegraph_callees` one Type at a time; do **not** ANSWER NOW as a full graph.');
         }
         else {
             const uniq = [...new Set(edges)].slice(0, 40);
             lines.push(...uniq);
+        }
+        lines.push('');
+        // Text-scan `extends Base` when graph edges are missing — shared bases are
+        // the usual answer to "这几个 Installer/Parser 的依赖关系".
+        const extendsHits = [];
+        const baseNames = new Set();
+        let projectRoot = '';
+        try {
+            projectRoot = cg.getProjectRoot();
+        }
+        catch { /* */ }
+        for (const a of locs) {
+            let content = '';
+            try {
+                const full = (0, path_1.isAbsolute)(a.file) ? a.file : (projectRoot ? (0, path_1.join)(projectRoot, a.file) : '');
+                if (full && (0, fs_1.existsSync)(full))
+                    content = (0, fs_1.readFileSync)(full, 'utf-8');
+            }
+            catch { /* */ }
+            if (!content)
+                continue;
+            const m = content.match(new RegExp(`(?:export\\s+)?(?:abstract\\s+)?class\\s+${a.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s+extends\\s+([A-Za-z_][A-Za-z0-9_]*)`));
+            if (!m?.[1])
+                continue;
+            const base = m[1];
+            baseNames.add(base);
+            extendsHits.push(`- \`${a.name}\` extends \`${base}\``);
+        }
+        if (extendsHits.length > 0) {
+            lines.push('### Inheritance (source `extends`)');
+            lines.push(...[...new Set(extendsHits)].slice(0, 20));
+            if (baseNames.size > 0) {
+                lines.push('');
+                lines.push(`Shared / parent Type(s): ${[...baseNames].slice(0, 8).map((b) => `\`${b}\``).join(', ')}.`);
+            }
             lines.push('');
-            lines.push('> Multi-Type dependency inventory — **ANSWER NOW** from locations + edges above; '
-                + 'only `homegraph_node` one Type if a body detail is still missing.');
+        }
+        const hasGraph = edges.length > 0;
+        const hasExtends = extendsHits.length > 0;
+        if (!hasGraph && !hasExtends) {
+            lines.push('> **Partial locator** — Type files above are anchors. '
+                + '`homegraph_node` / `homegraph_callees` one Type at a time; do **not** ANSWER NOW as a full graph.');
+        }
+        else {
+            lines.push('> Multi-Type dependency inventory — **ANSWER NOW** from locations'
+                + (hasExtends ? ' + `extends` bases' : '')
+                + (hasGraph ? ' + import/caller edges' : '')
+                + ' above; only `homegraph_node` one Type if a body detail is still missing.');
         }
         lines.push('');
-        return { section: lines.join('\n'), hitCount: locs.length + edges.length };
+        return { section: lines.join('\n'), hitCount: locs.length + edges.length + extendsHits.length };
     }
     /**
      * Main-thread fast path for inventory surveys — skips the worker queue.
@@ -4522,7 +5146,8 @@ class ToolHandler {
             const cg = this.getHomeGraph(args.projectPath);
             const projectRoot = cg.getProjectRoot();
             if (toolName === 'homegraph_explore') {
-                return this.tryFastInventoryExplore(cg, query, projectRoot)
+                return this.trySpecializedExploreRoute(cg, query, projectRoot)
+                    ?? this.tryFastInventoryExplore(cg, query, projectRoot)
                     ?? this.tryLightMechanismExplore(cg, query, projectRoot)
                     ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot);
             }
@@ -4537,13 +5162,240 @@ class ToolHandler {
         }
         return null;
     }
+    /** Conservative compatibility router: ambiguous mechanism queries stay broad. */
+    specializedExploreRouteForQuery(query) {
+        if ((0, query_utils_1.queryAsModuleDependencySurvey)(query))
+            return 'modules';
+        if ((0, query_utils_1.queryAsModuleExportSurvey)(query))
+            return 'native';
+        if ((0, query_utils_1.queryAsReturnValueConsumerSurvey)(query))
+            return null;
+        if ((0, query_utils_1.shouldBuildApiUsageSurvey)(query))
+            return 'usages';
+        if (queryAsBareSymbolInventory(query))
+            return 'usages';
+        if (!(0, query_utils_1.shouldBuildMemberSurvey)(query))
+            return null;
+        return /哪里(?:用|使用|调用)|哪些.{0,24}(?:用|使用|调用|依赖)|使用位置|引用位置|调用位置|\busages?\b|\bwhere\b.{0,36}\bused\b|\bwhich\b.{0,36}\b(?:files?|functions?|methods?)\b.{0,24}\b(?:use|call|depend)/i.test(query)
+            ? 'usages'
+            : null;
+    }
+    /** Run exactly one bounded survey family and expose the selected route. */
+    runSpecializedExploreRoute(route, cg, query, projectRoot) {
+        let section = '';
+        let status = 'no_indexed_evidence';
+        let coverage = '';
+        if (route === 'modules') {
+            const manifestResult = this.buildFocusedModuleManifestSection(projectRoot, query);
+            const graphResult = manifestResult.manifestCount === 0
+                ? this.buildModuleDependencySurveySection(cg, query)
+                : { section: '', hitCount: 0 };
+            section = manifestResult.section || graphResult.section;
+            status = section ? 'complete' : 'no_indexed_evidence';
+            coverage = manifestResult.manifestCount > 0
+                ? 'named module manifests plus bounded linter evidence only; no full-repo cycle walk or unrelated surveys were built'
+                : 'named-module dependency/cycle graph only; no source bodies or unrelated surveys were built';
+        }
+        else if (route === 'native') {
+            const result = this.buildModuleExportSurveySection(cg, query, projectRoot);
+            section = result.section;
+            status = result.hitCount > 0 ? 'complete' : 'no_indexed_evidence';
+            coverage = 'named path/Type NAPI export registrations only; no domain file dump was built';
+        }
+        else {
+            const apiUsage = (0, query_utils_1.shouldBuildApiUsageSurvey)(query)
+                ? this.buildApiUsageSection(cg, query, projectRoot)
+                : { section: '', fileCount: 0 };
+            const memberUsage = (0, query_utils_1.shouldBuildMemberSurvey)(query)
+                && !((0, query_utils_1.queryAsFieldUsageSurvey)(query) && apiUsage.fileCount > 0)
+                ? this.buildMemberSurveySection(cg, query, projectRoot)
+                : '';
+            let scanned = (0, query_utils_1.shouldBuildApiUsageSurvey)(query) || (0, query_utils_1.shouldBuildMemberSurvey)(query);
+            section = [apiUsage.section, memberUsage].filter(Boolean).join('\n');
+            if (!section) {
+                const bare = this.buildBareSymbolUsageSection(cg, query, projectRoot);
+                scanned = scanned || bare.scanned;
+                section = bare.section;
+            }
+            status = section ? 'complete' : (scanned ? 'no_indexed_evidence' : 'not_surveyed');
+            coverage = 'named API/member/constant/field usage sites only; no general call-flow or source dump was built';
+        }
+        const body = section
+            || (status === 'not_surveyed'
+                ? '- No survey ran: this query carries no symbol name to scan. Re-run naming the symbol(s), or use `homegraph_explore`.'
+                : '- No matching evidence was found in the current index for this focused survey.');
+        return this.textResult(this.truncateOutput([
+            `**HomeGraph specialized route: ${route}**`,
+            `Status: ${status}`,
+            `Coverage: ${coverage}.`,
+            '',
+            body,
+        ].join('\n')));
+    }
+    /** Usage sites for a bare symbol bag, including non-call textual references. */
+    buildBareSymbolUsageSection(cg, query, projectRoot) {
+        const symbols = extractBareUsageSymbols(query);
+        if (symbols.length === 0)
+            return { section: '', scanned: false };
+        const MAX_SYMBOLS = 4;
+        const MAX_FILES_SCANNED = 80;
+        const MAX_FILES_REPORTED = 14;
+        const MAX_LINES_PER_FILE = 3;
+        const rel = (p) => p.replace(/\\/g, '/');
+        const byFile = new Map();
+        const seenFiles = new Set();
+        let matchedFiles = 0;
+        const matchers = symbols.slice(0, MAX_SYMBOLS).map((sym) => ({
+            sym,
+            re: new RegExp(`\\b${sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`),
+        }));
+        const scanFile = (fp) => {
+            const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, fp);
+            if (!abs)
+                return { rows: [], bytes: 0 };
+            let content;
+            try {
+                content = (0, fs_1.readFileSync)(abs, 'utf-8');
+            }
+            catch {
+                return { rows: [], bytes: 0 };
+            }
+            const bytes = content.length;
+            const hit = matchers.filter((m) => m.re.test(content));
+            if (hit.length === 0)
+                return { rows: [], bytes };
+            const fileLines = content.split('\n');
+            const rows = [];
+            for (let i = 0; i < fileLines.length && rows.length < MAX_LINES_PER_FILE; i++) {
+                const text = (fileLines[i] ?? '').trim();
+                if (!text)
+                    continue;
+                const m = hit.find((x) => x.re.test(text));
+                if (m)
+                    rows.push({ line: i + 1, text, symbol: m.sym });
+            }
+            return { rows, bytes };
+        };
+        const record = (fp, rows) => {
+            if (rows.length === 0)
+                return;
+            matchedFiles++;
+            if (byFile.size < MAX_FILES_REPORTED)
+                byFile.set(fp, rows);
+        };
+        for (const { sym } of matchers) {
+            let nodes = [];
+            try {
+                nodes = cg.searchNodes(sym, { limit: 60 });
+            }
+            catch {
+                continue;
+            }
+            for (const r of nodes) {
+                if (seenFiles.size >= MAX_FILES_SCANNED)
+                    break;
+                const fp = rel(r.node.filePath);
+                if ((0, query_utils_1.isTestFile)(fp) || seenFiles.has(fp))
+                    continue;
+                seenFiles.add(fp);
+                record(fp, scanFile(fp).rows);
+            }
+        }
+        const SWEEP_DEADLINE_MS = 3000;
+        const SWEEP_MAX_FILES = 20000;
+        const SWEEP_MAX_BYTES = 256 * 1024 * 1024;
+        let sweepRan = false;
+        let sweepComplete = false;
+        if (process.env.HOMEGRAPH_EXPLORE_USAGE_SWEEP !== '0') {
+            let corpus = [];
+            try {
+                corpus = cg.getFiles();
+            }
+            catch {
+                corpus = [];
+            }
+            if (corpus.length > 0) {
+                sweepRan = true;
+                sweepComplete = true;
+                const started = Date.now();
+                let swept = 0;
+                let bytesRead = 0;
+                for (const f of corpus) {
+                    if (swept >= SWEEP_MAX_FILES || bytesRead >= SWEEP_MAX_BYTES
+                        || (swept % 64 === 0 && Date.now() - started > SWEEP_DEADLINE_MS)) {
+                        sweepComplete = false;
+                        break;
+                    }
+                    const fp = rel(String(f?.path ?? ''));
+                    if (!fp || (0, query_utils_1.isTestFile)(fp) || seenFiles.has(fp))
+                        continue;
+                    seenFiles.add(fp);
+                    swept++;
+                    const scan = scanFile(fp);
+                    bytesRead += scan.bytes;
+                    record(fp, scan.rows);
+                }
+            }
+        }
+        if (byFile.size === 0)
+            return { section: '', scanned: true };
+        const truncated = matchedFiles > byFile.size;
+        const lines = [
+            `**Symbol usage sites** — \`${symbols.slice(0, MAX_SYMBOLS).join('`, `')}\``, '',
+            sweepRan && sweepComplete
+                ? '> Full in-repo text sweep of every indexed source file: includes non-call references with no `calls` edge.'
+                : '> Scanned in-repo: includes non-call references with no `calls` edge.',
+            '',
+        ];
+        for (const [file, rows] of byFile) {
+            lines.push(`- \`${file}\``);
+            for (const row of rows)
+                lines.push(`    - ${row.line}: \`${row.text.slice(0, 120)}\``);
+        }
+        lines.push('');
+        if (truncated) {
+            lines.push(`> Showing ${byFile.size} of ${matchedFiles} matching file(s) — narrow the symbol to see the rest.`);
+        }
+        else if (sweepRan && sweepComplete) {
+            lines.push(`> ${byFile.size} file(s) — every indexed source file was swept, so this is the complete in-repo list. **ANSWER NOW** from it: do not re-grep these names.`);
+        }
+        else {
+            lines.push(`> ${byFile.size} indexed use site file(s); the text sweep did not complete, so files that merely reference these names may be missing.`);
+        }
+        return { section: lines.join('\n'), scanned: true };
+    }
+    trySpecializedExploreRoute(cg, query, projectRoot) {
+        const route = this.specializedExploreRouteForQuery(query);
+        return route ? this.runSpecializedExploreRoute(route, cg, query, projectRoot) : null;
+    }
+    async handleSpecializedUsages(args) {
+        const query = this.validateString(args.query, 'query');
+        if (typeof query !== 'string')
+            return query;
+        const cg = this.getHomeGraph(args.projectPath);
+        return this.runSpecializedExploreRoute('usages', cg, query, cg.getProjectRoot());
+    }
+    async handleSpecializedModules(args) {
+        const query = this.validateString(args.query, 'query');
+        if (typeof query !== 'string')
+            return query;
+        const cg = this.getHomeGraph(args.projectPath);
+        return this.runSpecializedExploreRoute('modules', cg, query, cg.getProjectRoot());
+    }
+    async handleSpecializedNative(args) {
+        const query = this.validateString(args.query, 'query');
+        if (typeof query !== 'string')
+            return query;
+        const cg = this.getHomeGraph(args.projectPath);
+        return this.runSpecializedExploreRoute('native', cg, query, cg.getProjectRoot());
+    }
     /**
      * Fast inventory-only explore — skips findRelevantContext for survey/caller/dependency queries.
      */
     tryFastInventoryExplore(cg, query, projectRoot) {
         if (!(0, query_utils_1.shouldTryFastInventoryExplore)(query))
             return null;
-        // Multi-Type dependency asks: inventory-only early exit (avoids fat compact / 25s busy).
+        // Multi-Type dependency asks: inventory-only early exit (avoids fat compact / busy timeout).
         if ((0, query_utils_1.queryAsMultiTypeDependencySurvey)(query)) {
             const multi = this.buildMultiTypeDependencySection(cg, query);
             if (multi.section) {
@@ -4706,6 +5558,11 @@ class ToolHandler {
             : { section: '', hitCount: 0 };
         if (hoverResult.section)
             lines.push(hoverResult.section);
+        const containerResult = (0, query_utils_1.queryAsContainerCompositionSurvey)(query)
+            ? this.buildContainerCompositionSection(cg, query, projectRoot)
+            : { section: '', hitCount: 0, complete: false };
+        if (containerResult.section)
+            lines.push(containerResult.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 —
@@ -4758,7 +5615,7 @@ class ToolHandler {
             || callerSection || memberSection || configSection
             || systemCapResult.section || declarationResult.section || moduleDepResult.section
             || moduleExportResult.section || dtsWrapResult.section || controlSyncResult.section
-            || eventDispatchResult.section;
+            || eventDispatchResult.section || containerResult.section;
         if (!hasAnySection)
             return null;
         // Data-source / API usage inventories are complete without source dumps —
@@ -4833,6 +5690,11 @@ class ToolHandler {
                 : 'Event→Manager survey — 0 event types / handlers indexed. **Partial locator** — do **not** ANSWER NOW; '
                     + 'ONE Grep for enum members / `case` branches OK.');
         }
+        if (containerResult.section && (0, query_utils_1.queryAsContainerCompositionSurvey)(query)) {
+            return finishCompact(containerResult.complete
+                ? `Container composition survey — **${containerResult.hitCount}** page/site(s). **ANSWER NOW** from injection snippets above; do not Grep \`LocalStorageLink\` again.`
+                : `Container composition survey — **${containerResult.hitCount}** site(s). **Partial locator** — Read the top page file for full build() wiring.`);
+        }
         if (apiUsageResult.fileCount > 0 && !dataSourceResult.section) {
             return finishCompact(`API usage survey — **${apiUsageResult.fileCount}** file(s). **ANSWER NOW** from the list above.`);
         }
@@ -5069,16 +5931,21 @@ class ToolHandler {
                     const n = cg.getNode(id);
                     if (!n)
                         continue;
-                    // Always keep domain Manager/Service hits — they are the locator answer.
+                    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();
+                    const hitsDistinctive = distinctive.some((t) => blob.includes(t.toLowerCase()));
+                    const hitsPathTok = domainPathTokens.some((t) => blob.includes(t));
+                    // Domain Manager/Service hits must still match the distinctive stem
+                    // (e.g. `xml`) — otherwise agent EN bags (`xml parser`) keep every
+                    // `*Parser*Manager` that only matched the verb noun.
                     if ((0, query_utils_1.isDomainRoleSymbol)(n.name, n.filePath, domainPathTokens)) {
-                        keep.add(id);
+                        if (hitsDistinctive || hitsPathTok)
+                            keep.add(id);
                         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())))
+                    if (hitsDistinctive)
                         keep.add(id);
-                    if (domainPathTokens.some((t) => blob.includes(t)))
+                    if (hitsPathTok)
                         keep.add(id);
                 }
                 if (keep.size > 0) {
@@ -5134,12 +6001,15 @@ class ToolHandler {
             : 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()) && t.length >= 4)).slice(0, 4).join(' ');
+                    .filter((t) => /^[\x00-\x7F]+$/.test(t) && !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase()) && t.length >= 3)).slice(0, 4).join(' ');
         const importResult = importQuery
             ? this.buildImportSitesSection(cg, importQuery, projectRoot)
             : { section: '', siteCount: 0, compactListing: false };
         if (importResult.section) {
-            const trimmed = this.trimLightImportSection(importResult.section, 5);
+            // Wider + path-diversified when a distinctive stem exists (e.g. xml→convertxml
+            // usages span backup/ + util/ — first-N-only hid judge keypoints).
+            const importBullets = distinctiveEarly.length > 0 ? 8 : 5;
+            const trimmed = this.trimLightImportSection(importResult.section, importBullets);
             if (trimmed)
                 lines.push(trimmed);
         }
@@ -5184,7 +6054,7 @@ class ToolHandler {
                 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()) && t.length >= 4);
+        const distinctiveForScore = (0, query_utils_1.extractDomainSearchTerms)(query).filter((t) => /^[\x00-\x7F]+$/.test(t) && !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase()) && t.length >= 3);
         const apiSeeds = (0, query_utils_1.extractMechanismEntrySeeds)(query)
             .map((s) => s.toLowerCase())
             .filter((s) => s.length >= 5 && !query_utils_1.GENERIC_VERB_ANCHOR_NOISE.has(s));
@@ -5206,6 +6076,12 @@ class ToolHandler {
                 if (t.length >= 4 && fpLc.includes(t))
                     score += 20;
             }
+            if ((0, query_utils_1.queryAsNativeRenderThreadSurvey)(query)) {
+                if (/plugin_manager|egl_core|nativerender|xcomponent|render_service/i.test(fpLc))
+                    score += 90;
+                if (/\.cpp$|\.h$|cmake/i.test(fpLc))
+                    score += 25;
+            }
             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();
@@ -5301,10 +6177,32 @@ class ToolHandler {
             return null;
         // Soft-close when inventory + at least one digest exist — enough to answer
         // with ONE narrow Grep; avoid Partial→re-explore churn.
+        // Also close when distinctive-stem import evidence + digests exist but no
+        // *Manager* survived filtering (xml/convertxml how-implemented bags).
         const digestCoversNext = !!(nextMgr && sortedFiles.some(([fp]) => fp === nextMgr.filePath)
             && filesRendered > 0);
-        const softClose = hasStrongManager && filesRendered >= 1
-            && (digestCoversNext || managerHits.length >= 2 || topIsStrong);
+        const importEvidenceClose = distinctiveEarly.length > 0
+            && importResult.siteCount >= 3
+            && filesRendered >= 1;
+        const xmlStem = distinctiveEarly.some((t) => t.toLowerCase() === 'xml');
+        const bodyText = lines.join('\n');
+        const xmlMechanismClose = xmlStem
+            && filesRendered >= 1
+            && /convertxml|ConvertXML|fastConvertToJSObject/i.test(bodyText);
+        const nativeRenderClose = (0, query_utils_1.queryAsNativeRenderThreadSurvey)(query)
+            && filesRendered >= 1
+            && (/plugin_manager|egl_core|OnSurfaceCreated|EGLCore|nativerender/i.test(bodyText)
+                || /\*\*CMake \/ link \+ GL libs\*\*/.test(bodyText));
+        // Don't soft-close onto an antithetical Primary (Delete* while ask is install/parse).
+        const nextContradictsPipeline = !!(nextMgr
+            && /(?:解析|安装|激活|下载|parse|install|activate|download)/i.test(query)
+            && (/^(?:Delete|Remove|Uninstall|Clear|Cancel)/i.test(nextMgr.name)
+                || /Delete|Uninstall|RemoveOnline|CancelRestore/i.test(nextMgr.name)));
+        const softClose = !nextContradictsPipeline && ((hasStrongManager && filesRendered >= 1
+            && (digestCoversNext || managerHits.length >= 2 || topIsStrong))
+            || importEvidenceClose
+            || xmlMechanismClose
+            || nativeRenderClose);
         const closedAnswer = softClose || mechanismClosed || (hasFlowPath && topIsStrong);
         lines.push('---');
         if (mechanismClosed || (hasFlowPath && topIsStrong)) {
@@ -5501,7 +6399,32 @@ class ToolHandler {
                 header.push(line);
             }
         }
-        const chosen = [...prod, ...test].slice(0, maxBullets);
+        // Round-robin across top path prefixes so one product/ folder cannot hide
+        // other convertxml / kit usage sites (backup vs util vs launchercommon).
+        const diversify = (items, max) => {
+            const buckets = new Map();
+            for (const line of items) {
+                const pathMatch = line.match(/^- `([^`]+)`/);
+                const fp = (pathMatch?.[1]?.split(':')[0] ?? '').replace(/\\/g, '/');
+                const parts = fp.split('/').filter(Boolean);
+                const key = parts.length >= 3 ? `${parts[0]}/${parts[1]}/${parts[2]}` : (parts.length >= 2 ? `${parts[0]}/${parts[1]}` : (parts[0] || fp || '_'));
+                const list = buckets.get(key) ?? [];
+                list.push(line);
+                buckets.set(key, list);
+            }
+            const keys = [...buckets.keys()];
+            const out = [];
+            let i = 0;
+            while (out.length < max && keys.some((k) => (buckets.get(k)?.length ?? 0) > 0)) {
+                const k = keys[i % keys.length];
+                const list = buckets.get(k);
+                if (list && list.length > 0)
+                    out.push(list.shift());
+                i++;
+            }
+            return out;
+        };
+        const chosen = diversify([...prod, ...test], maxBullets);
         const out = [...header, ...chosen];
         if (prod.length + test.length > maxBullets) {
             out.push(`- … (light-mechanism: showing ${maxBullets} sites, tests deprioritized — **ANSWER NOW**, do not Grep the same import)`);
@@ -5593,6 +6516,7 @@ class ToolHandler {
         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 uiConsequence = (0, query_utils_1.queryAsMemberUiConsequenceSurvey)(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)
@@ -5852,29 +6776,43 @@ class ToolHandler {
         const multiTypeThin = typeNames.length >= 2
             && !(0, query_utils_1.queryHasNamedMemberFocus)(query)
             && !(0, query_utils_1.queryAsNamedComponentAction)(query);
+        let lifecycleStubComplete = false;
+        let lifecycleStubSection = '';
+        if (typeLifecycle && stubHeavy) {
+            const stubPaths = [...fileNodes.keys()].filter(isStubPath);
+            const lifecycleResult = this.buildSdkStubLifecycleSection(projectRoot, stubPaths, query);
+            lifecycleStubSection = lifecycleResult.section;
+            lifecycleStubComplete = lifecycleResult.complete;
+        }
         const lines = [
             `**Exploration: ${query}**`,
             '',
-            stubHeavy
-                ? '> **Partial locator** — indexed hits are SDK / `.d.ts` stubs, not in-repo implementations. '
-                    + 'Prefer `homegraph_search` / ONE explore for `*State*` / impl class names; '
-                    + 'ONE narrow Grep for in-repo impl names is OK — do not ANSWER NOW from the stub alone.'
-                : resourceProvenanceAsk
-                    ? '> **Partial locator** — component shells below are anchors. '
-                        + 'Confirm `$r` / Image / download call sites in the dialog body (or ONE narrow Grep for `$r` / `http`) before ANSWER NOW.'
-                    : multiTypeThin
-                        ? '> **Partial locator** — multi-Type bag below is a coarse anchor set. '
-                            + 'Pick ONE Type/`Type.member` for a tighter explore, or ONE narrow Grep for unindexed wiring — do **not** ANSWER NOW as a full cross-Type mechanism.'
-                        : '> **Coarse locate complete.** Treat Source + trail as already Read for these symbols. '
-                            + 'Answer from them; do **not** re-Grep/Read/node the same symbols. '
-                            + 'ONE narrow Grep is OK only for residual literals / unindexed wiring — not a repo-wide storm.',
+            lifecycleStubComplete
+                ? '> **Coarse locate complete — SDK lifecycle inventory below.** **ANSWER NOW** from state enum + callbacks; '
+                    + 'do not Grep in-repo or re-explore the same stub names.'
+                : stubHeavy
+                    ? '> **Partial locator** — indexed hits are SDK / `.d.ts` stubs, not in-repo implementations. '
+                        + 'Prefer `homegraph_search` / ONE explore for `*State*` / impl class names; '
+                        + 'ONE narrow Grep for in-repo impl names is OK — do not ANSWER NOW from the stub alone.'
+                    : resourceProvenanceAsk
+                        ? '> **Coarse locate — check Source digests for `$r` / Image / download.** '
+                            + 'Treat visible bodies as already Read. ONE narrow Grep for `$r`/`http` only if digests lack load origin — '
+                            + 'do **not** re-explore or fan out Read on the same Page/Dialog.'
+                        : multiTypeThin
+                            ? '> **Partial locator** — multi-Type bag below is a coarse anchor set. '
+                                + 'Pick ONE Type/`Type.member` for a tighter explore, or ONE narrow Grep for unindexed wiring — do **not** ANSWER NOW as a full cross-Type mechanism.'
+                            : '> **Coarse locate complete.** Treat Source + trail as already Read for these symbols. '
+                                + 'Answer from them; do **not** re-Grep/Read/node the same symbols. '
+                                + 'ONE narrow Grep is OK only for residual literals / unindexed wiring — not a repo-wide storm.',
             '',
             `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).',
             '',
         ];
-        if (stubHeavy && implAsk) {
+        if (lifecycleStubSection)
+            lines.push(lifecycleStubSection);
+        if (stubHeavy && implAsk && !lifecycleStubComplete) {
             lines.push('> Stub-only compact — state/callback answers usually live in project `.ets` / `.ts` under the feature, not `@ohos.*.d.ts`.', '');
         }
         // Bare `BadgeManager`-style compact: surface real @ohos/@kit / sibling Managers.
@@ -5971,7 +6909,15 @@ class ToolHandler {
                 trail.push('');
                 lines.push(...trail);
             }
-            else if (!stubHeavy && !resourceProvenanceAsk && !multiTypeThin) {
+            else if (!stubHeavy
+                && !resourceProvenanceAsk
+                && !multiTypeThin
+                // UI Page/Dialog surfaces + member text-usage already answer without a
+                // graph trail — flipping to Partial caused ThemeHome/isExpired fan-out
+                // (163355 flat-but-worse-cost / score drops).
+                && !componentSurface
+                && !uiCluster
+                && !memberFocus) {
                 // No graph trail — coarse locate only; do not claim completeness.
                 const softIdx = lines.findIndex((l) => l.includes('**Coarse locate complete.**'));
                 if (softIdx >= 0) {
@@ -6107,7 +7053,10 @@ class ToolHandler {
                 }
                 lines.push('');
                 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.'
+                    ? uiConsequence
+                        ? '> UI-consequence ask: call/filter sites above show **how true/expired values affect UI** '
+                            + '(often exclusion from render stacks). **ANSWER NOW** from them + Source — do not Read/Grep the same member.'
+                        : '> 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('');
             }
@@ -6216,7 +7165,7 @@ class ToolHandler {
             .slice(0, maxFiles);
         const digest = exploreLocatorDigestEnabled();
         lines.push(digest ? '**Source digests**' : '**Source Code**', '');
-        lines.push(stubHeavy
+        lines.push(stubHeavy && !lifecycleStubComplete
             ? '> Stub digests only — treat as Partial locator. Do **not** ANSWER NOW from `.d.ts` alone; search in-repo impl next.'
             : digest
                 ? '> Short digests — treat as already Read for these symbols. Answer from anchors + digests; '
@@ -6391,26 +7340,255 @@ class ToolHandler {
         }
         if (rendered === 0)
             return null;
+        // If provenance digests already show $r / download / PixelMap, kill any leftover
+        // Partial banner so the agent stops (163355 D17 Partial→Read fan-out).
+        if (resourceProvenanceAsk) {
+            const body = lines.join('\n');
+            if (/\$r\b|PixelMap|copyFile|http[s]?:|download|getPreview|previewPixelMap/i.test(body)) {
+                const softIdx = lines.findIndex((l) => l.includes('**Partial locator**'));
+                if (softIdx >= 0) {
+                    lines[softIdx] =
+                        '> **Coarse locate complete.** Source digests already show load origin (`$r` / download / PixelMap). '
+                            + '**ANSWER NOW** — do not Read/Grep the same Page/Dialog again.';
+                }
+            }
+        }
         lines.push('---');
         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'));
     }
+    /**
+     * When a lifecycle Type only exists as SDK `.d.ts`, extract state enums +
+     * callback registrations from the stub so agents stop grep-storming in-repo.
+     */
+    buildSdkStubLifecycleSection(projectRoot, stubFilePaths, _query) {
+        const rel = (p) => p.replace(/\\/g, '/');
+        const enums = [];
+        const callbacks = [];
+        for (const fp of stubFilePaths.slice(0, 4)) {
+            const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, fp);
+            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');
+            for (let i = 0; i < fileLines.length; i++) {
+                const line = fileLines[i] ?? '';
+                if (/^\s*enum\s+\w*State\w*\s*\{/.test(line)) {
+                    const members = [];
+                    for (let j = i + 1; j < Math.min(fileLines.length, i + 48); j++) {
+                        const l = fileLines[j] ?? '';
+                        if (/^\s*\}/.test(l))
+                            break;
+                        const m = l.match(/^\s*(\w+)\s*[,=]/);
+                        if (m?.[1])
+                            members.push(m[1]);
+                    }
+                    if (members.length > 0) {
+                        enums.push(`\`${line.trim().slice(0, 72)}\` → ${members.slice(0, 14).join(', ')}`);
+                    }
+                }
+                if (/on\s*\(\s*type\s*:\s*['"][\w]+['"]/.test(line)
+                    || /Register the callback|Register.*Callback|move scene session|foreground|background|sessionStateChange/i.test(line)) {
+                    callbacks.push(`- \`${rel(fp)}:${i + 1}\`  \`${line.trim().slice(0, 110)}\``);
+                }
+            }
+        }
+        if (enums.length === 0 && callbacks.length < 3) {
+            return { section: '', complete: false };
+        }
+        const lines = [
+            '**SDK lifecycle surface (indexed stub)**',
+            '',
+            '> Lifecycle Type is stub-only — state enum + callbacks below are authoritative. **ANSWER NOW**; '
+                + 'do not Grep in-repo for the same SDK API names.',
+            '',
+        ];
+        if (enums.length > 0) {
+            lines.push('**State enum(s)**', '');
+            for (const e of enums.slice(0, 4))
+                lines.push(`- ${e}`);
+            lines.push('');
+        }
+        if (callbacks.length > 0) {
+            lines.push('**Callbacks / transitions**', '');
+            lines.push(...callbacks.slice(0, 22));
+            if (callbacks.length > 22)
+                lines.push(`- … and ${callbacks.length - 22} more`);
+            lines.push('');
+        }
+        const complete = enums.length > 0 && callbacks.length >= 3;
+        return { section: lines.join('\n'), complete: complete || callbacks.length >= 6 };
+    }
+    /**
+     * Pages sharing a container component + how they inject differentiated
+     * ViewModel / LocalStorage state into the shared shell.
+     */
+    buildContainerCompositionSection(cg, query, projectRoot) {
+        const types = (0, query_utils_1.extractTypeNamesFromQuery)(query).filter((t) => !(0, query_utils_1.isFrameworkUiDecoratorName)(t));
+        const containerName = types.find((t) => /(?:Screen|Page|View|Container)$/i.test(t))
+            ?? types.find((t) => /Screen/i.test(t))
+            ?? types[0];
+        const viewModelName = types.find((t) => /ViewModel$/i.test(t));
+        if (!containerName)
+            return { section: '', hitCount: 0, complete: false };
+        const rel = (p) => p.replace(/\\/g, '/');
+        const hits = [];
+        const seen = new Set();
+        const ingestFile = (fp, content, baseScore) => {
+            if (seen.has(fp) || (0, query_utils_1.isTestFile)(fp))
+                return;
+            if (!content.includes(containerName))
+                return;
+            const useRe = new RegExp(`${containerName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*[({]`);
+            if (!useRe.test(content) && !content.includes(`import { ${containerName}`))
+                return;
+            const fileLines = content.split('\n');
+            const snippets = [];
+            for (let i = 0; i < fileLines.length; i++) {
+                const line = fileLines[i] ?? '';
+                if (line.includes(containerName)
+                    || /@LocalStorageLink|LocalStorageProp|screenSession/i.test(line)
+                    || (viewModelName && line.includes(viewModelName))
+                    || /new\s+\w+ViewModel/i.test(line)) {
+                    snippets.push(`L${i + 1}: ${line.trim().slice(0, 100)}`);
+                    if (snippets.length >= 4)
+                        break;
+                }
+            }
+            if (snippets.length === 0)
+                return;
+            seen.add(fp);
+            let score = baseScore;
+            if (/@LocalStorageLink/i.test(content))
+                score += 30;
+            if (/CommonScbView|EntryView|DevView/i.test(fp))
+                score += 20;
+            if (viewModelName && content.includes(viewModelName))
+                score += 15;
+            hits.push({ file: fp, snippet: snippets.join(' / '), score });
+        };
+        let results = [];
+        try {
+            results = cg.searchNodes(containerName, { kinds: ['import', 'component', 'class', 'struct'], limit: 36 });
+        }
+        catch { /* */ }
+        for (const r of results) {
+            if ((0, arkts_1.isOhosApiFilePath)(r.node.filePath))
+                continue;
+            const fp = rel(r.node.filePath);
+            if (!/\.(ets|tsx|jsx|vue|svelte)$/i.test(fp))
+                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;
+            }
+            ingestFile(fp, content, 12);
+        }
+        if (hits.length < 4) {
+            try {
+                for (const f of cg.getFiles()) {
+                    if (hits.length >= 14)
+                        break;
+                    const fp = rel(f.path);
+                    if (!/\.ets$/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;
+                    }
+                    ingestFile(fp, content, 8);
+                }
+            }
+            catch { /* optional */ }
+        }
+        hits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+        if (hits.length === 0)
+            return { section: '', hitCount: 0, complete: false };
+        const lines = [
+            '**Container composition / ViewModel injection survey**',
+            '',
+            `> Pages using \`${containerName}\`${viewModelName ? ` with \`${viewModelName}\`` : ''}. `
+                + '**ANSWER NOW** from injection snippets — do not fan out Read/callers per page.',
+            '',
+        ];
+        for (const h of hits.slice(0, 10)) {
+            lines.push(`- \`${h.file}\` — ${h.snippet.slice(0, 220)}`);
+        }
+        if (hits.length > 10)
+            lines.push(`- … and ${hits.length - 10} more`);
+        lines.push('');
+        const complete = hits.length >= 2
+            && hits.some((h) => /@LocalStorageLink|screenSession|ViewModel/i.test(h.snippet));
+        return { section: lines.join('\n'), hitCount: Math.min(hits.length, 10), complete };
+    }
     /**
      * 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 searchTerms = topicBoost
+            ? [
+                'onHover', 'AppIconCommonView', 'HoverAnimationUtil', 'AppIconHoverEvent',
+                'setIconHoverEventIface', 'HoverAnimation', 'HoverEffect',
+            ]
+            : ['onHover', 'HoverAnimation', 'HoverEffect', 'HoverConstants', 'hover'];
         const seen = new Set();
         const hits = [];
+        const scoreHit = (r, term, snippet) => {
+            const nameLc = r.node.name.toLowerCase();
+            const pathLc = r.node.filePath.toLowerCase().replace(/\\/g, '/');
+            const termLc = term.toLowerCase();
+            let score = nameLc === 'onhover' || nameLc.startsWith('onhover') ? 40 : 10;
+            if (/hover/.test(nameLc))
+                score += 15;
+            if (/onhover/.test(snippet.toLowerCase()))
+                score += 35;
+            if (/appiconcommonview|hoveranimationutil|appiconhover/i.test(nameLc))
+                score += 45;
+            if (/seticonhover|geticonhover/i.test(nameLc))
+                score += 35;
+            if (topicBoost && /launchercommon|launchericon|appicon|smartdock|appcenter/i.test(pathLc)) {
+                score += 50;
+            }
+            if (topicBoost && /controlcenter|commonconstants|controlpanel/i.test(pathLc)) {
+                score -= 45;
+            }
+            if (topicBoost && nameLc === 'hoverconstants' && !/launcher|appicon/i.test(pathLc)) {
+                score -= 40;
+            }
+            if (topicBoost && /import/.test(snippet) && !/onhover|hoveranimation|appicon/i.test(snippet.toLowerCase())) {
+                score -= 25;
+            }
+            if (termLc === 'onhover' && /component|struct/.test(r.node.kind))
+                score += 10;
+            return score;
+        };
         for (const term of searchTerms) {
             let results = [];
             try {
                 results = cg.searchNodes(term, {
-                    kinds: ['method', 'function', 'property', 'field', 'variable', 'constant', 'class', 'component'],
+                    kinds: ['method', 'function', 'property', 'field', 'variable', 'constant', 'class', 'component', 'struct'],
                     limit: 30,
                 });
             }
@@ -6429,11 +7607,6 @@ class ToolHandler {
                 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);
@@ -6445,12 +7618,38 @@ class ToolHandler {
                     }
                 }
                 catch { /* keep signature */ }
+                // App icon views often expose `.onHover` on a builder line — scan nearby.
+                if (topicBoost && /appiconcommonview/i.test(pathLc)) {
+                    try {
+                        const abs = (0, utils_1.validatePathWithinRoot)(projectRoot, r.node.filePath);
+                        if (abs && (0, fs_1.existsSync)(abs)) {
+                            const lines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+                            for (let i = 0; i < lines.length; i++) {
+                                if (!/\.onHover\s*\(/.test(lines[i] ?? ''))
+                                    continue;
+                                const hk = `${r.node.filePath}:${i + 1}:onHover`;
+                                if (seen.has(hk))
+                                    continue;
+                                seen.add(hk);
+                                hits.push({
+                                    file: r.node.filePath,
+                                    line: i + 1,
+                                    name: 'onHover',
+                                    kind: 'property',
+                                    score: 90,
+                                    snippet: (lines[i] ?? '').trim().slice(0, 160),
+                                });
+                            }
+                        }
+                    }
+                    catch { /* optional */ }
+                }
                 hits.push({
                     file: r.node.filePath,
                     line: r.node.startLine,
                     name: r.node.name,
                     kind: r.node.kind,
-                    score,
+                    score: scoreHit(r, term, snippet),
                     snippet,
                 });
             }
@@ -6469,20 +7668,32 @@ class ToolHandler {
             };
         }
         hits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+        // Icon-hover asks: drop import-only control-center noise from the visible set.
+        const filtered = topicBoost
+            ? hits.filter((h) => {
+                const pl = h.file.toLowerCase();
+                if (h.score >= 35)
+                    return true;
+                if (/controlcenter|commonconstants/.test(pl) && h.name === 'HoverConstants')
+                    return false;
+                return h.score > 0;
+            })
+            : hits;
+        const displayHits = filtered.length > 0 ? filtered : hits;
         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);
+        const shown = displayHits.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`);
+        if (displayHits.length > shown.length)
+            lines.push(`- … and ${displayHits.length - shown.length} more`);
         lines.push('');
         return { section: lines.join('\n'), hitCount: shown.length };
     }
@@ -6633,8 +7844,8 @@ class ToolHandler {
                 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)) {
+        // Install/deps asks (incl. agent EN "parameters dependencies") — oh-package lines.
+        if ((0, query_utils_1.queryAsksKitInstallDeps)(query)) {
             const depLines = [];
             try {
                 for (const f of cg.getFiles()) {
@@ -7181,7 +8392,7 @@ class ToolHandler {
         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.
+        // Expand Telephony → telephony / @ohos.telephony / @kit.TelephonyKit call sites.
         const symbols = [];
         for (const sym of rawSymbols) {
             symbols.push(sym);
@@ -7194,6 +8405,12 @@ class ToolHandler {
                     symbols.push(ohos);
             }
         }
+        if (rawSymbols.some((s) => /^telephony$/i.test(s))) {
+            for (const kit of ['@kit.TelephonyKit', '@hms.telephony.enhanced', '@hms.telephony.vsim', 'TelephonyKit']) {
+                if (!symbols.includes(kit))
+                    symbols.push(kit);
+            }
+        }
         const rel = (p) => p.replace(/\\/g, '/');
         const hits = new Map();
         const addHit = (file, line) => {
@@ -7207,8 +8424,54 @@ class ToolHandler {
             prev.stub = prev.stub && stub;
             hits.set(fp, prev);
         };
-        for (const sym of symbols.slice(0, 6)) {
+        if (rawSymbols.some((s) => /^telephony$/i.test(s))) {
+            for (const kit of ['@kit.TelephonyKit', '@hms.telephony.enhanced', '@hms.telephony.vsim']) {
+                let importHits = [];
+                try {
+                    importHits = cg.searchNodes(kit.replace(/^@/, ''), { kinds: ['import'], limit: 40 });
+                }
+                catch {
+                    importHits = [];
+                }
+                for (const r of importHits) {
+                    const line = (0, query_utils_1.resolveImportLineFromNode)(r.node, projectRoot);
+                    if (line.includes(kit) || line.toLowerCase().includes(kit.toLowerCase())) {
+                        addHit(r.node.filePath, r.node.startLine);
+                    }
+                }
+                // FTS stem fallback (`TelephonyKit`, `telephony.vsim`, …).
+                const stem = kit.split('.').pop() ?? kit;
+                try {
+                    importHits = cg.searchNodes(stem, { kinds: ['import'], limit: 40 });
+                }
+                catch {
+                    importHits = [];
+                }
+                for (const r of importHits) {
+                    const line = (0, query_utils_1.resolveImportLineFromNode)(r.node, projectRoot);
+                    if (line.includes('@kit.TelephonyKit') || line.includes('@hms.telephony')) {
+                        addHit(r.node.filePath, r.node.startLine);
+                    }
+                }
+            }
+        }
+        for (const sym of symbols.slice(0, 8)) {
             const symLc = sym.toLowerCase();
+            if (sym.startsWith('@')) {
+                let importNodes = [];
+                try {
+                    importNodes = cg.searchNodes(sym.replace(/^@/, ''), { kinds: ['import'], limit: 28 });
+                }
+                catch {
+                    importNodes = [];
+                }
+                for (const r of importNodes) {
+                    const line = (0, query_utils_1.resolveImportLineFromNode)(r.node, projectRoot).toLowerCase();
+                    if (line.includes(symLc.replace(/^@/, '')) || line.includes(symLc)) {
+                        addHit(r.node.filePath, r.node.startLine);
+                    }
+                }
+            }
             let nodes = [];
             try {
                 nodes = cg.searchNodes(sym.replace(/^@/, ''), { limit: 40 });
@@ -7307,6 +8570,14 @@ class ToolHandler {
         const rankedFiles = [...hits.entries()].sort((a, b) => {
             if (a[1].stub !== b[1].stub)
                 return a[1].stub ? 1 : -1;
+            const telephonyBoost = (fp) => rawSymbols.some((s) => /^telephony$/i.test(s))
+                && /@kit\.telephonykit|@hms\.telephony|telephonykit/i.test(fp.toLowerCase())
+                ? -1
+                : 0;
+            const ta = telephonyBoost(a[0]);
+            const tb = telephonyBoost(b[0]);
+            if (ta !== tb)
+                return ta - tb;
             return a[0].localeCompare(b[0]);
         });
         const projectHits = rankedFiles.filter(([, v]) => !v.stub);
@@ -7344,9 +8615,17 @@ class ToolHandler {
             }
         }
         // Recompute display after call-site enrichment.
+        const telephonyBoost = (fp) => rawSymbols.some((s) => /^telephony$/i.test(s))
+            && /@kit\.telephonykit|@hms\.telephony|telephonykit/i.test(fp.toLowerCase())
+            ? -1
+            : 0;
         const rankedFiles2 = [...hits.entries()].sort((a, b) => {
             if (a[1].stub !== b[1].stub)
                 return a[1].stub ? 1 : -1;
+            const ta = telephonyBoost(a[0]);
+            const tb = telephonyBoost(b[0]);
+            if (ta !== tb)
+                return ta - tb;
             return a[0].localeCompare(b[0]);
         });
         const projectHits2 = rankedFiles2.filter(([, v]) => !v.stub);
@@ -7400,6 +8679,34 @@ class ToolHandler {
                 lines.push(`- … and ${methodNames.size - 24} more`);
             lines.push('');
         }
+        if (rawSymbols.some((s) => /^telephony$/i.test(s))) {
+            const kitSurfaces = 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, 8)) {
+                    const lineText = fileLines[ln - 1] ?? '';
+                    for (const m of lineText.matchAll(/@kit\.TelephonyKit|@hms\.telephony(?:\.\w+)?/g)) {
+                        if (m[0])
+                            kitSurfaces.add(m[0]);
+                    }
+                }
+            }
+            if (kitSurfaces.size > 0) {
+                lines.push('**@kit / @hms Telephony imports**');
+                for (const k of [...kitSurfaces].sort())
+                    lines.push(`- \`${k}\``);
+                lines.push('');
+            }
+        }
         let shown = 0;
         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);
@@ -10087,7 +11394,7 @@ 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`, ...(stats.walSizeBytes > 0
+        lines.push(`**Build phase:** ${cg.getBuildPhase()}`, `**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.
@@ -10146,8 +11453,70 @@ class ToolHandler {
                 lines.push(`- ${p.path} (edited ${ageMs}ms ago, ${label})`);
             }
         }
+        const updateNotice = (0, update_check_1.getUpdateNotice)();
+        if (updateNotice) {
+            lines.push('', '**Update available:**', updateNotice);
+        }
         return this.textResult(lines.join('\n'));
     }
+    /**
+     * Handle homegraph_project — shallow module → file map (fast build).
+     */
+    async handleProject(args) {
+        const cg = this.getHomeGraph(args.projectPath);
+        const phase = cg.getBuildPhase();
+        if (phase === 'building_fast') {
+            return this.textResult('Fast project map is still building — retry in a few seconds.');
+        }
+        let map = cg.getProjectMap({
+            module: typeof args.module === 'string' ? args.module : undefined,
+            includeFiles: args.includeFiles !== false,
+        });
+        // On-demand build for indexes that never ran the fast path (legacy / CLI init).
+        if (map.modules.length === 0) {
+            try {
+                cg.buildProjectMap();
+                if (phase === 'none') {
+                    cg.setBuildPhase(cg.getStats().nodeCount > 0 ? 'full' : 'fast');
+                }
+                map = cg.getProjectMap({
+                    module: typeof args.module === 'string' ? args.module : undefined,
+                    includeFiles: args.includeFiles !== false,
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return this.textResult(`Failed to build project map: ${message}`);
+            }
+        }
+        if (map.modules.length === 0) {
+            return this.textResult('No modules found in the project map.');
+        }
+        const FILE_CAP = 80;
+        const lines = [
+            `**Project map** (phase=${map.phase})`,
+            `modules: ${map.modules.length} · files: ${map.fileCount}`,
+            '',
+        ];
+        if (map.phase === 'fast' || map.phase === 'indexing') {
+            lines.push('_Full symbol index still building — this map has modules/files only (no call graph)._', '');
+        }
+        for (const m of map.modules) {
+            const rootLabel = m.rootPath || '.';
+            lines.push(`### ${m.name} (\`${rootLabel}\`) · ${m.kind} · ${m.fileCount} files`);
+            if (m.files && m.files.length > 0) {
+                const shown = m.files.slice(0, FILE_CAP);
+                for (const f of shown) {
+                    lines.push(`- ${f.path}`);
+                }
+                if (m.files.length > FILE_CAP) {
+                    lines.push(`- … +${m.files.length - FILE_CAP} more`);
+                }
+            }
+            lines.push('');
+        }
+        return this.textResult(lines.join('\n').trimEnd());
+    }
     /**
      * Handle homegraph_arkui_migrate — one-shot ArkUI migrate / state snapshot (spec 0007).
      */
@@ -11033,7 +12402,9 @@ class ToolHandler {
     }
     textResult(text) {
         return {
-            content: [{ type: 'text', text }],
+            // Single choke point for every tool's text, so no section builder can ship
+            // a stop-searching directive on an output that declares itself partial.
+            content: [{ type: 'text', text: reconcilePartialAnswerNow(text) }],
         };
     }
     /**