homegraph 1.5.8 → 1.6.0

package/dist/mcp/tools.js

@@ -12,6 +12,11 @@ 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;
@@ -26,9 +31,11 @@ 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 memory_budget_1 = require("./memory-budget");
+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;
@@ -56,6 +63,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");
@@ -566,6 +574,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.
@@ -922,11 +1182,12 @@ 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. ' +
+            '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. ' +
@@ -968,9 +1229,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: {
@@ -1327,6 +1591,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
@@ -1560,12 +1828,11 @@ class ToolHandler {
                 if (state === 'empty') {
                     return (0, index_availability_1.productIndexGuidance)('empty');
                 }
-                if (state === 'fast' || state === 'syncing') {
-                    // Keep the Spec 0027 "still building → homegraph_project" story for
-                    // frozen tools/list descriptions (hosts snapshot once at connect).
-                    return state === 'syncing'
-                        ? (0, index_availability_1.productIndexGuidance)('syncing')
-                        : "HomeGraph is still building this project's index. A call right now returns build-progress guidance; use `homegraph_project` for the module/file map, then retry once indexing finishes.";
+                if (state === 'fast') {
+                    return (0, index_availability_1.productIndexGuidance)('fast');
+                }
+                if (state === 'syncing') {
+                    return (0, index_availability_1.productIndexGuidance)('syncing');
                 }
             }
             catch {
@@ -1582,6 +1849,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)();
@@ -1628,25 +1900,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);
@@ -1891,58 +2172,98 @@ 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] };
         }
-        // Defensive: some test fakes inject a partial HomeGraph stub without the
-        // newer pending-files API. Treat missing/throwing as "no pending files."
-        let pending = [];
+        // Spec 0035: pending/dirty is a one-line status footer (withProductStatusFooter),
+        // not the long ⚠️ stale banner. Keep formatStaleBanner helpers for tests /
+        // status tool; do not prepend them on every read tool.
+        return result;
+    }
+    /**
+     * 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)
+            return result;
+        const [first, ...rest] = result.content;
+        if (!first || first.type !== 'text')
+            return result;
+        let cg;
         try {
-            pending = cg.getPendingFiles?.() ?? [];
+            cg = this.getHomeGraph(projectPath);
         }
         catch {
             return result;
         }
-        if (pending.length === 0)
-            return result;
-        const [first, ...rest] = result.content;
-        if (!first || first.type !== 'text')
-            return result;
-        const text = first.text;
-        const inResponse = [];
-        const elsewhere = [];
-        for (const p of pending) {
-            // Substring match against the project-relative POSIX path — that's
-            // exactly the format both the watcher and every homegraph response
-            // emit, so a plain includes() is sufficient and avoids regex pitfalls.
-            if (text.includes(p.path))
-                inResponse.push(p);
-            else
-                elsewhere.push(p);
+        if (this.cg && cg !== this.cg) {
+            try {
+                const sameProject = (0, path_1.resolve)(this.cg.getProjectRoot()) === (0, path_1.resolve)(cg.getProjectRoot());
+                if (sameProject)
+                    cg = this.cg;
+            }
+            catch {
+                /* leave cg */
+            }
         }
-        let banner = '';
-        if (inResponse.length > 0) {
-            let dbPath = null;
+        let text = first.text;
+        // Spec 0038: absolute project root + how to join repo-relative paths (idempotent).
+        if (!(0, index_availability_1.textAlreadyHasProjectRootHint)(text)) {
             try {
-                // Large indexes skip catch-up — soft banner so agents don't abandon HG for Read.
-                const root = cg.getProjectRoot();
-                dbPath = (0, path_1.resolve)(root, '.homegraph', 'homegraph.db');
+                const absRoot = (0, path_1.resolve)(cg.getProjectRoot());
+                if (absRoot) {
+                    text = `${(0, index_availability_1.formatProjectRootPathHint)(absRoot)}\n\n${text}`;
+                }
             }
             catch {
-                dbPath = null;
+                /* no root — skip hint */
             }
-            banner = formatStaleBanner(inResponse, {
-                catchUpDeferred: (0, memory_budget_1.shouldSkipCatchUpSync)(dbPath),
-            });
         }
-        let footer = '';
-        if (elsewhere.length > 0) {
-            footer = formatStaleFooter(elsewhere);
+        // 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}`;
         }
-        if (!banner && !footer)
-            return result;
-        const composed = [banner, text, footer].filter(Boolean).join('\n\n');
-        return { ...result, content: [{ type: 'text', text: composed }, ...rest] };
+        // Spec 0035: one-line product index status footer (skip if already present).
+        if (!(0, index_availability_1.textAlreadyHasProductStatus)(text)) {
+            let state;
+            try {
+                state = (0, index_availability_1.resolveProductIndexState)(cg);
+            }
+            catch {
+                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}`;
+        }
+        return {
+            ...result,
+            content: [{ type: 'text', text }, ...rest],
+        };
     }
     /**
      * Execute a tool by name.
@@ -1952,10 +2273,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
@@ -2069,7 +2427,7 @@ class ToolHandler {
                         && this.areEvidenceFilesCurrent(cachedFiles ?? [], cacheCg.getProjectRoot())))) {
                         const diagnosed = this.withQueryPlanDiagnostics(cached, args, true);
                         const withWorktree = this.withWorktreeNotice(diagnosed, projectPath);
-                        return this.withStalenessNotice(withWorktree, projectPath);
+                        return this.withProductStatusFooter(this.withStalenessNotice(withWorktree, projectPath), projectPath);
                     }
                 }
                 catch {
@@ -2133,7 +2491,7 @@ class ToolHandler {
                                 cacheIndex.setEntry(cacheQueries, cacheKey, toolName, served);
                             }
                             const withWorktree = this.withWorktreeNotice(served, projectPath);
-                            return this.withStalenessNotice(withWorktree, projectPath);
+                            return this.withProductStatusFooter(this.withStalenessNotice(withWorktree, projectPath), projectPath);
                         }
                         if (requestPlan)
                             args[QUERY_FAST_ATTEMPTED_ARG] = true;
@@ -2164,7 +2522,7 @@ class ToolHandler {
                 cacheIndex.setEntry(cacheQueries, cacheKey, toolName, result);
             }
             const withWorktree = this.withWorktreeNotice(result, projectPath);
-            return this.withStalenessNotice(withWorktree, projectPath);
+            return this.withProductStatusFooter(this.withStalenessNotice(withWorktree, projectPath), projectPath);
         }
         catch (err) {
             // Expected condition, not a malfunction: answer as a SUCCESS so the
@@ -2218,15 +2576,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;
@@ -2298,6 +2660,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 */ }
@@ -2509,7 +2875,7 @@ class ToolHandler {
      */
     maybeDeepToolPhaseGate(cg, _toolName) {
         const state = (0, index_availability_1.resolveProductIndexState)(cg);
-        if (state === 'full')
+        if (state === 'full' || state === 'dirty')
             return null;
         if (state === 'syncing') {
             return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
@@ -3146,6 +3512,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 {
@@ -6314,7 +6687,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;
@@ -6773,9 +7152,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();
@@ -7222,7 +7600,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;
                         }
@@ -7411,11 +7791,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++;
@@ -9634,6 +10018,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';
@@ -9645,19 +10031,28 @@ 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))
+            || 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: plan?.literalTexts,
+                    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 });
@@ -9666,7 +10061,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);
@@ -9677,10 +10080,26 @@ class ToolHandler {
         }
         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);
@@ -9848,7 +10267,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;
@@ -10209,10 +10628,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;
@@ -10237,6 +10658,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
@@ -10260,7 +10697,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;
@@ -10269,6 +10706,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;
@@ -11341,7 +11789,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
@@ -11635,6 +12091,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
@@ -11642,17 +12198,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) {
@@ -11662,6 +12243,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 ?? '';
@@ -11835,7 +12417,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` : ''}`
@@ -12015,6 +12598,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);
             }
@@ -12190,21 +12775,47 @@ class ToolHandler {
             return this.textResult('No modules found in the project map.');
         }
         const FILE_CAP = 80;
-        const productState = (0, index_availability_1.resolveProductIndexState)(cg);
+        const projectRoot = cg.getProjectRoot();
+        const hasHarmony = map.modules.some((m) => m.kind === 'harmony');
         const lines = [
-            `**Project map** (status=${productState}, phase=${map.phase})`,
+            `**Project map** (phase=${map.phase})`,
             `modules: ${map.modules.length} · files: ${map.fileCount}`,
-            '',
         ];
-        if (productState === 'fast' || map.phase === 'fast' || map.phase === 'indexing') {
-            lines.push('_Full symbol index still building — this map has modules/files only (no call graph)._', '');
+        // 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 (productState === 'syncing') {
-            lines.push('_Index write in progress — map may be briefly stale._', '');
+        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) {
@@ -12216,6 +12827,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());
     }
     /**