homegraph 1.5.7 → 1.5.8

package/dist/mcp/engine.js

@@ -49,7 +49,6 @@ exports.parseFixedWindowEnv = parseFixedWindowEnv;
 exports.parseDebounceEnv = parseDebounceEnv;
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
 const directory_1 = require("../directory");
 const sync_1 = require("../sync");
 const tools_1 = require("./tools");
@@ -87,7 +86,7 @@ class MCPEngine {
     // project is open — workers each hold their own WAL read connection.
     queryPool = null;
     constructor(opts = {}) {
-        this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false };
+        this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false, rootFloor: opts.rootFloor ?? null };
         this.toolHandler = new tools_1.ToolHandler(null);
     }
     /**
@@ -146,7 +145,7 @@ class MCPEngine {
      * subsequent-tool-call semantics; we preserve them by NOT throwing when the
      * search misses (just leaves `cg` null so the next call can retry).
      */
-    async ensureInitialized(searchFrom) {
+    async ensureInitialized(searchFrom, floor) {
         if (this.closed)
             return;
         if (this.toolHandler.hasDefaultHomeGraph())
@@ -158,7 +157,7 @@ class MCPEngine {
             catch { /* let caller retry */ }
             return;
         }
-        this.initPromise = this.doInitialize(searchFrom).finally(() => {
+        this.initPromise = this.doInitialize(searchFrom, floor).finally(() => {
             this.initPromise = null;
         });
         try {
@@ -174,13 +173,13 @@ class MCPEngine {
      * background `ensureInitialized` already finished (or failed) and we need
      * to pick up a project that appeared *after* the engine started.
      */
-    retryInitializeSync(searchFrom) {
+    retryInitializeSync(searchFrom, floor) {
         if (this.closed)
             return;
         if (this.toolHandler.hasDefaultHomeGraph())
             return;
         this.toolHandler.setDefaultProjectHint(searchFrom);
-        const resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(searchFrom);
+        const resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(searchFrom, floor ?? this.opts.rootFloor ?? undefined);
         if (!resolvedRoot)
             return;
         try {
@@ -230,9 +229,9 @@ class MCPEngine {
             this.cg = null;
         }
     }
-    async doInitialize(searchFrom) {
+    async doInitialize(searchFrom, floor) {
         this.toolHandler.setDefaultProjectHint(searchFrom);
-        let resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(searchFrom);
+        let resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(searchFrom, floor ?? this.opts.rootFloor ?? undefined);
         if (!resolvedRoot && autoInitEnabled()) {
             const created = await this.tryAutoInit(searchFrom);
             if (created)
@@ -280,66 +279,86 @@ class MCPEngine {
             process.stderr.write(`[HomeGraph MCP] Auto-init skipped — ${invalid}\n`);
             return false;
         }
+        // Race: another process finished init before we entered — open, don't bail
+        // (Spec 0032). Returning false here left the session with no cg forever.
         if ((0, directory_1.isInitialized)(root)) {
-            // Race: another process finished init between our findNearest and here.
-            return false;
+            return this.openAfterAutoInitRace(root);
         }
         try {
             process.stderr.write(`[HomeGraph MCP] Auto-init at ${root}\n`);
             const HomeGraph = loadHomeGraph();
             // Create DB immediately so tools/open succeed; index in background.
             const cg = await HomeGraph.init(root, { index: false });
+            // Pin empty state before returning so the first tool call cannot see `none`
+            // while the async fast-map task has not started (Spec 0032).
+            cg.setBuildPhase('building_fast');
             this.cg = cg;
             this.projectPath = root;
             this.toolHandler.setDefaultHomeGraph(cg);
-            this.startWatching();
+            // Defer watch/catch-up until the full build finishes so auto-sync does not
+            // contend with the same-process writer (Spec 0032).
             this.maybeStartPool(root);
-            // Fast map in-process (seconds, MCP stays up). Full index in a *detached*
-            // child — in-process indexAll wedges the MCP event loop on large repos,
-            // so DevEco marks the server "Connection closed" and agents fall back.
+            // Fast build in-process (seconds). Full build continues in *this* process
+            // as a background task — no sibling CLI (avoids second writer / lock fights).
+            // indexAll already yields between batches so MCP stdio can still answer
+            // tools with empty/fast/syncing guidance while the full build runs.
             void (async () => {
                 try {
                     cg.setBuildPhase('building_fast');
                     const map = cg.buildProjectMap();
                     cg.setBuildPhase('fast');
-                    process.stderr.write(`[HomeGraph MCP] Fast project map ready — modules=${map.modules.length} files=${map.files.length} (${map.durationMs}ms)\n`);
+                    process.stderr.write(`[HomeGraph MCP] Fast build ready — modules=${map.modules.length} files=${map.files.length} (${map.durationMs}ms)\n`);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
-                    process.stderr.write(`[HomeGraph MCP] Fast project map failed: ${msg}\n`);
+                    process.stderr.write(`[HomeGraph MCP] Fast build failed: ${msg}\n`);
                 }
-                this.startDetachedFullIndex(cg, root);
+                this.startBackgroundFullBuild(cg);
             })();
             return true;
         }
         catch (err) {
             // Concurrent init from another process — treat as success path via open.
-            if ((0, directory_1.isInitialized)(root)) {
-                process.stderr.write(`[HomeGraph MCP] Auto-init raced; opening existing index at ${root}\n`);
-                try {
-                    const mode = (0, graph_sources_1.resolveGraphSources)();
-                    if (!(0, graph_sources_1.graphSourceFlags)(mode).openProjectDb)
-                        return false;
-                    this.cg = await loadHomeGraph().open(root, { sources: mode });
-                    this.projectPath = root;
-                    this.toolHandler.setDefaultHomeGraph(this.cg);
-                    this.healBuildPhase(this.cg);
-                    this.startWatching();
-                    this.catchUpSync();
-                    this.maybeStartPool(root);
-                    return true;
-                }
-                catch (openErr) {
-                    const msg = openErr instanceof Error ? openErr.message : String(openErr);
-                    process.stderr.write(`[HomeGraph MCP] Auto-init open-after-race failed: ${msg}\n`);
-                    return false;
-                }
+            if (await this.openAfterAutoInitRace(root)) {
+                return true;
             }
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Auto-init failed: ${msg}\n`);
             return false;
         }
     }
+    /**
+     * Open an index another process just created (Spec 0032 cold-start race).
+     * Brief retries cover the window between mkdir and db file create.
+     */
+    async openAfterAutoInitRace(root) {
+        const mode = (0, graph_sources_1.resolveGraphSources)();
+        if (!(0, graph_sources_1.graphSourceFlags)(mode).openProjectDb)
+            return false;
+        for (let i = 0; i < 25; i++) {
+            if (!(0, directory_1.isInitialized)(root)) {
+                await new Promise((r) => setTimeout(r, 40));
+                continue;
+            }
+            try {
+                process.stderr.write(`[HomeGraph MCP] Auto-init raced; opening existing index at ${root}\n`);
+                this.cg = await loadHomeGraph().open(root, { sources: mode });
+                this.projectPath = root;
+                this.toolHandler.setDefaultHomeGraph(this.cg);
+                this.healBuildPhase(this.cg);
+                this.startWatching();
+                this.catchUpSync();
+                this.maybeStartPool(root);
+                return true;
+            }
+            catch (openErr) {
+                const msg = openErr instanceof Error ? openErr.message : String(openErr);
+                process.stderr.write(`[HomeGraph MCP] Auto-init open-after-race retry: ${msg}\n`);
+                await new Promise((r) => setTimeout(r, 40));
+            }
+        }
+        return false;
+    }
     /**
      * If a previous auto-init child finished indexing but never flipped
      * build_phase (MCP died mid-flight), heal so deep tools unlock.
@@ -355,10 +374,18 @@ class MCPEngine {
                 process.stderr.write(`[HomeGraph MCP] Healed build_phase → full (index_state=${state})\n`);
                 return;
             }
-            // Index finished enough to have symbols but metadata stuck on indexing.
-            if ((phase === 'indexing' || phase === 'fast') && cg.getStats().nodeCount > 0 && state !== 'indexing') {
+            // Symbols present after a full-build attempt — unlock deep tools even if
+            // metadata stayed on indexing/fast (crash mid-flight or soft fail).
+            let nodes = 0;
+            try {
+                nodes = cg.getStats().nodeCount;
+            }
+            catch {
+                return;
+            }
+            if (nodes > 0 && state !== 'failed' && (phase === 'indexing' || phase === 'fast')) {
                 cg.setBuildPhase('full');
-                process.stderr.write(`[HomeGraph MCP] Healed build_phase → full (nodes present, index_state=${state ?? 'null'})\n`);
+                process.stderr.write(`[HomeGraph MCP] Healed build_phase → full (nodes=${nodes}, index_state=${state ?? 'null'})\n`);
             }
         }
         catch {
@@ -366,88 +393,68 @@ class MCPEngine {
         }
     }
     /**
-     * Run `homegraph index` in a detached sibling process so the MCP stdio
-     * server stays responsive (fast map + homegraph_project keep working).
+     * Full symbol build in this MCP/daemon process (Spec 0032).
+     * Fire-and-forget: MCP tools keep answering with empty/fast/syncing while
+     * indexAll yields between batches. One writer — no sibling CLI process.
      */
-    startDetachedFullIndex(cg, root) {
-        cg.setBuildPhase('indexing');
-        const scriptPath = process.argv[1];
-        if (!scriptPath) {
-            process.stderr.write('[HomeGraph MCP] No script path — falling back to in-process indexAll\n');
-            this.startInProcessFullIndex(cg);
-            return;
-        }
-        const args = [...process.execArgv, scriptPath, 'index', root];
-        const env = { ...process.env };
-        delete env.HOMEGRAPH_AUTO_INIT;
-        process.stderr.write(`[HomeGraph MCP] Spawning background full index (detached) for ${root}\n`);
-        try {
-            const child = (0, child_process_1.spawn)(process.execPath, args, {
-                detached: true,
-                stdio: 'ignore',
-                windowsHide: true,
-                env,
-            });
-            child.on('error', (err) => {
-                process.stderr.write(`[HomeGraph MCP] Detached index spawn error: ${err.message}; falling back in-process\n`);
-                this.startInProcessFullIndex(cg);
-            });
-            child.unref();
-            this.watchIndexCompletion(cg);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`[HomeGraph MCP] Detached index spawn failed (${msg}); falling back in-process\n`);
-            this.startInProcessFullIndex(cg);
-        }
-    }
-    startInProcessFullIndex(cg) {
+    startBackgroundFullBuild(cg) {
         cg.setBuildPhase('indexing');
+        process.stderr.write('[HomeGraph MCP] Full build starting in-process (background)\n');
         void cg
             .indexAll()
             .then((result) => {
-            cg.setBuildPhase('full');
             const files = result && typeof result === 'object' && 'filesIndexed' in result
-                ? String(result.filesIndexed)
-                : '?';
-            process.stderr.write(`[HomeGraph MCP] Auto-init index complete — files=${files}\n`);
-        })
-            .catch((err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`[HomeGraph MCP] Auto-init index failed: ${msg}\n`);
+                ? Number(result.filesIndexed ?? 0)
+                : 0;
+            const ok = !result || result.success !== false;
+            let nodes = 0;
             try {
-                cg.setBuildPhase('fast');
+                nodes = cg.getStats().nodeCount;
             }
             catch {
-                /* ignore */
+                /* busy */
             }
-        });
-    }
-    watchIndexCompletion(cg) {
-        const started = Date.now();
-        const maxMs = 3 * 60 * 60 * 1000;
-        const timer = setInterval(() => {
+            // Prefer symbols on disk over a soft failure flag — agents must unlock
+            // deep tools once a usable graph exists.
+            if (ok || nodes > 0 || files > 0) {
+                cg.setBuildPhase('full');
+                process.stderr.write(`[HomeGraph MCP] Full build complete — files=${files || '?'} nodes=${nodes}` +
+                    (ok ? '\n' : ' (soft-fail but symbols present)\n'));
+            }
+            else {
+                cg.setBuildPhase('fast');
+                process.stderr.write('[HomeGraph MCP] Full build finished with no symbols — staying on fast map\n');
+            }
+            this.startWatchingAfterAutoInit();
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[HomeGraph MCP] Full build failed: ${msg}\n`);
             try {
-                const state = cg.getQueryBuilder().getMetadata('index_state');
-                if (state === 'complete' || state === 'partial') {
-                    cg.setBuildPhase('full');
-                    clearInterval(timer);
-                    process.stderr.write(`[HomeGraph MCP] Auto-init index complete — index_state=${state}\n`);
-                    return;
+                let nodes = 0;
+                try {
+                    nodes = cg.getStats().nodeCount;
                 }
-                if (state === 'failed') {
-                    cg.setBuildPhase('fast');
-                    clearInterval(timer);
-                    process.stderr.write('[HomeGraph MCP] Auto-init index failed — index_state=failed\n');
-                    return;
+                catch {
+                    /* ignore */
+                }
+                cg.setBuildPhase(nodes > 0 ? 'full' : 'fast');
+                if (nodes > 0) {
+                    process.stderr.write(`[HomeGraph MCP] Full build error after symbols written — phase=full (nodes=${nodes})\n`);
                 }
             }
             catch {
-                /* lock / transient */
+                /* ignore */
             }
-            if (Date.now() - started > maxMs)
-                clearInterval(timer);
-        }, 2000);
+            this.startWatchingAfterAutoInit();
+        });
+    }
+    /** Enable watch + catch-up once auto-init full build is done (or gave up). */
+    startWatchingAfterAutoInit() {
+        if (this.watcherStarted)
+            return;
+        this.startWatching();
+        this.catchUpSync();
     }
     /**
      * Start file watching on the active HomeGraph instance. Idempotent — the

package/dist/mcp/index-availability.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Product-facing index availability for MCP tool results (Spec 0032).
+ *
+ * Internal `build_phase` stays as-is; this layer maps it (+ write-lock / busy)
+ * to the four states hosts and agents should see in tool text.
+ */
+import type HomeGraph from '../index';
+/** Agent-visible index readiness (tool return copy — not tools/list gating). */
+export type ProductIndexState = 'empty' | 'fast' | 'full' | 'syncing';
+export declare function productIndexGuidance(state: Exclude<ProductIndexState, 'full'>): string;
+/**
+ * Resolve the product state from a live HomeGraph handle.
+ *
+ * - empty: fast map not ready (`none` / `building_fast`)
+ * - fast: map ready, full index not done (`fast` / `indexing`)
+ * - full: symbol index ready
+ * - syncing: full (or empty-while-contended-init) and a writer holds the lock /
+ *   this process is indexing — reads may fail or see a moving target
+ */
+export declare function resolveProductIndexState(cg: HomeGraph): ProductIndexState;
+/** True when an error message indicates SQLite writer contention. */
+export declare function isSqliteBusyMessage(message: string): boolean;
+//# sourceMappingURL=index-availability.d.ts.map

package/dist/mcp/index-availability.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Product-facing index availability for MCP tool results (Spec 0032).
+ *
+ * Internal `build_phase` stays as-is; this layer maps it (+ write-lock / busy)
+ * to the four states hosts and agents should see in tool text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.productIndexGuidance = productIndexGuidance;
+exports.resolveProductIndexState = resolveProductIndexState;
+exports.isSqliteBusyMessage = isSqliteBusyMessage;
+const EMPTY_LINES = [
+    'HomeGraph status=empty — project map is not ready yet.',
+    'Retry in a few seconds (or call `homegraph_project` once the fast build completes).',
+];
+const FAST_LINES = [
+    'HomeGraph status=fast — module/file map is ready; full symbol index is still building.',
+    'Use `homegraph_project` for the module/file map now, then retry this tool once indexing finishes.',
+];
+const SYNCING_LINES = [
+    'HomeGraph status=syncing — the index is being written (lock held or local index/sync in progress).',
+    'Retry this tool shortly; do not busy-loop.',
+];
+function productIndexGuidance(state) {
+    switch (state) {
+        case 'empty':
+            return EMPTY_LINES.join('\n');
+        case 'fast':
+            return FAST_LINES.join('\n');
+        case 'syncing':
+            return SYNCING_LINES.join('\n');
+    }
+}
+/**
+ * Resolve the product state from a live HomeGraph handle.
+ *
+ * - empty: fast map not ready (`none` / `building_fast`)
+ * - fast: map ready, full index not done (`fast` / `indexing`)
+ * - full: symbol index ready
+ * - syncing: full (or empty-while-contended-init) and a writer holds the lock /
+ *   this process is indexing — reads may fail or see a moving target
+ */
+function resolveProductIndexState(cg) {
+    let phase;
+    try {
+        phase = cg.getBuildPhase();
+    }
+    catch {
+        return 'syncing';
+    }
+    if (phase === 'building_fast' || phase === 'none') {
+        try {
+            if (cg.isWriteLockedByOther())
+                return 'syncing';
+        }
+        catch {
+            return 'syncing';
+        }
+        return 'empty';
+    }
+    if (phase === 'fast' || phase === 'indexing') {
+        return 'fast';
+    }
+    // full
+    try {
+        if (cg.isWriteLockedByOther() || cg.isIndexing())
+            return 'syncing';
+    }
+    catch {
+        return 'syncing';
+    }
+    return 'full';
+}
+/** True when an error message indicates SQLite writer contention. */
+function isSqliteBusyMessage(message) {
+    return /SQLITE_BUSY|database is locked/i.test(message);
+}
+//# sourceMappingURL=index-availability.js.map

package/dist/mcp/index.js

@@ -142,8 +142,9 @@ function daemonInternalSet() {
  * fail to share the daemon.
  */
 function resolveDaemonRoot(explicitPath) {
-    const candidate = explicitPath ?? process.cwd();
-    const root = (0, directory_1.findNearestHomeGraphRoot)(candidate);
+    // An explicit host path is also the walk-up floor (spec 0028): a stray
+    // ancestor .homegraph must not redirect the daemon to the wrong tree.
+    const root = (0, directory_1.findNearestHomeGraphRoot)(explicitPath ?? process.cwd(), explicitPath ?? undefined);
     if (!root)
         return null;
     try {
@@ -349,7 +350,7 @@ class MCPServer {
         // 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.
         // Soft deadlines + compact-before-pool still run on the warm main connection.
-        this.engine = new engine_1.MCPEngine({ queryPool: false });
+        this.engine = new engine_1.MCPEngine({ queryPool: false, rootFloor: this.projectPath ?? undefined });
         const transport = new transport_1.StdioTransport();
         this.session = new session_1.MCPSession(transport, this.engine, {
             explicitProjectPath: this.projectPath,
@@ -471,7 +472,7 @@ class MCPServer {
             getDaemonSocket,
             // Daemon-unavailable fallback is one client — same as direct mode: no
             // pool. Duplicating the DB open here blew RSS on large indexes.
-            makeEngine: () => new engine_1.MCPEngine({ queryPool: false }),
+            makeEngine: () => new engine_1.MCPEngine({ queryPool: false, rootFloor: root ?? undefined }),
             root,
         });
     }

package/dist/mcp/query-cache.d.ts

@@ -15,7 +15,7 @@
 import type { QueryBuilder } from '../db/queries';
 import type { ToolResult } from './tools';
 /** Bump when cache-key normalization or cached payload shape changes. */
-export declare const QUERY_CACHE_FORMAT_VERSION = 3;
+export declare const QUERY_CACHE_FORMAT_VERSION = 5;
 export declare function isMcpQueryCacheEnabled(): boolean;
 export declare function isCacheableMcpTool(toolName: string): boolean;
 /**

package/dist/mcp/query-cache.js

@@ -35,7 +35,7 @@ function defaultExploreMaxFiles(fileCount) {
     return 8;
 }
 /** Bump when cache-key normalization or cached payload shape changes. */
-exports.QUERY_CACHE_FORMAT_VERSION = 3;
+exports.QUERY_CACHE_FORMAT_VERSION = 5;
 const METADATA_INDEX_STAMP = 'query_cache_index_stamp';
 const METADATA_FORMAT_VERSION = 'query_cache_format_version';
 /** Tools that must stay live — never cached. */
@@ -144,7 +144,9 @@ function exploreEnvFingerprint() {
         : '1';
     const rankMultiterm = process.env.HOMEGRAPH_RANK_NO_MULTITERM === '1' ? '0' : '1';
     const fullSource = process.env.HOMEGRAPH_EXPLORE_FULL_SOURCE === '1' ? '1' : '0';
-    return `linums:${linums}|adaptive:${adaptive}|rankMultiterm:${rankMultiterm}|fullSource:${fullSource}`;
+    const evidencePacks = process.env.HOMEGRAPH_ARKTS_EVIDENCE_PACKS === '0' ? '0' : '1';
+    const queryPaths = process.env.HOMEGRAPH_ARKTS_QUERY_PATHS === '0' ? '0' : '1';
+    return `linums:${linums}|adaptive:${adaptive}|rankMultiterm:${rankMultiterm}|fullSource:${fullSource}|arktsEvidence:${evidencePacks}|arktsPaths:${queryPaths}`;
 }
 function normalizeString(value) {
     if (typeof value !== 'string')
@@ -256,6 +258,8 @@ function buildMcpQueryCacheFingerprint(toolName, args, fileCount) {
         }
         case 'homegraph_search': {
             parts.push(`query:${(normalizeString(args.query) ?? '').toLowerCase()}`);
+            // Search can reuse the compact ArkTS renderer as an existing fast path.
+            parts.push(exploreEnvFingerprint());
             if (args.kind != null) {
                 const kind = args.kind === 'type' ? 'type_alias' : String(args.kind);
                 parts.push(`kind:${kind}`);

package/dist/mcp/query-worker.d.ts

@@ -2,7 +2,7 @@
  * Query worker thread — issue: concurrent MCP tool calls starve the daemon.
  *
  * The shared daemon serves every session on ONE event loop with synchronous
- * SQLite (better-sqlite3 / wasm). `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
+ * SQLite (node:sqlite / wasm). `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
  * PageRank + impact + output building) stitched together by microtask `await`s,
  * so N concurrent explores keep the microtask queue continuously full and
  * starve the macrotask phases — timers AND socket I/O. The transport freezes:

package/dist/mcp/query-worker.js

@@ -3,7 +3,7 @@
  * Query worker thread — issue: concurrent MCP tool calls starve the daemon.
  *
  * The shared daemon serves every session on ONE event loop with synchronous
- * SQLite (better-sqlite3 / wasm). `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
+ * SQLite (node:sqlite / wasm). `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
  * PageRank + impact + output building) stitched together by microtask `await`s,
  * so N concurrent explores keep the microtask queue continuously full and
  * starve the macrotask phases — timers AND socket I/O. The transport freezes:

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

@@ -1,12 +1,7 @@
 /**
- * Server-level instructions emitted in the MCP `initialize` response.
- *
- * Single source of truth for agent-facing tool guidance (issue #529).
- * Edit here — not installer prompts or eval harness prompts.
- *
- * Keep this short: long essays are low-salience and rarely change tool choice.
- * Prefer concrete habits (query shape, which tool, when to stop).
+ * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
+ * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
  */
-export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 structural locator for THIS repo\n\nLocal symbol graph (defs / calls / imports / files). Use it to locate in-repo symbols (`file:line` + source), then continue the user's requested explanation, edits and validation. Retrieval completion is not task completion.\n\n## When to call (path-first): choose exactly ONE first tool\n\n- User task already names an in-repo relative path to one source file and requests a code change \u2192 Read that file and edit (Skip HomeGraph).\n- Otherwise, use the narrow tool or explore below to locate the missing source evidence.\n\nUse the narrow tool when the task is exactly one of these inventories:\n\n- **Where is this named API/member/constant/field used?** \u2192 `homegraph_usages`\n- **How do these named modules depend on each other / is there a cycle?** \u2192 `homegraph_modules`\n- **Which NAPI/native exports or registration sites does this named path/Type expose?** \u2192 `homegraph_native`\n\nOtherwise, if you will **explain or edit in-repo code**, call `homegraph_explore` **once** with the user task as `query` (Chinese OK; add English Type / `Type.member` / `@kit` / `@ohos` tokens when known). Do not call explore after a focused tool already answered the inventory. Older clients that call explore still get the same focused handler through conservative compatibility routing.\n\nEngineering overview / module\u2192file map (including while the full index is still building) \u2192 `homegraph_project`.\n\nAlready know **one** exact symbol body or call direction? Prefer `homegraph_callers` / `homegraph_callees` / `homegraph_node`. Spelling unknown \u2192 `homegraph_search` last.\n\n**Prefer explore when locating (without a path-pinned single-file edit):** how/mechanism wiring, cross-Type/component behavior, `.d.ts` wrap flows, and general pre-edit orientation that is not one of the three narrow inventories above.\n\nArkUI V1\u2194V2 / state-decorator migration on a named component \u2192 `homegraph_arkui_migrate` once (not explore stitching).\n\n## How to write `query`\n\n- Preserve the task's intent, relation direction and scope; do not stuff keywords or invent symbols. For edits, include the requested action, target product/module, exclusions and acceptance requirements in query or optional taskContext. Do not replace a deletion/refactoring request with a bare component name. When optional query planning is enabled, explore can plan bounded dependent lookups internally; scoped natural-language queries can be planned even when a lexical route matches, while exact symbol/path lookups stay cheap. No extra tool or explicit depth tier is required. Planned subquestion evidence is not a completeness claim for the whole task.\n- Planned steps keep separate retrieval focuses. Located source candidates carry file/line identity, not proof that the intended business feature is correct; check them against the original task constraints before editing. A missing dependency is reported as unexecuted, not as evidence that the code does not exist.\n- Before editing, verify that the evidence belongs to the requested product/module and that referenced symbols actually exist. A project map is only navigation, not proof that a feature has been located. If source evidence is ambiguous or belongs to another product, use a bounded follow-up instead of editing that hit. Read-duplication guidance never forbids checks needed to avoid an incorrect edit.\n- Put **concrete anchors** in the bag: `FooManager`, `BarEvent`, `Type.member`, `feature/foo`, `path/to/File.ets`, `@kit.X`.\n- Map Chinese entities to English symbol stems when you can (`\u8BBE\u7F6E`\u2192`Setting`, `\u65B0\u5EFA`\u2192`New`) \u2014 search/explore cluster `Entity` / `EntityManager` / `EntityViewModel`.\n- Keep **intent words** with the Type (`\u6765\u6E90` / `\u5206\u53D1` / `\u4F9D\u8D56` / `NAPI` / `\u9A71\u52A8`) \u2014 bare Type alone may drop survey routing.\n- Multi-app monorepo: pass `projectPath` to the app root; ignore sibling-app paths as noise.\n\n## After one explore\n\n- Digests concern named / hit files; unrelated neighboring pages are not required reading.\n\n- Reuse returned line-numbered source for the ranges actually shown. An outline, anchor, candidate list, truncated body or SDK declaration is not a substitute for missing business code.\n- Check source relevance and every requested change before editing. A retrieval status or completion banner never authorizes ending a coding task or skipping implementation and validation.\n- Empty, SDK-only or partial evidence \u2192 **one** bounded recovery aimed at the missing evidence. The suggested **Next anchor** is advisory; a newly scoped obligation may need another file or Type. One focused `homegraph_node`, `homegraph_callers` or `homegraph_callees` can recover a missing body or relation.\n- If evidence is still missing after the retrieval budget, inspect it with targeted Read/Grep and continue the requested work. Do not infer that the feature is absent or that the task is complete.\n- Busy/deadline \u2192 retry **once** tighter; then inspect the missing source directly.\n\nPrefer the smallest tool when the name is known and reuse unchanged evidence. Session budget: **\u22642** `homegraph_explore` attempts per project, including empty responses; **\u22641** focused depth recovery after incomplete evidence. Identical requests with usable evidence may be deduplicated; lexical overlap alone does not prove a new obligation was answered.\n\n## Do not call HomeGraph\n\nRuntime Skip is a short blacklist (everything else is served if you call):\n\n- Single-file path pinned in a code-change task \u2192 Read + edit (Skip HomeGraph)\n\n- Topic \u2192 file list with no Type/file basename\n- Pure layout-copy or media hunts with no code behavior to locate\n- Pure existence / concept-compare with no graph anchors\n- Official website/docs only \u00B7 scaffold empty project \u00B7 git/blame/diff \u00B7 media/binary inventories\n\n`@kit` / OHOS **API usage in this repo** is not Skip: exact where-used \u2192 `homegraph_usages`; mechanism/API-symbol flow \u2192 `homegraph_explore`. Feature **catalogs** of an SDK \u2192 SDK docs, not HomeGraph.\n\nFor UI behavior, preserve the verbatim label in the query: resource strings may lead to their source references, event handler and route. If a tool reports unsupported scope or an exhausted budget, use targeted built-ins for the missing evidence and continue the user's task.\n\n## Tips\n\n- Empty callers/callees = **edges not indexed**, not \u201Cmissing symbol\u201D \u2014 use the definition anchor; narrow Grep for registration if needed.\n- **Staleness banner** \u2014 refresh the listed changed source before relying on it.\n- **Not indexed** \u2014 use built-ins; user runs `homegraph init` (you do not).\n";
-export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 per-project (pass projectPath)\n\nPass `projectPath` to a folder that has `.homegraph/`.\n\n**When to call (path-first):** a single-file path-pinned edit \u2192 Read + edit (Skip HomeGraph). Otherwise choose exactly one first tool: named where-used \u2192 `homegraph_usages`; named module deps/cycles \u2192 `homegraph_modules`; named NAPI/native exports \u2192 `homegraph_native`; every other in-repo explanation/edit \u2192 `homegraph_explore`. Pass the same `projectPath`. Do not call explore after a focused inventory already answered.\n\n**Skip:** path-pinned single-file edits, topic file-lists, concept compares, git history, media. No index \u2192 Read/Grep/Glob; user runs `homegraph init`.\n\n**Query habit:** Chinese OK; keep UI labels verbatim and add English Type/`@kit` tokens only when known. Preserve requested edits and scope. Empty/SDK-only/partial evidence permits one focused recovery, then targeted source inspection. Retrieval completion is not task completion: continue the requested edits and validation.\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- 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\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\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