homegraph 1.5.10 → 1.6.0

package/dist/mcp/index-availability.js

@@ -6,12 +6,16 @@
  * pending dirty files) to the five states hosts and agents should see.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRODUCT_STATUS_GLOSSARY = void 0;
+exports.BOUND_PROJECT_PATH_PIN_MARKER = exports.PROJECT_ROOT_HINT_MARKER = exports.PRODUCT_STATUS_GLOSSARY = void 0;
 exports.productIndexGuidance = productIndexGuidance;
 exports.formatProductStatusLine = formatProductStatusLine;
 exports.resolveProductIndexState = resolveProductIndexState;
 exports.isSqliteBusyMessage = isSqliteBusyMessage;
 exports.textAlreadyHasProductStatus = textAlreadyHasProductStatus;
+exports.formatProjectRootPathHint = formatProjectRootPathHint;
+exports.textAlreadyHasProjectRootHint = textAlreadyHasProjectRootHint;
+exports.formatBoundProjectPathPinNotice = formatBoundProjectPathPinNotice;
+exports.textAlreadyHasBoundProjectPathPinNotice = textAlreadyHasBoundProjectPathPinNotice;
 /** One-line glossary for MCP initialize / tool surface (Spec 0035). */
 exports.PRODUCT_STATUS_GLOSSARY = 'status: empty=not ready · fast=map only (homegraph_project) · full=fresh · dirty=usable but listed paths outdated · syncing=write lock, retry';
 const MAX_DIRTY_PATHS = 5;
@@ -102,4 +106,39 @@ function isSqliteBusyMessage(message) {
 function textAlreadyHasProductStatus(text) {
     return /^\s*HomeGraph status=/m.test(text);
 }
+/** Marker line for Spec 0038 project-root path hint (idempotent prepend). */
+exports.PROJECT_ROOT_HINT_MARKER = 'HomeGraph project root:';
+/**
+ * Short preamble: absolute project root + how to join repo-relative paths (Spec 0038).
+ * `absRoot` should already be resolved (platform-native absolute path).
+ */
+function formatProjectRootPathHint(absRoot) {
+    const root = absRoot.trim();
+    return (`${exports.PROJECT_ROOT_HINT_MARKER} \`${root}\`\n` +
+        'Paths below are repo-relative to that root. Pass them to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes.');
+}
+/** True when text already carries a Spec 0038 project-root hint. */
+function textAlreadyHasProjectRootHint(text) {
+    return text.includes(exports.PROJECT_ROOT_HINT_MARKER);
+}
+/** Marker for Spec 0043 bound-root projectPath soft-pin notice (idempotent prepend). */
+exports.BOUND_PROJECT_PATH_PIN_MARKER = 'This MCP session is bound to';
+/**
+ * English preamble when a tool `projectPath` resolves to a different index root
+ * than the MCP session's default bound root (Spec 0043). Success-shaped — not isError.
+ */
+function formatBoundProjectPathPinNotice(opts) {
+    const bound = opts.boundRoot.trim();
+    const requested = opts.requestedPath.trim();
+    const resolved = opts.resolvedRoot === null
+        ? 'no .homegraph/ found walking up from it'
+        : `resolves to \`${opts.resolvedRoot.trim()}\``;
+    return (`${exports.BOUND_PROJECT_PATH_PIN_MARKER} \`${bound}\`.\n` +
+        `Ignoring projectPath=\`${requested}\` (${resolved}).\n` +
+        'Results below are from the bound project root only. Omit projectPath, or pass a path under that root.');
+}
+/** True when text already carries a Spec 0043 pin notice. */
+function textAlreadyHasBoundProjectPathPinNotice(text) {
+    return text.includes(exports.BOUND_PROJECT_PATH_PIN_MARKER);
+}
 //# sourceMappingURL=index-availability.js.map

package/dist/mcp/index.js

@@ -73,6 +73,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const directory_1 = require("../directory");
+const runtime_log_1 = require("../runtime-log");
 const transport_1 = require("./transport");
 const engine_1 = require("./engine");
 const session_1 = require("./session");
@@ -298,6 +299,7 @@ class MCPServer {
             // Runs until the host disconnects; the proxy installs its own watchdog and
             // falls back to an in-process engine if the daemon never comes up.
             this.mode = 'proxy';
+            (0, runtime_log_1.logLifecycle)('mcp.start', { projectRoot: root, mode: 'proxy' });
             await this.runProxyWithLocalHandshake(root);
             return;
         }
@@ -306,6 +308,7 @@ class MCPServer {
             // is still safe to recover from with a direct-mode session.
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Proxy path failed (${msg}); falling back to direct mode.\n`);
+            (0, runtime_log_1.logLifecycleError)('mcp.proxy.fail', { projectRoot: root, msg });
             return this.startDirect('proxy path threw');
         }
     }
@@ -346,6 +349,11 @@ class MCPServer {
         if (reason && process.env.HOMEGRAPH_MCP_DEBUG) {
             process.stderr.write(`[HomeGraph MCP] Direct mode: ${reason}.\n`);
         }
+        (0, runtime_log_1.logLifecycle)('mcp.start', {
+            projectRoot: this.projectPath ?? undefined,
+            mode: 'direct',
+            reason,
+        });
         // Direct mode = one client. Do NOT start a query-pool worker: each worker
         // is a second V8 isolate + a second open of the project DB, and on large
         // indexes (hundreds of MB) that alone pushed process-tree RSS to ~5GB.
@@ -392,6 +400,7 @@ class MCPServer {
      */
     async startDaemonProcess() {
         const root = resolveDaemonRoot(this.projectPath) ?? this.projectPath ?? process.cwd();
+        (0, runtime_log_1.logLifecycle)('mcp.start', { projectRoot: root, mode: 'daemon' });
         for (let attempt = 0; attempt < TAKEOVER_MAX_RETRIES; attempt++) {
             const lock = (0, daemon_1.tryAcquireDaemonLock)(root);
             if (lock.kind === 'acquired') {

package/dist/mcp/indexable-root.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cheap “is this root worth creating a HomeGraph index?” probe (Spec 0049).
+ *
+ * Used by MCP auto-init to avoid writing `.homegraph/` into empty workspaces
+ * (e.g. DevEco Code task dirs before `devecocli create`).
+ */
+/**
+ * True when `root` already looks like a project HomeGraph should index.
+ * Short-circuits on root `build-profile.json5`, else bounded BFS for any
+ * {@link isSourceFile} hit. Ignores `.homegraph*` and common build/vendor dirs.
+ */
+export declare function isIndexableRoot(rootDir: string, opts?: {
+    maxDirs?: number;
+    maxDepth?: number;
+}): boolean;
+/**
+ * Parse `HOMEGRAPH_DEFER_PROBE_MS`. Default **60000**.
+ * `0` disables the timer (tool-call kick only). Invalid → default.
+ * Clamp: 0, or 1000ms … 10min.
+ */
+export declare function parseDeferProbeMs(raw: string | undefined): number;
+//# sourceMappingURL=indexable-root.d.ts.map

package/dist/mcp/indexable-root.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Cheap “is this root worth creating a HomeGraph index?” probe (Spec 0049).
+ *
+ * Used by MCP auto-init to avoid writing `.homegraph/` into empty workspaces
+ * (e.g. DevEco Code task dirs before `devecocli create`).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIndexableRoot = isIndexableRoot;
+exports.parseDeferProbeMs = parseDeferProbeMs;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const grammars_1 = require("../extraction/grammars");
+const directory_1 = require("../directory");
+const HARMONY_PROFILE = 'build-profile.json5';
+/** Dirs skipped during the bounded source walk (names only). */
+const SKIP_DIR_NAMES = new Set([
+    'node_modules',
+    'oh_modules',
+    '.git',
+    '.hvigor',
+    '.preview',
+    '.cxx',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    'vendor',
+    'Pods',
+    'DerivedData',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'target',
+    '.gradle',
+    'obj',
+]);
+const DEFAULT_MAX_DIRS = 4000;
+const DEFAULT_MAX_DEPTH = 8;
+/**
+ * True when `root` already looks like a project HomeGraph should index.
+ * Short-circuits on root `build-profile.json5`, else bounded BFS for any
+ * {@link isSourceFile} hit. Ignores `.homegraph*` and common build/vendor dirs.
+ */
+function isIndexableRoot(rootDir, opts) {
+    const root = path.resolve(rootDir);
+    let st;
+    try {
+        st = fs.statSync(root);
+    }
+    catch {
+        return false;
+    }
+    if (!st.isDirectory())
+        return false;
+    if (fs.existsSync(path.join(root, HARMONY_PROFILE)))
+        return true;
+    const maxDirs = opts?.maxDirs ?? DEFAULT_MAX_DIRS;
+    const maxDepth = opts?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const queue = [{ dir: root, depth: 0 }];
+    let dirsSeen = 0;
+    while (queue.length > 0 && dirsSeen < maxDirs) {
+        const { dir, depth } = queue.shift();
+        dirsSeen += 1;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of entries) {
+            const name = ent.name;
+            if (name === '.' || name === '..')
+                continue;
+            if ((0, directory_1.isHomeGraphDataDir)(name) || SKIP_DIR_NAMES.has(name))
+                continue;
+            const full = path.join(dir, name);
+            if (ent.isDirectory()) {
+                if (depth + 1 <= maxDepth)
+                    queue.push({ dir: full, depth: depth + 1 });
+                continue;
+            }
+            if (ent.isFile() && (0, grammars_1.isSourceFile)(full))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parse `HOMEGRAPH_DEFER_PROBE_MS`. Default **60000**.
+ * `0` disables the timer (tool-call kick only). Invalid → default.
+ * Clamp: 0, or 1000ms … 10min.
+ */
+function parseDeferProbeMs(raw) {
+    if (raw === undefined || !raw.trim())
+        return 60_000;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n))
+        return 60_000;
+    if (n === 0)
+        return 0;
+    if (n < 1000 || n > 10 * 60 * 1000)
+        return 60_000;
+    return n;
+}
+//# sourceMappingURL=indexable-root.js.map

package/dist/mcp/liveness-watchdog.d.ts

@@ -7,6 +7,11 @@ export declare const DEFAULT_WATCHDOG_TIMEOUT_MS = 60000;
  * beyond any legitimate statement). 10× the 60s default ⇒ 10 minutes.
  */
 export declare const PROGRESS_CAP_MULTIPLIER = 10;
+/**
+ * Spec 0047: liveness watchdog is opt-in.
+ * Armed only when `HOMEGRAPH_WATCHDOG` is truthy and `HOMEGRAPH_NO_WATCHDOG` is not.
+ */
+export declare function isLivenessWatchdogEnabled(env?: NodeJS.ProcessEnv): boolean;
 /** Parse the timeout env, falling back to the default for missing/invalid values. */
 export declare function parseWatchdogTimeoutMs(raw: string | undefined, fallback?: number): number;
 /** Derive a heartbeat cadence that emits several beats inside the timeout window. */
@@ -42,7 +47,7 @@ export declare function installMainThreadWatchdog(options?: WatchdogOptions): Wa
  * resume function. Nested calls refcount; a `stop()` while suspended cancels
  * the pending re-arm.
  *
- * No-op when nothing is armed (tests, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
+ * No-op when nothing is armed (tests, default-off Spec 0047, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
  */
 export declare function suspendLivenessWatchdog(): () => void;
 /**

package/dist/mcp/liveness-watchdog.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROGRESS_CAP_MULTIPLIER = exports.DEFAULT_WATCHDOG_TIMEOUT_MS = void 0;
+exports.isLivenessWatchdogEnabled = isLivenessWatchdogEnabled;
 exports.parseWatchdogTimeoutMs = parseWatchdogTimeoutMs;
 exports.deriveCheckIntervalMs = deriveCheckIntervalMs;
 exports.installMainThreadWatchdog = installMainThreadWatchdog;
@@ -73,8 +74,9 @@ exports.runWithoutLivenessWatchdog = runWithoutLivenessWatchdog;
  * (off-thread) and the daemon's indexing shells out to a child process, so the
  * daemon's main thread only ever does fast, bounded work. The default timeout
  * is ~300× the 5h #850 wedge shorter, yet far longer than any legitimate
- * main-thread block. Opt out with `HOMEGRAPH_NO_WATCHDOG=1`; tune with
- * `HOMEGRAPH_WATCHDOG_TIMEOUT_MS`.
+ * main-thread block. Spec 0047: **opt in** with `HOMEGRAPH_WATCHDOG=1` (default
+ * off for product / DevEco concurrent init); `HOMEGRAPH_NO_WATCHDOG=1` still
+ * forces off. Tune with `HOMEGRAPH_WATCHDOG_TIMEOUT_MS`.
  *
  * **Disk-progress deferral (`progressPaths`).** The CLI `index`/`init` path is
  * different: it runs the SQLite store on this thread, and one long synchronous
@@ -118,6 +120,15 @@ function isEnvTruthy(raw) {
         return false;
     return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
 }
+/**
+ * Spec 0047: liveness watchdog is opt-in.
+ * Armed only when `HOMEGRAPH_WATCHDOG` is truthy and `HOMEGRAPH_NO_WATCHDOG` is not.
+ */
+function isLivenessWatchdogEnabled(env = process.env) {
+    if (isEnvTruthy(env.HOMEGRAPH_NO_WATCHDOG))
+        return false;
+    return isEnvTruthy(env.HOMEGRAPH_WATCHDOG);
+}
 /** Parse the timeout env, falling back to the default for missing/invalid values. */
 function parseWatchdogTimeoutMs(raw, fallback = exports.DEFAULT_WATCHDOG_TIMEOUT_MS) {
     if (raw === undefined)
@@ -153,7 +164,7 @@ const capMs = Number(process.argv[3]);
 const progressPaths = process.argv.slice(4);
 const secs = Math.round(timeoutMs / 1000);
 function kill(extra) {
-  try { fs.writeSync(2, Buffer.from('[HomeGraph] Main thread unresponsive for ~' + secs + 's' + (extra || '') + ' — killing the wedged process so a fresh one can start (#850). Disable with HOMEGRAPH_NO_WATCHDOG=1.\\n')); } catch (e) {}
+  try { fs.writeSync(2, Buffer.from('[HomeGraph] Main thread unresponsive for ~' + secs + 's' + (extra || '') + ' — killing the wedged process so a fresh one can start (#850). Disable with HOMEGRAPH_NO_WATCHDOG=1 (default off; enable with HOMEGRAPH_WATCHDOG=1).\\n')); } catch (e) {}
   try { process.kill(parentPid, 'SIGKILL'); } catch (e) {}
   process.exit(0);
 }
@@ -318,7 +329,8 @@ function rearmFromOptions(options) {
  * current generation.
  */
 function installMainThreadWatchdog(options = {}) {
-    if (isEnvTruthy(process.env.HOMEGRAPH_NO_WATCHDOG))
+    // Spec 0047: default off — set HOMEGRAPH_WATCHDOG=1 to arm.
+    if (!isLivenessWatchdogEnabled())
         return null;
     // Replace any prior generation (including a mid-suspend pending re-arm).
     suspendDepth = 0;
@@ -336,7 +348,7 @@ function installMainThreadWatchdog(options = {}) {
  * resume function. Nested calls refcount; a `stop()` while suspended cancels
  * the pending re-arm.
  *
- * No-op when nothing is armed (tests, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
+ * No-op when nothing is armed (tests, default-off Spec 0047, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
  */
 function suspendLivenessWatchdog() {
     suspendDepth++;

package/dist/mcp/locate-contract.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Spec 0044 — explore locate contract helpers (Located / Miss / Partial,
+ * literal-first demotion of log/toast spines, filename≠declaration hint,
+ * depth-fuse exemption for already-located symbols).
+ */
+import type { ExploreEmission, ExploreCallRecord, ExploreProjectState } from './explore-session-state';
+export type LocateOutcome = 'located' | 'partial' | 'miss';
+/** Marker strings (idempotent checks). */
+export declare const LOCATED_MARKER = "**Located**";
+export declare const MISS_MARKER = "**Miss**";
+export declare const FILENAME_DECL_MISMATCH_MARKER = "Filename does not match primary declaration";
+/** Query explicitly names a log/toast API — then those nodes may stay on the spine. */
+export declare function queryNamesLogOrToast(query: string): boolean;
+export declare function isLogOrToastSpineName(name: string): boolean;
+/** Demote log/toast when the user did not ask for them. */
+export declare function shouldDemoteLogToastSpine(name: string, query: string): boolean;
+/**
+ * Classify locate outcome for explore (Spec 0044 §8–9).
+ * Exact anchor / literal witness beats fuzzy-only FTS.
+ */
+export declare function classifyLocateOutcome(opts: {
+    hasExactAnchorHit: boolean;
+    hasLiteralWitness: boolean;
+    hasFullDeclarations: boolean;
+    missingStaticRelation: boolean;
+    budgetPartial: boolean;
+}): LocateOutcome;
+export declare function formatLocatedBanner(): string;
+export declare function formatPartialBanner(): string;
+/** Miss: paths only, no source bodies. */
+export declare function formatMissBanner(candidatePaths: readonly string[]): string;
+/**
+ * When file basename (sans extension) ≠ primary declaration name.
+ * Returns null when names match or inputs are empty.
+ */
+export declare function formatFilenameDeclarationMismatch(filePath: string, primaryDeclName: string | null | undefined): string | null;
+/** Names recorded on the latest counted explore emission. */
+export declare function locatedNamesFromEmission(emission: ExploreEmission | ExploreCallRecord | null | undefined): string[];
+export declare function symbolMatchesLocatedNames(symbol: string | undefined, locatedNames: readonly string[]): boolean;
+/**
+ * Spec 0044 §10.2 — do not depth-fuse-refuse a symbol already present on the
+ * latest explore locate list (even after Partial spent its one generic drill).
+ */
+export declare function shouldExemptDepthFuseForLocatedSymbol(prior: ExploreProjectState | null | undefined, symbol: string | undefined): boolean;
+/** Strip CJK→ASCII synonym seeds when Miss-bound (Spec 0044 §9). */
+export declare function shouldSuppressSynonymExpansion(opts: {
+    hasExactAnchorHit: boolean;
+    hasLiteralWitness: boolean;
+}): boolean;
+//# sourceMappingURL=locate-contract.d.ts.map

package/dist/mcp/locate-contract.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Spec 0044 — explore locate contract helpers (Located / Miss / Partial,
+ * literal-first demotion of log/toast spines, filename≠declaration hint,
+ * depth-fuse exemption for already-located symbols).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILENAME_DECL_MISMATCH_MARKER = exports.MISS_MARKER = exports.LOCATED_MARKER = void 0;
+exports.queryNamesLogOrToast = queryNamesLogOrToast;
+exports.isLogOrToastSpineName = isLogOrToastSpineName;
+exports.shouldDemoteLogToastSpine = shouldDemoteLogToastSpine;
+exports.classifyLocateOutcome = classifyLocateOutcome;
+exports.formatLocatedBanner = formatLocatedBanner;
+exports.formatPartialBanner = formatPartialBanner;
+exports.formatMissBanner = formatMissBanner;
+exports.formatFilenameDeclarationMismatch = formatFilenameDeclarationMismatch;
+exports.locatedNamesFromEmission = locatedNamesFromEmission;
+exports.symbolMatchesLocatedNames = symbolMatchesLocatedNames;
+exports.shouldExemptDepthFuseForLocatedSymbol = shouldExemptDepthFuseForLocatedSymbol;
+exports.shouldSuppressSynonymExpansion = shouldSuppressSynonymExpansion;
+const explore_session_state_1 = require("./explore-session-state");
+const explore_repeat_guard_1 = require("./explore-repeat-guard");
+/** Marker strings (idempotent checks). */
+exports.LOCATED_MARKER = '**Located**';
+exports.MISS_MARKER = '**Miss**';
+exports.FILENAME_DECL_MISMATCH_MARKER = 'Filename does not match primary declaration';
+const LOG_TOAST_NAME_RE = /^(?:Logger|Hilog|HiLog|Toast|promptAction|log(?:Info|Error|Warn|Debug|Fatal)?|hilog)$/i;
+/** Query explicitly names a log/toast API — then those nodes may stay on the spine. */
+function queryNamesLogOrToast(query) {
+    return /\b(?:Logger|hilog|HiLog|Toast|promptAction|logInfo|logError|logWarn|logDebug)\b/i.test(query)
+        || /日志|弹窗|吐司/.test(query);
+}
+function isLogOrToastSpineName(name) {
+    return LOG_TOAST_NAME_RE.test(name.trim());
+}
+/** Demote log/toast when the user did not ask for them. */
+function shouldDemoteLogToastSpine(name, query) {
+    return isLogOrToastSpineName(name) && !queryNamesLogOrToast(query);
+}
+/**
+ * Classify locate outcome for explore (Spec 0044 §8–9).
+ * Exact anchor / literal witness beats fuzzy-only FTS.
+ */
+function classifyLocateOutcome(opts) {
+    if (!opts.hasExactAnchorHit && !opts.hasLiteralWitness)
+        return 'miss';
+    if (opts.budgetPartial || opts.missingStaticRelation)
+        return 'partial';
+    if (opts.hasFullDeclarations && (opts.hasExactAnchorHit || opts.hasLiteralWitness)) {
+        return 'located';
+    }
+    return 'partial';
+}
+function formatLocatedBanner() {
+    return (`> ${exports.LOCATED_MARKER} — exact anchor declaration(s) are in this reply. `
+        + 'Reuse them; do **not** Grep the same symbol names again. '
+        + 'Runtime behavior may still need validation after edits.');
+}
+function formatPartialBanner() {
+    return ('> **Partial** — evidence is incomplete (missing relation or budget). '
+        + 'Next: `homegraph_node` / `homegraph_usages` / `homegraph_search` for the named gap — '
+        + 'do **not** Grep the same symbol names already shown.');
+}
+/** Miss: paths only, no source bodies. */
+function formatMissBanner(candidatePaths) {
+    const paths = candidatePaths
+        .map((p) => p.replace(/\\/g, '/').trim())
+        .filter(Boolean)
+        .slice(0, 12);
+    const list = paths.length
+        ? paths.map((p) => `- \`${p}\``).join('\n')
+        : '- _(no fuzzy path candidates)_';
+    return [
+        `> ${exports.MISS_MARKER} — no exact in-repo anchor or literal witness. Source bodies omitted.`,
+        'Fuzzy candidate paths (no source):',
+        list,
+        'Next: `homegraph_search` with a more precise symbol, file basename, or quoted UI label.',
+    ].join('\n');
+}
+/**
+ * When file basename (sans extension) ≠ primary declaration name.
+ * Returns null when names match or inputs are empty.
+ */
+function formatFilenameDeclarationMismatch(filePath, primaryDeclName) {
+    if (!primaryDeclName?.trim())
+        return null;
+    const base = filePath.replace(/\\/g, '/').split('/').pop() ?? '';
+    const stem = base.replace(/\.[^.]+$/, '');
+    if (!stem)
+        return null;
+    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (norm(stem) === norm(primaryDeclName))
+        return null;
+    return (`> ⚠ ${exports.FILENAME_DECL_MISMATCH_MARKER}: file \`${stem}\` vs \`${primaryDeclName.trim()}\` — `
+        + 'prefer the declaration name for edits and follow-up queries.');
+}
+/** Names recorded on the latest counted explore emission. */
+function locatedNamesFromEmission(emission) {
+    if (!emission?.locatedNodes?.length)
+        return [];
+    const out = new Set();
+    for (const n of emission.locatedNodes) {
+        if (n?.name)
+            out.add(n.name);
+        if (n?.qualifiedName) {
+            out.add(n.qualifiedName);
+            const leaf = n.qualifiedName.split(/[.::]/).pop();
+            if (leaf)
+                out.add(leaf);
+        }
+    }
+    return [...out];
+}
+function symbolMatchesLocatedNames(symbol, locatedNames) {
+    const raw = symbol?.trim();
+    if (!raw || locatedNames.length === 0)
+        return false;
+    const needle = raw.toLowerCase();
+    const leaf = needle.split(/[.::]/).pop() ?? needle;
+    for (const n of locatedNames) {
+        const ln = n.toLowerCase();
+        if (ln === needle || ln === leaf)
+            return true;
+        if (ln.endsWith(`.${leaf}`) || ln.endsWith(`::${leaf}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Spec 0044 §10.2 — do not depth-fuse-refuse a symbol already present on the
+ * latest explore locate list (even after Partial spent its one generic drill).
+ */
+function shouldExemptDepthFuseForLocatedSymbol(prior, symbol) {
+    const last = (0, explore_repeat_guard_1.latestCountedExplore)(prior);
+    if (!last)
+        return false;
+    // Closed explores already skip the fuse; exemption matters for Partial/Miss.
+    if ((0, explore_session_state_1.inferExploreEvidenceStatus)(last) === 'complete')
+        return false;
+    return symbolMatchesLocatedNames(symbol, locatedNamesFromEmission(last));
+}
+/** Strip CJK→ASCII synonym seeds when Miss-bound (Spec 0044 §9). */
+function shouldSuppressSynonymExpansion(opts) {
+    return !opts.hasExactAnchorHit && !opts.hasLiteralWitness;
+}
+//# sourceMappingURL=locate-contract.js.map

package/dist/mcp/server-instructions.d.ts

@@ -1,3 +1,3 @@
-export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 optional structural evidence for this repo\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism \u2192 `homegraph_explore`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.\n\nA project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n## Index status\n\nTool replies end with `HomeGraph status=\u2026`. status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\nNo index \u2192 use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.\n";
-export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 optional per-project evidence\n\nPass `projectPath` to an already indexed folder with `.homegraph/`. No index \u2192 use ordinary tools; indexing is managed by the host.\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism \u2192 `homegraph_explore`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.\n\nA project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n## Index status\n\nTool replies end with `HomeGraph status=\u2026`. status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\n";
+export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 optional structural evidence for this repo\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Engineering overview / which module owns a feature / where `route_map.json` or resource dirs live \u2192 `homegraph_project` (module map + Harmony skeleton pointers + Module roster with local `file:` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism or route registration edges \u2192 `homegraph_explore` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for `element/string.json` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n- Harmony `element/string.json` key/value lookup is searchable via explore/search (Resource hits may include bound `.ets` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.\n- Harmony `form_config.json` / `shortcuts_config.json` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project \u2014 do not treat SDK Form `.d.ts` as project wiring when the negative note says no in-repo form.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with `HomeGraph project root: `\u2026`` \u2014 that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched `projectPath` is ignored (results stay on the bound root) with a short English notice \u2014 do not treat that as a hard error.\n\nA project map (`homegraph_project`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n## Index status\n\nTool replies may start with `HomeGraph project root: \u2026` (absolute join base for relative paths) and end with `HomeGraph status=\u2026`. status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\nNo index \u2192 use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.\n";
+export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 optional per-project evidence\n\nPass `projectPath` to an already indexed folder with `.homegraph/`. No index \u2192 use ordinary tools; indexing is managed by the host.\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Engineering overview / which module owns a feature / where `route_map.json` or resource dirs live \u2192 `homegraph_project` (module map + Harmony skeleton pointers + Module roster with local `file:` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism or route registration edges \u2192 `homegraph_explore` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for `element/string.json` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n- Harmony `element/string.json` key/value lookup is searchable via explore/search (Resource hits may include bound `.ets` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.\n- Harmony `form_config.json` / `shortcuts_config.json` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project \u2014 do not treat SDK Form `.d.ts` as project wiring when the negative note says no in-repo form.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with `HomeGraph project root: `\u2026`` \u2014 that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched `projectPath` is ignored (results stay on the bound root) with a short English notice \u2014 do not treat that as a hard error.\n\nA project map (`homegraph_project`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n## Index status\n\nTool replies may start with `HomeGraph project root: \u2026` (absolute join base for relative paths) and end with `HomeGraph status=\u2026`. status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\n";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/server-instructions.js

@@ -20,23 +20,26 @@ Use ordinary bash/search/read tools first for repository paths, symbols, literal
 HomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.
 
 Choose the smallest available tool for that gap:
+- Engineering overview / which module owns a feature / where \`route_map.json\` or resource dirs live → \`homegraph_project\` (module map + Harmony skeleton pointers + Module roster with local \`file:\` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.
 - Exact usage/reference locations → \`homegraph_usages\`; callers/callees → the corresponding tool.
 - Named module dependencies/cycles → \`homegraph_modules\`; native exports/registration → \`homegraph_native\`.
 - One missing symbol body → \`homegraph_node\`; prefer direct read if its path is already known.
-- An unresolved cross-symbol mechanism → \`homegraph_explore\`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.
+- An unresolved cross-symbol mechanism or route registration edges → \`homegraph_explore\` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for \`element/string.json\` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.
 - ArkUI migration analysis → \`homegraph_arkui_migrate\` when that analysis is needed; SDK contracts → project declarations or SDK documentation.
+- Harmony \`element/string.json\` key/value lookup is searchable via explore/search (Resource hits may include bound \`.ets\` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.
+- Harmony \`form_config.json\` / \`shortcuts_config.json\` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project — do not treat SDK Form \`.d.ts\` as project wiring when the negative note says no in-repo form.
 
 Do not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.
 `;
 const QUERY = `## Query and recovery
 
-Write one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as \`taskContext\` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.
+Write one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as \`taskContext\` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with \`HomeGraph project root: \`…\`\` — that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as \`<root>/<relative>\` (use \`/\`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched \`projectPath\` is ignored (results stay on the bound root) with a short English notice — do not treat that as a hard error.
 
-A project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: ≤2 \`homegraph_explore\` attempts per project, ≤1 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.
+A project map (\`homegraph_project\`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: ≤2 \`homegraph_explore\` attempts per project, ≤1 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.
 `;
 const INDEX_STATUS = `## Index status
 
-Tool replies end with \`HomeGraph status=…\`. ${index_availability_1.PRODUCT_STATUS_GLOSSARY}.
+Tool replies may start with \`HomeGraph project root: …\` (absolute join base for relative paths) and end with \`HomeGraph status=…\`. ${index_availability_1.PRODUCT_STATUS_GLOSSARY}.
 `;
 exports.SERVER_INSTRUCTIONS = `# HomeGraph — optional structural evidence for this repo