homegraph 1.5.10 → 1.6.1

package/dist/mcp/tools.js

@@ -1,33 +1,40 @@
 "use strict";
-/**
- * MCP Tool Definitions
- *
- * Defines the tools exposed by the HomeGraph MCP server.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolHandler = exports.tools = exports.PathRefusalError = exports.GraphSourcesDisabledError = exports.NotIndexedError = void 0;
+exports.ToolHandler = exports.DEFAULT_MCP_TOOL_SHORT_NAMES = exports.tools = exports.PathRefusalError = exports.GraphSourcesDisabledError = exports.NotIndexedError = void 0;
 exports.__setLoadHomeGraphForTests = __setLoadHomeGraphForTests;
 exports.normalizeQuerySpelling = normalizeQuerySpelling;
 exports.getExploreBudget = getExploreBudget;
 exports.getExploreOutputBudget = getExploreOutputBudget;
 exports.tightenExploreBudgetForQuery = tightenExploreBudgetForQuery;
 exports.exploreLocatorDigestEnabled = exploreLocatorDigestEnabled;
+exports.formatHarmonyRegistrationSources = formatHarmonyRegistrationSources;
+exports.formatHarmonyResourceHits = formatHarmonyResourceHits;
+exports.formatHarmonyCapabilityProfiles = formatHarmonyCapabilityProfiles;
+exports.isHarmonyStubBody = isHarmonyStubBody;
+exports.formatHarmonySeamNotes = formatHarmonySeamNotes;
 exports.formatStaleBanner = formatStaleBanner;
 exports.formatStaleFooter = formatStaleFooter;
 exports.formatDegradedBanner = formatDegradedBanner;
+exports.resolveMcpToolAllowlist = resolveMcpToolAllowlist;
 exports.getStaticTools = getStaticTools;
 exports.extractBareUsageSymbols = extractBareUsageSymbols;
 exports.queryAsBareSymbolInventory = queryAsBareSymbolInventory;
 exports.hasPositiveAnswerNowDirective = hasPositiveAnswerNowDirective;
 exports.reconcilePartialAnswerNow = reconcilePartialAnswerNow;
+const evidence_audit_1 = require("./evidence-audit");
+const implementation_context_1 = require("./implementation-context");
+const request_contract_1 = require("../search/request-contract");
 const query_pool_1 = require("./query-pool");
 const source_slice_identity_1 = require("./source-slice-identity");
 const evidence_rendering_1 = require("./evidence-rendering");
 const arkts_evidence_packs_1 = require("./arkts-evidence-packs");
 const evidence_paths_1 = require("../graph/evidence-paths");
 const query_plan_1 = require("../search/query-plan");
+const grammars_1 = require("../extraction/grammars");
+const project_map_1 = require("../project-map");
 const index_availability_1 = require("./index-availability");
 const directory_1 = require("../directory");
+const runtime_log_1 = require("../runtime-log");
 // Lazy-load the heavy HomeGraph chain off the MCP startup path — see the same
 // helper in engine.ts. ToolHandler must load to answer tools/list (static
 // schemas), but it must NOT drag in sqlite/query layers before the daemon binds;
@@ -55,6 +62,7 @@ const arkts_1 = require("../extraction/languages/arkts");
 const explore_session_state_1 = require("./explore-session-state");
 const explore_dedup_1 = require("./explore-dedup");
 const explore_repeat_guard_1 = require("./explore-repeat-guard");
+const locate_contract_1 = require("./locate-contract");
 const dynamic_boundaries_1 = require("./dynamic-boundaries");
 const query_cache_1 = require("./query-cache");
 const diff_impact_1 = require("./diff-impact");
@@ -565,6 +573,258 @@ function fileSectionHeader(filePath, suffix) {
         ? `${FILE_SECTION_PREFIX}${filePath}\`** — ${suffix}`
         : `${FILE_SECTION_PREFIX}${filePath}\`**`;
 }
+/**
+ * Spec 0039 — short Registration sources table from indexed Harmony profile routes.
+ * Returns null when nothing to show.
+ */
+function formatHarmonyRegistrationSources(cg, maxRows = 24) {
+    const routes = cg
+        .getNodesByKind('route')
+        .filter((n) => (0, grammars_1.isHarmonyRouteProfileJson)(n.filePath))
+        .sort((a, b) => a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine);
+    if (routes.length === 0)
+        return null;
+    const byFile = new Map();
+    for (const r of routes) {
+        const fp = r.filePath.replace(/\\/g, '/');
+        const list = byFile.get(fp) ?? [];
+        list.push(r);
+        byFile.set(fp, list);
+    }
+    const lines = [
+        '**Registration sources** (indexed Harmony route profiles — evidence from these files; do not re-Read unless editing)',
+    ];
+    let rows = 0;
+    for (const [fp, list] of byFile) {
+        lines.push(`- \`${fp}\``);
+        for (const r of list) {
+            if (rows >= maxRows) {
+                lines.push(`  - … +more routes`);
+                return lines.join('\n');
+            }
+            const page = typeof r.signature === 'string'
+                ? /pageSourceFile=([^;]+)/.exec(r.signature)?.[1]?.trim()
+                : undefined;
+            const builder = typeof r.signature === 'string'
+                ? /buildFunction=([^;]+)/.exec(r.signature)?.[1]?.trim()
+                : undefined;
+            if (page) {
+                lines.push(`  - \`${r.name}\` → \`${page}\`${builder ? ` (${builder})` : ''} @${fp}:${r.startLine}`);
+            }
+            else {
+                lines.push(`  - \`${r.name}\` @${fp}:${r.startLine}`);
+            }
+            rows++;
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Spec 0041 / 0048 §3 — short Resource hits table for element/string.json constants.
+ * Spec 0048: append up to 2 in-repo `.ets` binding anchors when signature/docstring
+ * mention `app.string.<key>`.
+ */
+function formatHarmonyResourceHits(cg, query, maxRows = 8) {
+    const constants = cg
+        .getNodesByKind('constant')
+        .filter((n) => (0, grammars_1.isHarmonyElementStringJson)(n.filePath));
+    if (constants.length === 0)
+        return null;
+    const q = query.trim();
+    const namedFile = /string\.json/i.test(q);
+    const tokens = [
+        ...new Set(q
+            .split(/[\s,;|]+/)
+            .map((t) => t.trim())
+            .filter((t) => t.length >= 2 && t.length <= 160 && !/^string\.json$/i.test(t))),
+    ].slice(0, 12);
+    const matched = constants.filter((n) => {
+        if (namedFile && tokens.length === 0)
+            return true;
+        const hay = `${n.name}\n${n.qualifiedName ?? ''}\n${n.docstring ?? ''}\n${n.signature ?? ''}`.toLocaleLowerCase();
+        return tokens.some((t) => hay.includes(t.toLocaleLowerCase()));
+    });
+    const rows = (matched.length > 0 ? matched : namedFile ? constants : [])
+        .sort((a, b) => a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine)
+        .slice(0, maxRows);
+    if (rows.length === 0)
+        return null;
+    const projectRoot = cg.getProjectRoot();
+    const etsFiles = cg.getFiles()
+        .map((f) => f.path.replace(/\\/g, '/'))
+        .filter((p) => /\.ets$/i.test(p))
+        .slice(0, 80);
+    const findBindings = (key, stringFile) => {
+        const needle = `app.string.${key}`;
+        const hits = [];
+        const modRoot = (() => {
+            const marker = '/src/main/';
+            const i = stringFile.indexOf(marker);
+            return i >= 0 ? stringFile.slice(0, i) : '';
+        })();
+        for (const rel of etsFiles) {
+            if (hits.length >= 2)
+                break;
+            if (modRoot && !(rel === modRoot || rel.startsWith(`${modRoot}/`)))
+                continue;
+            const abs = (0, path_1.join)(projectRoot, rel);
+            if (!(0, fs_1.existsSync)(abs))
+                continue;
+            let text;
+            try {
+                text = (0, fs_1.readFileSync)(abs, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const lines = text.split(/\n/);
+            for (let i = 0; i < lines.length; i++) {
+                if (hits.length >= 2)
+                    break;
+                if (lines[i].includes(needle)) {
+                    hits.push(`\`${rel}:${i + 1}\``);
+                }
+            }
+        }
+        return hits;
+    };
+    const lines = [
+        '**Resource hits** (element/string.json — searchable literals, no graph edges)',
+    ];
+    for (const n of rows) {
+        const fp = n.filePath.replace(/\\/g, '/');
+        const value = (n.docstring ?? '').slice(0, 80);
+        const shown = value ? JSON.stringify(value) : '(empty)';
+        const bounds = findBindings(n.name, fp);
+        const boundNote = bounds.length ? ` · bound ${bounds.join(', ')}` : '';
+        lines.push(`- \`${fp}:${n.startLine}\` — ${shown} → \`${n.name}\`${boundNote} · Grep \`$r('app.string.${n.name}')\` in \`.ets\``);
+    }
+    if ((matched.length || constants.length) > rows.length) {
+        lines.push(`- … +more string resources`);
+    }
+    return lines.join('\n');
+}
+const FORM_QUERY_RE = /form_config|FormExtension|服务卡片|卡片/i;
+const SHORTCUT_QUERY_RE = /shortcuts_config|\bshortcuts\b|快捷方式|长按|快捷入口/i;
+/**
+ * Spec 0048 §1–2 — Capability profiles table, or form negative evidence.
+ */
+function formatHarmonyCapabilityProfiles(cg, query, maxRows = 8) {
+    const wantForm = FORM_QUERY_RE.test(query);
+    const wantShortcut = SHORTCUT_QUERY_RE.test(query);
+    if (!wantForm && !wantShortcut)
+        return null;
+    const constants = cg.getNodesByKind('constant');
+    const routes = cg.getNodesByKind('route');
+    const formNodes = [
+        ...constants.filter((n) => (0, grammars_1.isHarmonyCapabilityProfileJson)(n.filePath)
+            && /form_config\.json$/i.test(n.filePath.replace(/\\/g, '/'))),
+        ...constants.filter((n) => (n.qualifiedName ?? '').includes('harmony.capability.form')),
+        ...routes.filter((n) => (n.name ?? '').startsWith('formAbility:')),
+    ];
+    const shortcutNodes = [
+        ...constants.filter((n) => (0, grammars_1.isHarmonyCapabilityProfileJson)(n.filePath)
+            && /shortcuts_config\.json$/i.test(n.filePath.replace(/\\/g, '/'))),
+        ...constants.filter((n) => (n.qualifiedName ?? '').includes('harmony.capability.shortcut')
+            || (n.qualifiedName ?? '').includes('harmony.shortcut.')),
+    ];
+    const lines = [];
+    if (wantForm && formNodes.length === 0) {
+        lines.push('**Capability profiles:** No in-repo form_config / FormExtensionAbility (do not treat SDK `.d.ts` as project wiring).');
+    }
+    const rows = [];
+    const pushRows = (kind, nodes) => {
+        for (const n of nodes.sort((a, b) => a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine)) {
+            if (rows.length >= maxRows)
+                break;
+            const fp = n.filePath.replace(/\\/g, '/');
+            rows.push(`- (${kind}) \`${n.name}\` @\`${fp}:${n.startLine}\`${n.signature ? ` — ${n.signature}` : ''}`);
+        }
+    };
+    if (wantForm)
+        pushRows('form', formNodes);
+    if (wantShortcut)
+        pushRows('shortcut', shortcutNodes);
+    if (rows.length > 0) {
+        lines.push('**Capability profiles** (form_config / shortcuts_config — paths only, no UI edges)');
+        lines.push(...rows);
+    }
+    return lines.length ? lines.join('\n') : null;
+}
+/** Spec 0048 §5 — detect empty / log-only method bodies. */
+function isHarmonyStubBody(source) {
+    const body = source
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/\/\/[^\n]*/g, '')
+        .trim();
+    if (!body)
+        return true;
+    const lines = body.split(/\n/).map((l) => l.trim()).filter(Boolean);
+    if (lines.length === 0)
+        return true;
+    if (lines.length > 8)
+        return false;
+    const code = lines.join('\n');
+    // Strip common wrapper braces from a method slice.
+    const inner = code.replace(/^[^{]*\{/, '').replace(/\}[^}]*$/, '').trim();
+    const stmts = inner.split(/;|\n/).map((s) => s.trim()).filter(Boolean);
+    if (stmts.length === 0)
+        return true;
+    return stmts.every((s) => /^(return(\s+[^;]*)?|hilog\.[a-zA-Z]+\s*\(|console\.(log|info|warn|error|debug)\s*\(|\/\/)/i.test(s)
+        || s === '{'
+        || s === '}');
+}
+/**
+ * Spec 0048 §5 — seam notes for located explore anchors.
+ */
+function formatHarmonySeamNotes(cg, projectRoot, located, maxAnchors = 6) {
+    if (!located.length)
+        return null;
+    const lines = [];
+    const capabilityFiles = new Set([
+        ...cg.getNodesByKind('constant').filter((n) => (0, grammars_1.isHarmonyCapabilityProfileJson)(n.filePath)),
+        ...cg.getNodesByKind('route').filter((n) => (0, grammars_1.isHarmonyRouteProfileJson)(n.filePath)),
+    ].map((n) => n.filePath.replace(/\\/g, '/')));
+    for (const loc of located.slice(0, maxAnchors)) {
+        const fp = loc.filePath.replace(/\\/g, '/');
+        const modRoot = (() => {
+            const marker = '/src/main/';
+            const i = fp.indexOf(marker);
+            return i >= 0 ? fp.slice(0, i) : fp.includes('/') ? fp.slice(0, fp.lastIndexOf('/')) : '';
+        })();
+        let profileNote = 0;
+        for (const cap of capabilityFiles) {
+            if (profileNote >= 2)
+                break;
+            if (modRoot && (cap === modRoot || cap.startsWith(`${modRoot}/`))) {
+                lines.push(`- profile near \`${loc.name}\`: \`${cap}\``);
+                profileNote++;
+            }
+        }
+        try {
+            const node = loc.id ? cg.getNode(loc.id) : null;
+            const start = node?.startLine ?? loc.startLine;
+            const end = node?.endLine ?? start + 12;
+            const abs = (0, path_1.join)(projectRoot, fp);
+            if ((0, fs_1.existsSync)(abs)) {
+                const content = (0, fs_1.readFileSync)(abs, 'utf-8');
+                const allLines = content.split(/\n/);
+                const slice = allLines.slice(Math.max(0, start - 1), Math.min(allLines.length, end)).join('\n');
+                if (isHarmonyStubBody(slice)) {
+                    lines.push(`- stub: \`${loc.name}\` @\`${fp}:${start}\``);
+                }
+            }
+        }
+        catch {
+            /* omit */
+        }
+        if (lines.length >= maxAnchors * 3)
+            break;
+    }
+    if (lines.length === 0)
+        return null;
+    return ['**Seam notes** (config paths / empty stubs — digests still count as Read)', ...lines.slice(0, 18)].join('\n');
+}
 /**
  * Per-file staleness banner emitted at the top of a tool response when the
  * file watcher has pending events for files referenced by the response.
@@ -648,10 +908,11 @@ const READ_ONLY_ANNOTATIONS = {
     openWorldHint: false,
 };
 /**
- * All HomeGraph MCP tools
+ * All HomeGraph MCP tool definitions (handlers stay registered).
  *
- * Prefer the smallest tool that answers: callers/node for one named symbol,
- * explore for multi-file flows. Skip HomeGraph entirely for topic file-lists,
+ * Default tools/list is the slim pair in `DEFAULT_MCP_TOOL_SHORT_NAMES`
+ * (explore / project). Opt into the full catalog with
+ * `HOMEGRAPH_MCP_TOOLS=all`. Skip HomeGraph entirely for topic file-lists,
  * concept compares, SDK catalogs, and literal greps.
  *
  * All tools support cross-project queries via the optional `projectPath` parameter.
@@ -921,11 +1182,11 @@ exports.tools = [
     {
         name: 'homegraph_explore',
         description: 'Optional graph evidence for a concrete unresolved cross-symbol mechanism in THIS repo. Required: `query`. ' +
+            'For module/route-profile **paths** and engineering overview use homegraph_project first (not this tool). ' +
             'Use ordinary bash/search/read for paths, symbols, literal strings and local changes; continue editing when that evidence suffices. ' +
             'Do not call for routine pre-edit orientation or merely because implementation is difficult. ' +
-            'For a missing usage, dependency/cycle or native-registration relation, use ' +
-            'homegraph_usages, homegraph_modules, or homegraph_native instead. ' +
-            'Returns call paths and compact line-numbered source. ArkTS symbol evidence uses complete declarations and bounded directed paths with intermediate source dependencies; explicit Gaps and stop reasons name omitted or unverified evidence. Qualify ambiguous symbols by owning type or file. State the missing relation with known anchors, requested action, scope and constraints; taskContext can carry the full task. ' +
+            'Located ArkTS code may include render scope, imported types, module configuration, indexed SDK signatures and control-state gaps. ' +
+            'Returns call paths and compact line-numbered source (Harmony route_map queries may lead with Registration sources; form/shortcuts queries may lead with Capability profiles; element/string.json literals may lead with Resource hits + optional bound .ets anchors; Seam notes may flag stubs). ArkTS symbol evidence uses complete declarations and bounded directed paths with intermediate source dependencies; explicit Gaps and stop reasons name omitted or unverified evidence. Qualify ambiguous symbols by owning type or file. State the missing relation with known anchors, requested action, scope and constraints; taskContext can carry the full task. ' +
             'Reuse unchanged complete ranges; refresh missing, edited or truncated evidence. ' +
             'No new evidence → change to a targeted source inspection, not a paraphrased explore. ' +
             'Partial/busy → at most one focused recovery for the named gap; budgets are ceilings, not required calls. ' +
@@ -937,7 +1198,7 @@ exports.tools = [
                     type: 'string',
                     description: 'Required. For pre-edit orientation or how/mechanism: pass the user task or domain keywords (page/module/feature words). ' +
                         'For named flows, include Type / Type.member / component names. For @kit mechanism/flow, include module/export tokens; ' +
-                        'use homegraph_usages for a narrow import/usage inventory, not SDK catalogs.',
+                        'not SDK feature catalogs.',
                 },
                 taskContext: {
                     type: 'string',
@@ -967,9 +1228,12 @@ exports.tools = [
     },
     {
         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.',
+        description: 'Shallow engineering map: modules + per-module files. On Harmony repos also prints skeleton pointers ' +
+            '(bundleName from app.json5, modules from build-profile.json5, per-module route_map/router_map/main_pages paths, oh-package name) ' +
+            'and a Module roster (local file: deps) plus bounded HarmonyOS resources path inventory (string.json / capability profiles form_config|shortcuts_config / rawfile / media dirs / on-disk modules not in the graph). ' +
+            'GIVES navigation only — NOT symbol bodies, call graphs, or JSON/file contents (use homegraph_explore for route→page / Resource hits / Capability profiles; Read to edit). ' +
+            'PRIMARY overview while the full index is still building; also useful after full index. ' +
+            'Optional `module` filters by name/path; `includeFiles` defaults true (resources section still prints when false).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1156,6 +1420,28 @@ function withRequiredProjectPath(defs) {
         };
     });
 }
+/**
+ * Default MCP tools/list surface (product slim). Handlers for other tools remain
+ * in-tree; restore the full catalog with `HOMEGRAPH_MCP_TOOLS=all` (or `*`), or
+ * name a comma list (e.g. `explore,node,search,arkui_migrate`).
+ */
+exports.DEFAULT_MCP_TOOL_SHORT_NAMES = ['explore', 'project'];
+/** Resolve the exposed-tool allowlist from env (default = product slim pair). */
+function resolveMcpToolAllowlist(raw = process.env.HOMEGRAPH_MCP_TOOLS) {
+    if (!raw || !raw.trim()) {
+        return new Set(exports.DEFAULT_MCP_TOOL_SHORT_NAMES);
+    }
+    const trimmed = raw.trim();
+    if (trimmed === '*' || /^all$/i.test(trimmed))
+        return 'all';
+    const set = new Set(trimmed.split(',').map((s) => s.trim().replace(/^homegraph_/, '')).filter(Boolean));
+    return set.size ? set : new Set(exports.DEFAULT_MCP_TOOL_SHORT_NAMES);
+}
+function filterToolsByAllowlist(defs, allow) {
+    if (allow === 'all')
+        return defs;
+    return defs.filter((t) => allow.has(t.name.replace(/^homegraph_/, '')));
+}
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
@@ -1163,12 +1449,7 @@ function withRequiredProjectPath(defs) {
  * note in a description only adds once `cg` is loaded; the schemas are static).
  */
 function getStaticTools() {
-    const raw = process.env.HOMEGRAPH_MCP_TOOLS ?? process.env.HOMEGRAPH_MCP_TOOLS;
-    if (!raw || !raw.trim()) {
-        return exports.tools;
-    }
-    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;
+    return filterToolsByAllowlist(exports.tools, resolveMcpToolAllowlist());
 }
 /** Prose that reads like an identifier but never names a symbol worth scanning. */
 const BARE_USAGE_STOPWORDS = new Set([
@@ -1326,6 +1607,10 @@ class ToolHandler {
     // The directory the server last searched for a default project. Surfaced in
     // the "not initialized" error so users can see why detection missed.
     defaultProjectHint = null;
+    // Spec 0043: when a tool `projectPath` would open a different index root than
+    // the session's default bound project, we soft-pin to the default and stash
+    // an English notice to prepend on the success reply (consumed once).
+    boundProjectPathPinNotice = null;
     // Per-start-path cache of the git worktree/index mismatch (issue #155). The
     // mismatch is a fixed property of (where the request came from → which
     // .homegraph/ it resolves to), so the up-to-two `git rev-parse` spawns run
@@ -1428,26 +1713,20 @@ class ToolHandler {
         return this.cg !== null;
     }
     /**
-     * Optional allowlist of exposed tools, parsed from the HOMEGRAPH_MCP_TOOLS
-     * env var (comma-separated short names, e.g. "explore,search,node").
-     * Unset/empty → every tool is exposed. Set → only the listed tools are
-     * exposed. Lets an operator (or an A/B harness) trim the tool surface
-     * without rebuilding the client config; the ablated tool is then truly
-     * absent from ListTools rather than merely denied on call.
+     * Optional allowlist of exposed tools, parsed from HOMEGRAPH_MCP_TOOLS.
+     * Unset/empty → product slim default (`explore`, `project`).
+     * `all` / `*` → full catalog. Comma list → only those short names.
      * Matching is on the short form, so "node" and "homegraph_node" both work.
      */
     toolAllowlist() {
-        const raw = process.env.HOMEGRAPH_MCP_TOOLS ?? process.env.HOMEGRAPH_MCP_TOOLS;
-        if (!raw || !raw.trim())
-            return null;
-        const short = (s) => s.trim().replace(/^homegraph_/, '');
-        const set = new Set(raw.split(',').map(short).filter(Boolean));
-        return set.size ? set : null;
+        return resolveMcpToolAllowlist();
     }
-    /** Whether a tool name passes the HOMEGRAPH_MCP_TOOLS allowlist (if any). */
+    /** Whether a tool name passes the HOMEGRAPH_MCP_TOOLS allowlist. */
     isToolAllowed(name) {
         const allow = this.toolAllowlist();
-        return !allow || allow.has(name.replace(/^homegraph_/, ''));
+        if (allow === 'all')
+            return true;
+        return allow.has(name.replace(/^homegraph_/, ''));
     }
     /**
      * Get tool definitions with dynamic descriptions based on project size.
@@ -1457,11 +1736,7 @@ class ToolHandler {
      */
     getTools() {
         const allow = this.toolAllowlist();
-        // No explicit allowlist → expose every defined tool. An allowlist trims
-        // the surface to only the listed short names.
-        let visible = allow
-            ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, '')))
-            : exports.tools;
+        let visible = filterToolsByAllowlist(exports.tools, allow);
         // No default project loaded → no-root-index case (#993): a gateway server
         // started outside any repo, or a monorepo root whose indexes live in
         // sub-projects. With nothing to fall back to, EVERY call needs an explicit
@@ -1476,29 +1751,13 @@ class ToolHandler {
             return withRequiredProjectPath(visible);
         try {
             const stats = this.cg.getStats();
-            // Tiny-repo tool gating: on projects under TINY_REPO_FILE_THRESHOLD
-            // files, only expose the core trio (search, node, explore) — one
-            // below even the 4-tool default: at this scale callers, too, reduces
-            // to one grep. (Historical note: the audit below ran when context and
-            // trace still existed; its "5 core tools" are today's trio.)
-            //
-            // n=2 audits ruled out cutting below 5 tools:
-            // - 3-tool gate (search + context + trace): cost regressed on
-            //   cobra/ky/sinatra. The agent fell back to raw Reads to cover
-            //   what homegraph_node + homegraph_explore would have answered.
-            // - 1-tool gate (search only): catastrophic regression — express
-            //   went from -43% WIN to +107% LOSS. With only search, the agent
-            //   can't navigate the call graph structurally and reads everything.
+            // Tiny-repo tool gating applies only when the host asked for the full
+            // catalog (`HOMEGRAPH_MCP_TOOLS=all`). The product default is already the
+            // slim pair; an explicit comma allowlist is left untouched.
             //
-            // 5 is the empirical lower bound. Tools beyond search/context/
-            // node/explore/trace pay overhead that the agent doesn't recoup
-            // on tiny-repo flow questions.
-            // ITER4: raise threshold 150 → 500 so single-file frameworks
-            // (sinatra at 159, slim_framework around 200) also get the
-            // 5-tool surface. The empirical 5-tool floor was set on <150
-            // probes; iter3 measurement showed sinatra is structurally the
-            // SAME problem as cobra (single-file WITHOUT-arm Read wins),
-            // so it deserves the same gating.
+            // Historical note: n=2 audits ruled out cutting below ~5 tools on the
+            // *full* catalog for tiny OSS repos (search+node+explore+…). That trim
+            // still matters when someone opts into `all` on a <500-file tree.
             const TINY_REPO_FILE_THRESHOLD = 500;
             const TINY_REPO_CORE_TOOLS = new Set([
                 'homegraph_explore',
@@ -1507,9 +1766,9 @@ class ToolHandler {
                 'homegraph_diff_impact',
                 'homegraph_project',
             ]);
-            // An explicit host selection overrides the default size-based surface.
-            // Otherwise small ArkTS repos silently lose requested specialized tools.
-            if (!allow && stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
+            const envRaw = (process.env.HOMEGRAPH_MCP_TOOLS ?? '').trim();
+            const askedForFullCatalog = allow === 'all' && (/^all$/i.test(envRaw) || envRaw === '*');
+            if (askedForFullCatalog && stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
                 visible = visible.filter(t => TINY_REPO_CORE_TOOLS.has(t.name));
             }
             return visible.map(tool => {
@@ -1580,6 +1839,11 @@ class ToolHandler {
      *
      * Walks up parent directories to find the nearest .homegraph/ folder,
      * similar to how git finds .git/ directories.
+     *
+     * Spec 0043: when a default project is already bound, a `projectPath` whose
+     * resolved index root differs from that bound root is soft-pinned back to
+     * the default (no DB switch) and a success-shaped English notice is stashed
+     * for the reply preamble.
      */
     getHomeGraph(projectPath) {
         const sourcesMode = (0, graph_sources_1.resolveGraphSources)();
@@ -1626,25 +1890,34 @@ class ToolHandler {
         // (#926). The DB connection itself is still cached (by resolved root,
         // below), so re-resolving costs only the stat walk, never a reopen.
         const resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(projectPath);
+        // Spec 0043: with a bound default root, never switch the graph to a
+        // different index (sibling / parent / wrong absolute path). Soft-pin and
+        // stash a notice; security refusals above still win.
+        if (this.cg) {
+            const boundRoot = (0, path_1.resolve)(this.cg.getProjectRoot());
+            const resolvedAbs = resolvedRoot ? (0, path_1.resolve)(resolvedRoot) : null;
+            if (resolvedAbs === null || resolvedAbs !== boundRoot) {
+                this.boundProjectPathPinNotice = (0, index_availability_1.formatBoundProjectPathPinNotice)({
+                    boundRoot,
+                    requestedPath: projectPath,
+                    resolvedRoot: resolvedAbs,
+                });
+                return this.freshen(this.cg);
+            }
+            // Same index root (incl. nested path under the bound project) — reuse the
+            // default instance so we never open a second connection to the same DB
+            // (#238).
+            return this.freshen(this.cg);
+        }
         if (!resolvedRoot) {
             throw new NotIndexedError(`The project at ${projectPath} isn't indexed with homegraph (no .homegraph/ directory found ` +
                 'walking up from it), so homegraph cannot query it. Use your built-in tools (Read/Grep/Glob) ' +
                 "for that codebase instead, and don't call homegraph for it again this session. " +
                 "Indexing is the user's decision — they can run 'homegraph init' in that project to enable it.");
         }
-        // If the path resolves to the default project, reuse the already-open
-        // default instance rather than opening a SECOND connection to the same DB.
-        // A duplicate connection serializes reads against the watcher's auto-sync
-        // writes; when WAL isn't in effect (e.g. a filesystem without shared-memory
-        // support) that surfaces as intermittent
-        // "database is locked" on concurrent tool calls. See issue #238. The
-        // default instance is owned/closed by the server, so it's never cached.
-        if (this.cg && this.cg.getProjectRoot() === resolvedRoot) {
-            return this.freshen(this.cg);
-        }
-        // Cache the open DB connection by RESOLVED ROOT only — never by the input
-        // path. One key per instance means closeAll() closes each exactly once, and
-        // a changed resolution maps to a different entry instead of a stale hit.
+        // No default project — cross-project open (cached by resolved root).
+        // One key per instance means closeAll() closes each exactly once, and a
+        // changed resolution maps to a different entry instead of a stale hit.
         const cached = this.projectCache.get(resolvedRoot);
         if (cached)
             return this.freshen(cached);
@@ -1889,6 +2162,15 @@ class ToolHandler {
             catch {
                 reason = null;
             }
+            try {
+                (0, runtime_log_1.logLifecycle)('watcher.degraded', {
+                    projectRoot: cg.getProjectRoot(),
+                    reason: reason ?? undefined,
+                });
+            }
+            catch {
+                /* ignore */
+            }
             const composed = `${formatDegradedBanner(reason)}\n\n${head.text}`;
             return { ...result, content: [{ type: 'text', text: composed }, ...tail] };
         }
@@ -1898,8 +2180,9 @@ class ToolHandler {
         return result;
     }
     /**
-     * Append a one-line product index status footer (Spec 0035).
-     * Guidance-only replies that already start with `HomeGraph status=` are left alone.
+     * Decorate successful tool text (Spec 0035 status footer + Spec 0038 project-root hint
+     * + Spec 0043 bound projectPath pin notice).
+     * Prepends absolute project root + join guidance when known; appends status when missing.
      */
     withProductStatusFooter(result, projectPath) {
         if (result.isError)
@@ -1907,8 +2190,6 @@ class ToolHandler {
         const [first, ...rest] = result.content;
         if (!first || first.type !== 'text')
             return result;
-        if ((0, index_availability_1.textAlreadyHasProductStatus)(first.text))
-            return result;
         let cg;
         try {
             cg = this.getHomeGraph(projectPath);
@@ -1926,26 +2207,52 @@ class ToolHandler {
                 /* leave cg */
             }
         }
-        let state;
-        try {
-            state = (0, index_availability_1.resolveProductIndexState)(cg);
+        let text = first.text;
+        // Spec 0038: absolute project root + how to join repo-relative paths (idempotent).
+        if (!(0, index_availability_1.textAlreadyHasProjectRootHint)(text)) {
+            try {
+                const absRoot = (0, path_1.resolve)(cg.getProjectRoot());
+                if (absRoot) {
+                    text = `${(0, index_availability_1.formatProjectRootPathHint)(absRoot)}\n\n${text}`;
+                }
+            }
+            catch {
+                /* no root — skip hint */
+            }
         }
-        catch {
-            return result;
+        // Spec 0043: bound-root soft-pin notice at the very top (consume once).
+        const pinNotice = this.boundProjectPathPinNotice;
+        this.boundProjectPathPinNotice = null;
+        if (pinNotice && !(0, index_availability_1.textAlreadyHasBoundProjectPathPinNotice)(text)) {
+            text = `${pinNotice}\n\n${text}`;
         }
-        let pendingPaths;
-        if (state === 'dirty') {
+        // Spec 0035: one-line product index status footer (skip if already present).
+        if (!(0, index_availability_1.textAlreadyHasProductStatus)(text)) {
+            let state;
             try {
-                pendingPaths = (cg.getPendingFiles?.() ?? []).map((p) => p.path);
+                state = (0, index_availability_1.resolveProductIndexState)(cg);
             }
             catch {
-                pendingPaths = [];
+                return {
+                    ...result,
+                    content: [{ type: 'text', text }, ...rest],
+                };
             }
+            let pendingPaths;
+            if (state === 'dirty') {
+                try {
+                    pendingPaths = (cg.getPendingFiles?.() ?? []).map((p) => p.path);
+                }
+                catch {
+                    pendingPaths = [];
+                }
+            }
+            const line = (0, index_availability_1.formatProductStatusLine)(state, { pendingPaths });
+            text = `${text}\n\n${line}`;
         }
-        const line = (0, index_availability_1.formatProductStatusLine)(state, { pendingPaths });
         return {
             ...result,
-            content: [{ type: 'text', text: `${first.text}\n\n${line}` }, ...rest],
+            content: [{ type: 'text', text }, ...rest],
         };
     }
     /**
@@ -1956,10 +2263,47 @@ class ToolHandler {
      */
     async execute(toolName, args, sessionState) {
         const requestStartedAt = Date.now();
+        const result = await this.executeCore(toolName, args, sessionState, requestStartedAt);
+        this.traceToolCall(toolName, args, result, requestStartedAt);
+        return result;
+    }
+    /** Spec 0046: HOMEGRAPH_DEBUG tool summary → stderr + daemon.log. */
+    traceToolCall(toolName, args, result, requestStartedAt) {
+        try {
+            let projectRoot;
+            try {
+                projectRoot = this.getHomeGraph(args.projectPath).getProjectRoot();
+            }
+            catch {
+                projectRoot = typeof args.projectPath === 'string' ? args.projectPath : undefined;
+            }
+            const q = typeof args.query === 'string'
+                ? args.query
+                : typeof args.symbol === 'string'
+                    ? args.symbol
+                    : undefined;
+            const evidenceStatus = result._meta?.homegraphEvidence?.status
+                ?? result[explore_session_state_1.EXPLORE_EMISSION_KEY]?.evidenceStatus;
+            (0, runtime_log_1.logToolDebug)(toolName, {
+                projectRoot,
+                durationMs: Date.now() - requestStartedAt,
+                isError: !!result.isError,
+                evidenceStatus,
+                query: q,
+            });
+        }
+        catch {
+            /* logging never fails the tool */
+        }
+    }
+    async executeCore(toolName, args, sessionState, requestStartedAt) {
         args = { ...args };
         for (const key of [QUERY_PLAN_ARG, QUERY_DEADLINE_ARG, QUERY_STARTED_ARG, QUERY_INDEX_STATE_ARG, QUERY_FAST_ATTEMPTED_ARG, '_hgEvidenceMaxChars'])
             delete args[key];
         try {
+            // Spec 0043: drop any leftover pin notice from a prior call that exited
+            // before withProductStatusFooter (gate / defer / refuse).
+            this.boundProjectPathPinNotice = null;
             // Block the first tool call on the engine's post-open reconcile so we
             // never serve rows for files deleted/edited while no MCP server was
             // running. The wait is time-boxed (#905): a huge-repo reconcile takes
@@ -2047,7 +2391,8 @@ class ToolHandler {
             // would re-serve the first call's full source and defeat CG-18 dedup.
             const skipCacheForSession = toolName === 'homegraph_explore' && !!sessionState;
             const requestPlan = readQueryPlan(args);
-            const cacheEnabled = !skipCacheForSession && requestPlan?.source !== 'llm'
+            const cacheEnabled = !skipCacheForSession && !(toolName === 'homegraph_explore' && process.env.HOMEGRAPH_ARKTS_EVIDENCE_LOG === '1') && requestPlan?.source !== 'llm'
+                && !(requestPlan?.requestContract && ((0, request_contract_1.accuracyTargetsEnabled)() || (0, request_contract_1.accuracyCoverageEnabled)()))
                 && !requestPlan?.telemetry.fallbackReason && (0, query_cache_1.isMcpQueryCacheEnabled)() && (0, query_cache_1.isCacheableMcpTool)(toolName);
             let cacheKey;
             let cacheQueries;
@@ -2069,7 +2414,7 @@ class ToolHandler {
                     const cached = cacheIndex.getEntry(cacheQueries, cacheKey);
                     const packMeta = cached?._meta?.homegraphEvidencePacks;
                     const cachedFiles = cached?._meta?.homegraphEvidence?.files;
-                    if (cached && (!packMeta || (packMeta.status === 'complete'
+                    if (cached && (!packMeta || (packMeta.status === 'complete' && !packMeta.implementationContext?.length
                         && this.areEvidenceFilesCurrent(cachedFiles ?? [], cacheCg.getProjectRoot())))) {
                         const diagnosed = this.withQueryPlanDiagnostics(cached, args, true);
                         const withWorktree = this.withWorktreeNotice(diagnosed, projectPath);
@@ -2222,15 +2567,19 @@ class ToolHandler {
         try {
             const cg = this.getHomeGraph(args.projectPath);
             const root = cg.getProjectRoot();
-            const decision = (0, explore_repeat_guard_1.decideDepthToolFuse)(sessionState.forProject(root), sessionState.depthToolCount(root), toolName);
-            if (!decision.refuse)
-                return null;
-            const hint = typeof args.symbol === 'string'
+            const prior = sessionState.forProject(root);
+            const symbolHint = typeof args.symbol === 'string'
                 ? args.symbol
                 : typeof args.file === 'string'
                     ? args.file
                     : undefined;
-            return this.textResult((0, explore_repeat_guard_1.formatDepthToolRefuse)(decision, toolName, hint));
+            // Spec 0044 §10.2: symbols already on the locate list bypass the Partial depth cap.
+            if ((0, locate_contract_1.shouldExemptDepthFuseForLocatedSymbol)(prior, symbolHint))
+                return null;
+            const decision = (0, explore_repeat_guard_1.decideDepthToolFuse)(prior, sessionState.depthToolCount(root), toolName);
+            if (!decision.refuse)
+                return null;
+            return this.textResult((0, explore_repeat_guard_1.formatDepthToolRefuse)(decision, toolName, symbolHint));
         }
         catch {
             return null;
@@ -2302,6 +2651,10 @@ class ToolHandler {
             const last = prior?.calls[prior.calls.length - 1];
             if (!last || (0, explore_session_state_1.inferExploreEvidenceStatus)(last) === 'complete')
                 return;
+            const symbolHint = typeof args.symbol === 'string' ? args.symbol : undefined;
+            // Spec 0044 §10.2: located-symbol drills do not consume the Partial depth budget.
+            if ((0, locate_contract_1.shouldExemptDepthFuseForLocatedSymbol)(prior, symbolHint))
+                return;
             sessionState.recordDepthTool(root);
         }
         catch { /* bookkeeping only */ }
@@ -3150,6 +3503,13 @@ class ToolHandler {
                 registeredAt,
             };
         }
+        if (m?.synthesizedBy === 'arkts-route-map') {
+            return {
+                label: `Harmony route registration (config → page/builder)`,
+                compact: `route-map registration${at}`,
+                registeredAt,
+            };
+        }
         if (m?.synthesizedBy === 'goframe-route') {
             const route = m.route ? `\`${String(m.route)}\`` : 'a route';
             return {
@@ -5375,7 +5735,7 @@ class ToolHandler {
                     ...prior, version: plan.version, source: plan.source, intent: plan.intent, route: plan.route,
                     confidence: plan.confidence,
                     plannerSeeds: { anchors: plan.anchors, searchTerms: plan.searchTerms, literalTexts: plan.literalTexts,
-                        sourceScope: plan.sourceScope, relation: plan.relation },
+                        sourceScope: plan.sourceScope, relation: plan.relation, requestContract: plan.requestContract },
                     hasTaskContext: !!plan.taskContext,
                     matchedFeatures: Object.entries(plan.features).filter(([, matched]) => matched).map(([name]) => name).slice(0, 12),
                     planningMs: plan.telemetry.durationMs, durationMs: Math.max(plan.telemetry.durationMs, Date.now() - started),
@@ -5400,6 +5760,10 @@ class ToolHandler {
         if (plan.route === 'usages' || plan.route === 'modules' || plan.route === 'native') {
             return this.runSpecializedExploreRoute(plan.route, cg, query, root, plan);
         }
+        // Constrained ArkTS retrieval needs the full, verified-source renderer.
+        if (plan.requestContract && ((0, request_contract_1.accuracyTargetsEnabled)() || (0, request_contract_1.accuracyCoverageEnabled)())
+            && plan.sourceScope !== 'sdk' && cg.getFiles().some(f => /\.ets$/i.test(f.path)))
+            return null;
         // These legacy paths re-extract seeds from text and cannot consume bound
         // node identity / step hints. Model general/flow plans use full explore;
         // rule/default and specialized routes retain their existing fast behavior.
@@ -6260,20 +6624,58 @@ class ToolHandler {
         if (!nodes.some(n => /\.ets$/i.test(n.filePath) && !n.filePath.startsWith('ohos-sdk:')))
             return null;
         const budget = getExploreOutputBudget(cg.getStats().fileCount);
-        const queryPaths = process.env.HOMEGRAPH_ARKTS_QUERY_PATHS !== '0';
+        const constrained = !!plan?.requestContract && ((0, request_contract_1.accuracyTargetsEnabled)() || (0, request_contract_1.accuracyCoverageEnabled)());
+        const queryPaths = (!constrained || plan?.intent === 'flow' || !!plan?.bindings?.length) && process.env.HOMEGRAPH_ARKTS_QUERY_PATHS !== '0';
         if (queryPaths)
             nodes = (0, evidence_paths_1.completeEvidencePathCandidates)(query, nodes, (name, limit) => cg.getQueryBuilder().getNodesByQualifiedNameExact(name, limit), plan);
+        if ((0, implementation_context_1.implementationContextEnabled)()) {
+            const boundIds = new Set(focusIds);
+            nodes = nodes.map(n => {
+                if (n.kind !== 'struct')
+                    return n;
+                const component = cg.getNodesInFile(n.filePath).find(c => c.kind === 'component' && c.name === n.name && c.startLine === n.startLine);
+                if (component && boundIds.has(n.id))
+                    boundIds.add(component.id);
+                return component ?? n;
+            });
+            focusIds = boundIds;
+        }
         const pathSearch = !queryPaths ? undefined : (0, evidence_paths_1.searchEvidencePaths)({
             getNode: id => cg.getNode(id),
-            getEdges: (id, direction, kinds, limit, preferred) => cg.getQueryBuilder().getEvidenceEdges(id, direction, kinds, limit, preferred),
+            getEdges: (id, direction, kinds, limit, preferred) => {
+                const read = (nodeId) => cg.getQueryBuilder().getEvidenceEdges(nodeId, direction, kinds, limit, preferred);
+                if (!(0, implementation_context_1.implementationContextEnabled)())
+                    return read(id);
+                const owner = cg.getNode(id);
+                const aliases = owner && ['struct', 'component'].includes(owner.kind)
+                    ? cg.getNodesInFile(owner.filePath).filter(n => ['struct', 'component'].includes(n.kind) && n.name === owner.name
+                        && n.startLine === owner.startLine && n.endLine === owner.endLine).slice(0, 2) : [];
+                const canonical = (nodeId) => {
+                    const n = cg.getNode(nodeId);
+                    if (!n || n.kind !== 'struct')
+                        return nodeId;
+                    return cg.getNodesInFile(n.filePath).find(c => c.kind === 'component' && c.name === n.name
+                        && c.startLine === n.startLine && c.endLine === n.endLine)?.id ?? nodeId;
+                };
+                // ArkAnalyzer stores struct/component roles for the same declaration. Project
+                // their ownership edges to one identity; this is not a new runtime call.
+                const edges = (aliases.length ? aliases.flatMap(n => read(n.id)) : read(id)).map(e => ({ ...e,
+                    source: canonical(e.source), target: canonical(e.target) })).filter(e => e.source !== e.target);
+                return [...new Map(edges.map(e => [JSON.stringify([e.source, e.target, e.kind, e.metadata]), e])).values()].slice(0, limit);
+            },
         }, (0, evidence_paths_1.resolveEvidencePathGoal)(query, nodes, focusIds, plan));
         const result = (0, arkts_evidence_packs_1.buildArktsEvidencePacks)(cg, { projectRoot, query, nodes, focusIds,
-            maxChars: Math.min(budget.maxOutputChars, maxChars ?? budget.maxOutputChars), maxFiles, pathSearch });
+            maxChars: Math.min(budget.maxOutputChars, maxChars ?? budget.maxOutputChars), maxFiles, pathSearch, requestContract: plan?.requestContract,
+            sdkModule: cg.getGraphSources() === 'project' || cg.getGraphSources() === 'none' ? undefined : module => {
+                const nodes = cg.getQueryBuilder().getOhosApiModuleNodes(module);
+                return nodes.length ? { nodes, version: cg.getOhosApiBinding()?.version ?? 'unknown' } : undefined;
+            } });
         if (!result)
             return null;
+        const audit = (0, evidence_audit_1.recordEvidencePack)(projectRoot, { query, requestContract: plan?.requestContract }, result);
         // The pack renderer already supplies neutral guidance and exact source bytes.
         return { content: [{ type: 'text', text: result.text }], [explore_session_state_1.EXPLORE_EMISSION_KEY]: result.emission,
-            _meta: { homegraphEvidencePacks: result.metadata } };
+            _meta: { homegraphEvidencePacks: result.metadata, ...(audit !== 'disabled' ? { homegraphEvidenceAudit: audit } : {}) } };
     }
     /** Render a compact symbol-bounded slice on the legacy mechanism path. */
     renderLightMechanismSource(projectRoot, filePath, nodes, maxChars) {
@@ -6318,7 +6720,13 @@ class ToolHandler {
         const isTestPath = (p) => /(^|\/)(tests?|spec)\//i.test(p) || /\.(test|spec)\./i.test(p);
         const fileNodes = new Map();
         const seedIds = new Set();
-        const domainPathTokens = (0, query_utils_1.mechanismDomainPathTokens)(query);
+        const domainPathTokens = (0, locate_contract_1.shouldSuppressSynonymExpansion)({
+            hasExactAnchorHit: (0, query_utils_1.extractInRepoLocateAnchors)(query).length > 0
+                || (0, query_utils_1.extractTypeNamesFromQuery)(query).length > 0,
+            hasLiteralWitness: false,
+        })
+            ? []
+            : (0, query_utils_1.mechanismDomainPathTokens)(query);
         const addNode = (n) => {
             if ((0, arkts_1.isOhosApiFilePath)(n.filePath))
                 return;
@@ -6777,9 +7185,8 @@ class ToolHandler {
      * Static AA class/interface nodes that look like domain Managers/Services.
      */
     collectDomainRoleSymbols(cg, query, domainTokens) {
-        const tokens = domainTokens.length > 0
-            ? domainTokens
-            : (0, query_utils_1.mechanismDomainPathTokens)(query);
+        // Spec 0044 §9: callers may pass [] to suppress CJK→ASCII synonym expansion.
+        const tokens = domainTokens;
         if (tokens.length === 0)
             return [];
         const byId = new Map();
@@ -7226,7 +7633,9 @@ class ToolHandler {
                 }
                 if (!callersOnly) {
                     for (const { node: c } of cg.getCallees(id).slice(0, 10)) {
-                        // Skip log*/hilog helpers — Export→logInfo homonyms ballooned seeds.
+                        if ((0, locate_contract_1.shouldDemoteLogToastSpine)(c.name, query)) {
+                            continue;
+                        }
                         if (/^log(?:Info|Error|Warn|Debug|Fatal)?$/i.test(c.name) || /^hilog$/i.test(c.name)) {
                             continue;
                         }
@@ -7415,11 +7824,15 @@ class ToolHandler {
                     continue;
                 trail.push(`- \`${seedNode.name}\` (${seedNode.kind}) — ${seedNode.filePath}:${seedNode.startLine}`);
                 for (const c of callers) {
+                    if ((0, query_utils_1.isMcpNoiseNode)(c.node))
+                        continue;
                     const loc = c.node.startLine ? `:${c.node.startLine}` : '';
                     trail.push(`  ← used by \`${c.node.name}\` (${c.node.kind}) — ${c.node.filePath}${loc}`);
                     trailBullets++;
                 }
                 for (const c of callees) {
+                    if ((0, query_utils_1.isMcpNoiseNode)(c.node))
+                        continue;
                     const loc = c.node.startLine ? `:${c.node.startLine}` : '';
                     trail.push(`  → calls \`${c.node.name}\` (${c.node.kind}) — ${c.node.filePath}${loc}`);
                     trailBullets++;
@@ -9638,6 +10051,8 @@ class ToolHandler {
         const explicitMaxFiles = typeof args.maxFiles === 'number' && !Number.isNaN(args.maxFiles);
         let maxFiles = (0, utils_1.clamp)(args.maxFiles || budget.defaultMaxFiles, 1, 20);
         const queryFileBasenames = (0, query_utils_1.extractFileBasenamesFromQuery)(query);
+        const locateAnchors = (0, query_utils_1.extractInRepoLocateAnchors)(query);
+        const exploreSourceScope = (0, query_utils_1.resolveExploreSourceScope)(query, plan?.sourceScope);
         const interpretationQuery = feature('queryAsInterpretationSurvey', query_utils_1.queryAsInterpretationSurvey);
         const testOnlyInterpretation = feature('queryAsTestOnlyInterpretation', query_utils_1.queryAsTestOnlyInterpretation);
         const crossModuleFlow = feature('queryAsCrossModuleFlowSurvey', query_utils_1.queryAsCrossModuleFlowSurvey) || plan?.intent === 'flow';
@@ -9649,19 +10064,29 @@ class ToolHandler {
             ? `${queryFileBasenames[0]} ${query}`
             : queryFileBasenames.length === 1
                 ? `${queryFileBasenames[0]} ${query}`
-                : query;
+                : locateAnchors.length === 1
+                    ? `${locateAnchors[0]} ${query}`
+                    : query;
+        const wantHints = !!(plan && (plan.source === 'llm' || plan.literalTexts?.length || plan.anchors?.length || plan.requestContract))
+            || exploreSourceScope !== 'all';
         const subgraph = await cg.findRelevantContext(contextQuery, {
             ...contextOpts,
-            ...(plan && (plan.source === 'llm' || plan.literalTexts?.length) ? { retrievalHints: {
-                    symbols: plan.anchors.filter((anchor) => !(plan.bindings ?? []).some((node) => anchor === node.name || anchor === node.qualifiedName)),
-                    searchTerms: plan.searchTerms, literalTexts: plan.literalTexts, sourceScope: plan.sourceScope, nodeIds: (plan.bindings ?? []).map((node) => node.id),
+            ...(wantHints ? { retrievalHints: {
+                    symbols: [
+                        ...(plan?.anchors ?? []).filter((anchor) => !(plan?.bindings ?? []).some((node) => anchor === node.name || anchor === node.qualifiedName)),
+                        ...locateAnchors,
+                    ].slice(0, 16),
+                    searchTerms: plan?.searchTerms ?? [], literalTexts: [...new Set([...(plan?.literalTexts ?? []),
+                            ...((0, request_contract_1.accuracyTargetsEnabled)() && !plan?.bindings?.length ? (0, request_contract_1.contractLiteralTexts)(plan?.requestContract) : [])])].slice(0, 8),
+                    sourceScope: exploreSourceScope,
+                    nodeIds: (plan?.bindings ?? []).map((node) => node.id),
                 } } : {}),
         });
-        // Path-first: always seed nodes from an explicit `Foo.ets` basename so a
-        // CJK-only ask + path (or a shared prop like showSearchIcon) cannot leave
-        // the named file out of the subgraph / digests.
-        if (queryFileBasenames.length > 0 && plan?.sourceScope !== 'sdk') {
-            for (const base of queryFileBasenames.slice(0, 3)) {
+        // Path-first + Spec 0042 identifier seeding: Foo.ets and PascalCase ≥8 exact hits
+        // become roots so taskContext-polluted FTS cannot drop the named in-repo file.
+        if (exploreSourceScope !== 'sdk') {
+            const seedNames = [...new Set([...queryFileBasenames, ...locateAnchors])].slice(0, 6);
+            for (const base of seedNames) {
                 let hits = [];
                 try {
                     hits = cg.searchNodes(base, { limit: 50 });
@@ -9670,7 +10095,15 @@ class ToolHandler {
                     continue;
                 }
                 for (const r of hits) {
-                    if (!(0, query_utils_1.fileMatchesQueryBasename)(r.node.filePath, [base]))
+                    if ((0, query_utils_1.isMcpNoiseNode)(r.node))
+                        continue;
+                    const fp = r.node.filePath.replace(/\\/g, '/');
+                    const stem = fp.split('/').pop()?.replace(/\.[^.]+$/, '') ?? '';
+                    const exactFile = stem.toLowerCase() === base.toLowerCase()
+                        || (0, query_utils_1.fileMatchesQueryBasename)(r.node.filePath, [base]);
+                    const exactSymbol = r.node.name === base
+                        || (r.node.qualifiedName?.split(/::|\./).pop() === base);
+                    if (!exactFile && !exactSymbol)
                         continue;
                     if (!subgraph.nodes.has(r.node.id)) {
                         subgraph.nodes.set(r.node.id, r.node);
@@ -9679,12 +10112,48 @@ class ToolHandler {
                 }
             }
         }
+        if (plan?.requestContract && ((0, request_contract_1.accuracyTargetsEnabled)() || (0, request_contract_1.accuracyCoverageEnabled)()) && plan.sourceScope !== 'sdk'
+            // Resource values need the existing resource + reference renderer; a bare
+            // declaration would silently drop the value-to-key witness.
+            && !subgraph.literalEvidence?.hits.some(hit => hit.kind === 'resource_reference')) {
+            // One existing retrieval pass; raw literal hits affect candidate order only.
+            // Actual target evidence is checked against hash-verified source in the packer.
+            const hits = subgraph.literalEvidence?.hits ?? [];
+            const fileHits = new Map();
+            for (const hit of hits) {
+                const labels = fileHits.get(hit.filePath) ?? new Set();
+                labels.add(hit.literal);
+                fileHits.set(hit.filePath, labels);
+            }
+            const candidates = [...subgraph.nodes.values()];
+            if ((0, request_contract_1.accuracyTargetsEnabled)())
+                candidates.sort((a, b) => (fileHits.get(b.filePath)?.size ?? 0) - (fileHits.get(a.filePath)?.size ?? 0));
+            const packed = this.tryArktsEvidenceExplore(cg, query, projectRoot, candidates, new Set(plan.bindings?.length ? plan.bindings.map(b => b.id) : subgraph.roots), args._hgEvidenceMaxChars, maxFiles, plan);
+            if (packed)
+                return packed;
+        }
         const literalSource = this.renderLiteralSource(cg, subgraph);
         if (subgraph.nodes.size === 0) {
-            const text = literalSource.text || `No relevant code found for "${query}"`;
-            return this.exploreResult(text, { projectRoot, query, files: literalSource.files,
-                sourceBytes: literalSource.files.reduce((sum, file) => sum + file.bytes, 0), responseBytes: text.length,
-                locatedNodes: literalSource.nodes, partial: true, evidenceStatus: literalSource.text ? 'partial' : 'empty' });
+            // Spec 0044 §9: empty exact evidence → Miss (paths only), not a source dump.
+            let fuzzyPaths = [];
+            try {
+                fuzzyPaths = [...new Set(cg.searchNodes(query.slice(0, 64), { limit: 12 })
+                        .map((r) => r.node.filePath.replace(/\\/g, '/'))
+                        .filter((p) => p && !(0, arkts_1.isOhosApiFilePath)(p)))].slice(0, 8);
+            }
+            catch { /* ignore */ }
+            const text = literalSource.text
+                || (0, locate_contract_1.formatMissBanner)(fuzzyPaths);
+            return this.exploreResult(text, {
+                projectRoot,
+                query,
+                files: literalSource.files,
+                sourceBytes: literalSource.files.reduce((sum, file) => sum + file.bytes, 0),
+                responseBytes: text.length,
+                locatedNodes: literalSource.nodes,
+                partial: true,
+                evidenceStatus: literalSource.text ? 'partial' : 'empty',
+            });
         }
         // Seed import nodes for @kit.* / *Kit names (and named symbols like taskpool).
         const importTerms = (0, query_utils_1.extractImportSearchTerms)(query);
@@ -9852,7 +10321,7 @@ class ToolHandler {
                 const raw = isQual ? this.findAllSymbols(cg, t).nodes : cg.getNodesByName(t);
                 let cands = raw
                     .filter((n) => SEED_KINDS.has(n.kind) && !isTestPath(n.filePath)
-                    && !(plan?.sourceScope === 'local' && (0, arkts_1.isOhosApiFilePath)(n.filePath)))
+                    && !(exploreSourceScope === 'local' && (0, arkts_1.isOhosApiFilePath)(n.filePath)))
                     .sort((a, b) => {
                     // Prefer callables over types when both share a name, then body size.
                     const ac = CALLABLE.has(a.kind) ? 1 : 0;
@@ -10213,10 +10682,12 @@ class ToolHandler {
         // dropped, so the budget never fills with incidental files. Guarded so it
         // never prunes below 2.
         if (maxGraph > 0) {
+            const litKeep = new Set((subgraph.literalEvidence?.hits ?? []).map((h) => h.filePath).filter(Boolean));
             const gated = relevantFiles.filter(([fp]) => (fileGraphScore.get(fp) ?? 0) >= maxGraph * 0.06
                 || centralFiles.has(fp)
                 || entryFiles.has(fp)
                 || changeSurfaceFiles.has(fp)
+                || litKeep.has(fp)
                 || (fileTermHits.get(fp) ?? 0) >= 2);
             if (gated.length >= 2)
                 relevantFiles = gated;
@@ -10241,6 +10712,22 @@ class ToolHandler {
         // tier so it isn't buried under files that merely share surface words (#1064).
         for (const fp of changeSurfaceFiles)
             namedSeedFiles.add(fp);
+        // Spec 0044 §7: literal witness files must stay in the pack and rank with named seeds.
+        {
+            const litPaths = [...new Set((subgraph.literalEvidence?.hits ?? []).map((h) => h.filePath).filter(Boolean))];
+            for (const fp of litPaths) {
+                entryFiles.add(fp);
+                namedSeedFiles.add(fp);
+                if (relevantFiles.some(([f]) => f === fp))
+                    continue;
+                let group = fileGroups.get(fp);
+                if (!group) {
+                    group = { nodes: [], score: 1000 };
+                    fileGroups.set(fp, group);
+                }
+                relevantFiles.push([fp, group]);
+            }
+        }
         // Multi-term corroboration tier: a file that is BOTH (a) an entry/central file
         // (a search root, named seed, or graph-central hub — i.e. structurally part of
         // the answer) AND (b) matched by ≥2 DISTINCT query terms must not be buried by
@@ -10264,7 +10751,7 @@ class ToolHandler {
         const sortedFiles = relevantFiles.sort((a, b) => {
             const aPath = a[0].toLowerCase();
             const bPath = b[0].toLowerCase();
-            if (plan?.sourceScope === 'local') {
+            if (exploreSourceScope === 'local') {
                 const sdkOrder = Number((0, arkts_1.isOhosApiFilePath)(a[0])) - Number((0, arkts_1.isOhosApiFilePath)(b[0]));
                 if (sdkOrder)
                     return sdkOrder;
@@ -10273,6 +10760,17 @@ class ToolHandler {
                 - Number((subgraph.literalEvidence?.hits ?? []).some((hit) => hit.filePath === a[0]));
             if (literalOrder)
                 return literalOrder;
+            // Spec 0044 §7: demote Logger/hilog/Toast-only files when query did not name them.
+            const logToastDemote = (fp) => {
+                const group = fileGroups.get(fp);
+                if (!group?.nodes.length)
+                    return 0;
+                const allNoise = group.nodes.every((n) => (0, locate_contract_1.shouldDemoteLogToastSpine)(n.name, query));
+                return allNoise ? 1 : 0;
+            };
+            const logOrder = logToastDemote(a[0]) - logToastDemote(b[0]);
+            if (logOrder)
+                return logOrder;
             // Query-named file (LocationController.ets in the question) before partial
             // substring matches (control.ets matching "Controller" inside LocationController).
             const aExactBase = (0, query_utils_1.fileMatchesQueryBasename)(a[0], queryFileBasenames) ? 1 : 0;
@@ -11345,7 +11843,15 @@ class ToolHandler {
             const headerSuffix = omittedCount > 0
                 ? `${headerSymbols.join(', ')}, +${omittedCount} more`
                 : headerSymbols.join(', ');
-            const fileHeader = fileSectionHeader(filePath, headerSuffix);
+            let fileHeader = fileSectionHeader(filePath, headerSuffix);
+            // Spec 0044 §10.1: warn when basename ≠ primary declaration.
+            {
+                const primary = group?.nodes.find((n) => ['class', 'struct', 'component', 'interface', 'enum'].includes(n.kind)
+                    && !n.name.startsWith('%')) ?? group?.nodes.find((n) => ['function', 'method'].includes(n.kind) && !n.name.startsWith('%'));
+                const mismatch = (0, locate_contract_1.formatFilenameDeclarationMismatch)(filePath, primary?.name);
+                if (mismatch)
+                    fileHeader = `${fileHeader}\n${mismatch}`;
+            }
             // The total cap bounds INCIDENTAL files only. A file that DEFINES a symbol
             // the agent named (or that's on the flow spine) renders even when the
             // nominal total is used up — it's the answer, and the set is bounded by
@@ -11595,7 +12101,10 @@ class ToolHandler {
         const nodes = [];
         const seen = new Set();
         let chars = 0;
-        for (const hit of subgraph.literalEvidence?.hits ?? []) {
+        // Preserve value-to-key provenance when a plain label in the same file
+        // would otherwise consume its single source-witness slot first.
+        const literalHits = [...(subgraph.literalEvidence?.hits ?? [])].sort((a, b) => Number(!!b.resource) - Number(!!a.resource));
+        for (const hit of literalHits) {
             if (files.length >= 2 || seen.has(hit.filePath))
                 continue;
             const absolute = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), hit.filePath);
@@ -11639,6 +12148,106 @@ class ToolHandler {
         }
         return { text: sections.join('\n\n'), files, nodes };
     }
+    /**
+     * Spec 0039: when the query names Harmony route profiles, lead with a short
+     * Registration sources table so agents see JSON was indexed (avoid re-Read).
+     */
+    prependHarmonyRegistrationSources(result, projectRoot, query) {
+        if (!/route_map|router_map|main_pages/i.test(query))
+            return result;
+        const [first, ...rest] = result.content;
+        if (!first || first.type !== 'text')
+            return result;
+        if (/^\*\*Registration sources\*\*/m.test(first.text))
+            return result;
+        let cg;
+        try {
+            cg = this.getHomeGraph(projectRoot);
+        }
+        catch {
+            return result;
+        }
+        const section = formatHarmonyRegistrationSources(cg);
+        if (!section)
+            return result;
+        return {
+            ...result,
+            content: [{ type: 'text', text: `${section}\n\n${first.text}` }, ...rest],
+        };
+    }
+    /** Spec 0041: lead with Resource hits when string.json is named or matched. */
+    prependHarmonyResourceHits(result, projectRoot, query) {
+        const [first, ...rest] = result.content;
+        if (!first || first.type !== 'text')
+            return result;
+        if (/^\*\*Resource hits\*\*/m.test(first.text) || /\n\*\*Resource hits\*\*/m.test(first.text)) {
+            return result;
+        }
+        let cg;
+        try {
+            cg = this.getHomeGraph(projectRoot);
+        }
+        catch {
+            return result;
+        }
+        const section = formatHarmonyResourceHits(cg, query);
+        if (!section)
+            return result;
+        return {
+            ...result,
+            content: [{ type: 'text', text: `${section}\n\n${first.text}` }, ...rest],
+        };
+    }
+    /** Spec 0048 §1–2: Capability profiles or form negative evidence. */
+    prependHarmonyCapabilityProfiles(result, projectRoot, query) {
+        const [first, ...rest] = result.content;
+        if (!first || first.type !== 'text')
+            return result;
+        if (/^\*\*Capability profiles/m.test(first.text)
+            || /\n\*\*Capability profiles/m.test(first.text)) {
+            return result;
+        }
+        let cg;
+        try {
+            cg = this.getHomeGraph(projectRoot);
+        }
+        catch {
+            return result;
+        }
+        const section = formatHarmonyCapabilityProfiles(cg, query);
+        if (!section)
+            return result;
+        return {
+            ...result,
+            content: [{ type: 'text', text: `${section}\n\n${first.text}` }, ...rest],
+        };
+    }
+    /** Spec 0048 §5: seam notes for located anchors. */
+    prependHarmonySeamNotes(result, projectRoot, emission) {
+        const located = emission?.locatedNodes;
+        if (!located || located.length === 0)
+            return result;
+        const [first, ...rest] = result.content;
+        if (!first || first.type !== 'text')
+            return result;
+        if (/^\*\*Seam notes\*\*/m.test(first.text) || /\n\*\*Seam notes\*\*/m.test(first.text)) {
+            return result;
+        }
+        let cg;
+        try {
+            cg = this.getHomeGraph(projectRoot);
+        }
+        catch {
+            return result;
+        }
+        const section = formatHarmonySeamNotes(cg, projectRoot, located);
+        if (!section)
+            return result;
+        return {
+            ...result,
+            content: [{ type: 'text', text: `${section}\n\n${first.text}` }, ...rest],
+        };
+    }
     /**
      * An explore response plus the record of what it emitted (CG-17). The record
      * rides the result only as far as {@link execute}, which files it into the
@@ -11646,17 +12255,42 @@ class ToolHandler {
      */
     exploreResult(text, emission) {
         const meta = (0, explore_repeat_guard_1.inferExplorePartialMeta)(text);
-        const result = this.textResult(text);
+        let evidenceStatus = emission.evidenceStatus
+            ?? (emission.sourceBytes > 0 ? (meta.partial ? 'partial' : 'complete') : 'partial');
+        let body = text;
+        // Spec 0044 §8: Located banner when complete exact evidence; soften Partial wording.
+        if (evidenceStatus === 'complete' && !body.includes(locate_contract_1.LOCATED_MARKER)) {
+            if (/\*\*Partial locator\*\*/i.test(body)) {
+                body = body.replace(/>\s*\*\*Partial locator\*\*[^\n]*/gi, (0, locate_contract_1.formatLocatedBanner)());
+            }
+            else if (!/\*\*ANSWER NOW/i.test(body) && !body.includes(locate_contract_1.MISS_MARKER)) {
+                body = `${(0, locate_contract_1.formatLocatedBanner)()}\n\n${body}`;
+            }
+        }
+        else if ((evidenceStatus === 'partial' || meta.partial)
+            && /\*\*Partial locator\*\*/i.test(body)
+            && !body.includes(locate_contract_1.LOCATED_MARKER)) {
+            // Spec 0044 §8: Partial next-step → node/usages/search (not Grep same names).
+            body = body.replace(/>\s*\*\*Partial locator\*\*[^\n]*/gi, (0, locate_contract_1.formatPartialBanner)());
+        }
+        let result = this.textResult(body);
+        result = this.prependHarmonyRegistrationSources(result, emission.projectRoot, emission.query);
+        result = this.prependHarmonyCapabilityProfiles(result, emission.projectRoot, emission.query);
+        result = this.prependHarmonyResourceHits(result, emission.projectRoot, emission.query);
         result[explore_session_state_1.EXPLORE_EMISSION_KEY] = {
             ...emission,
-            evidenceStatus: emission.evidenceStatus ?? (emission.sourceBytes > 0 ? (meta.partial ? 'partial' : 'complete') : 'partial'),
-            partial: emission.partial ?? (emission.evidenceStatus && emission.evidenceStatus !== 'complete' ? true : meta.partial),
+            evidenceStatus,
+            partial: emission.partial ?? (evidenceStatus !== 'complete' ? true : meta.partial),
             nextAnchor: emission.nextAnchor ?? meta.nextAnchor,
         };
+        result = this.prependHarmonySeamNotes(result, emission.projectRoot, result[explore_session_state_1.EXPLORE_EMISSION_KEY]);
         return result;
     }
     /** Attach a minimal session emission when a compact/light path used textResult. */
     ensureExploreEmission(result, projectRoot, query) {
+        result = this.prependHarmonyRegistrationSources(result, projectRoot, query);
+        result = this.prependHarmonyCapabilityProfiles(result, projectRoot, query);
+        result = this.prependHarmonyResourceHits(result, projectRoot, query);
         if (result[explore_session_state_1.EXPLORE_EMISSION_KEY]) {
             const em = result[explore_session_state_1.EXPLORE_EMISSION_KEY];
             if (em.partial === undefined || !em.nextAnchor) {
@@ -11666,6 +12300,7 @@ class ToolHandler {
                 if (!em.nextAnchor && meta.nextAnchor)
                     em.nextAnchor = meta.nextAnchor;
             }
+            result = this.prependHarmonySeamNotes(result, projectRoot, em);
             return result;
         }
         const text = result.content?.[0]?.text ?? '';
@@ -11839,7 +12474,8 @@ class ToolHandler {
         const nodes = cg.getNodesInFile(filePath)
             .filter((n) => n.kind !== 'file' && n.kind !== 'import' && n.kind !== 'export')
             .sort((a, b) => a.startLine - b.startLine);
-        const dependents = cg.getFileDependents(filePath);
+        const dependents = cg.getFileDependents(filePath)
+            .filter((p) => !p.includes('@dummy') && !p.replace(/\\/g, '/').split('/').pop()?.startsWith('@dummy'));
         // Compact, one-line blast radius (homegraph's value-add over a plain Read).
         const depSummary = dependents.length
             ? `used by ${dependents.length} file${dependents.length === 1 ? '' : 's'}: ${dependents.slice(0, 8).join(', ')}${dependents.length > 8 ? `, +${dependents.length - 8} more` : ''}`
@@ -12019,6 +12655,8 @@ class ToolHandler {
             for (const e of edges) {
                 if (seen.has(e.node.id))
                     continue;
+                if ((0, query_utils_1.isMcpNoiseNode)(e.node))
+                    continue;
                 seen.add(e.node.id);
                 out.push(e);
             }
@@ -12194,14 +12832,47 @@ class ToolHandler {
             return this.textResult('No modules found in the project map.');
         }
         const FILE_CAP = 80;
+        const projectRoot = cg.getProjectRoot();
+        const hasHarmony = map.modules.some((m) => m.kind === 'harmony');
         const lines = [
             `**Project map** (phase=${map.phase})`,
             `modules: ${map.modules.length} · files: ${map.fileCount}`,
-            '',
         ];
+        // Spec 0040 — Harmony skeleton summary (navigation pointers, not call edges).
+        try {
+            const bundle = (0, project_map_1.readHarmonyAppBundleName)(projectRoot);
+            if (bundle)
+                lines.push(`bundle: \`${bundle}\` (from app.json5)`);
+        }
+        catch {
+            /* omit */
+        }
+        if (hasHarmony) {
+            lines.push('modules from `build-profile.json5` — skeleton map only (not call edges; use `homegraph_explore` for route_map → page)');
+        }
+        lines.push('');
         for (const m of map.modules) {
             const rootLabel = m.rootPath || '.';
             lines.push(`### ${m.name} (\`${rootLabel}\`) · ${m.kind} · ${m.fileCount} files`);
+            if (m.kind === 'harmony' || m.rootPath) {
+                try {
+                    const profiles = (0, project_map_1.listHarmonyRouteProfilesUnderModule)(projectRoot, m.rootPath || '');
+                    for (const p of profiles) {
+                        lines.push(`- route profile: \`${p}\``);
+                    }
+                }
+                catch {
+                    /* omit */
+                }
+                try {
+                    const ohpm = (0, project_map_1.readModuleOhPackageName)(projectRoot, m.rootPath || '');
+                    if (ohpm)
+                        lines.push(`- oh-package: \`${ohpm}\``);
+                }
+                catch {
+                    /* omit */
+                }
+            }
             if (m.files && m.files.length > 0) {
                 const shown = m.files.slice(0, FILE_CAP);
                 for (const f of shown) {
@@ -12213,6 +12884,42 @@ class ToolHandler {
             }
             lines.push('');
         }
+        // Spec 0048 §4 — module roster with local file: deps.
+        try {
+            const roster = (0, project_map_1.formatHarmonyModuleRoster)(projectRoot, map.modules);
+            if (roster) {
+                lines.push(roster);
+                lines.push('');
+            }
+        }
+        catch {
+            /* omit roster on failure */
+        }
+        // Spec 0042 B — path inventory (string/rawfile/media + unindexed package dirs).
+        // Skip when the caller filtered to a single non-Harmony module? Still useful
+        // project-wide; keep always on Harmony-shaped trees or whenever scan finds hits.
+        try {
+            const indexedPaths = map.modules.flatMap((m) => (m.files ?? []).map((f) => f.path));
+            // When includeFiles=false, files arrays are empty — fall back to full map paths.
+            let pathsForUnindexed = indexedPaths;
+            if (pathsForUnindexed.length === 0) {
+                try {
+                    const full = cg.getProjectMap({ includeFiles: true });
+                    pathsForUnindexed = full.modules.flatMap((m) => (m.files ?? []).map((f) => f.path));
+                }
+                catch {
+                    pathsForUnindexed = [];
+                }
+            }
+            const inv = (0, project_map_1.scanHarmonyResourceInventory)(projectRoot, { indexedPaths: pathsForUnindexed });
+            const section = (0, project_map_1.formatHarmonyResourceInventory)(inv);
+            if (section) {
+                lines.push(section);
+            }
+        }
+        catch {
+            /* omit inventory on scan failure */
+        }
         return this.textResult(lines.join('\n').trimEnd());
     }
     /**