homegraph 1.5.10 → 1.6.0

package/CHANGELOG.md

@@ -10,6 +10,23 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 
+## [1.6.0] - 2026-09-23
+
+### Improvements
+
+- MCP auto-init (Spec 0049): empty workspace roots no longer create `.homegraph/` on `--auto-init` / `HOMEGRAPH_AUTO_INIT` (fixes DevEco in-place `devecocli create` hitting `PROJECT_EXISTS` because only an index dir existed). A 60s probe (`HOMEGRAPH_DEFER_PROBE_MS`; `0` = tool-kick only) and the first `homegraph_*` call re-check `isIndexableRoot` (root `build-profile.json5` or any indexable source); once non-empty, the existing fast-map + background full index path runs once. Status footers stay the product empty/fast/full/dirty/syncing lines. Lifecycle logging no longer mkdir's `.homegraph/` just to write `daemon.log`.
+- Harmony locate seams (Spec 0048): index `form_config.json` / `shortcuts_config.json` (plus module.json5 form extensionAbilities and shortcuts/form metadata) as searchable capability nodes — explore may lead with **Capability profiles**, or an explicit no-in-repo form note instead of SDK `.d.ts`. Resource hits can append in-repo `$r('app.string.<key>')` **bound** `.ets` anchors. `homegraph_project` adds a **Module roster** (oh-package + local `file:` deps) and lists capability profile paths separately from rawfile. Explore may prepend **Seam notes** for nearby profiles and empty/log-only stubs.
+- MCP product lifecycle (Spec 0047): main-thread liveness watchdog is **off by default** (enable with `HOMEGRAPH_WATCHDOG=1`; `HOMEGRAPH_NO_WATCHDOG=1` still forces off) so concurrent DevEco init no longer gets false "Main thread unresponsive" kills — file watch / incremental sync unchanged. Shared daemon idle linger defaults to **60s** after the last client disconnects; if auto-init/full index is still in `building_fast`/`indexing`, idle exit waits until that build settles, then starts the 60s linger. While any client is connected the daemon never idle-exits.
+- MCP runtime log (Spec 0046): always-on coarse lifecycle lines (`mcp.start` / `mcp.initialize` / `auto-init.*` / `index.*` / `watcher.degraded`) go to stderr and `.homegraph/daemon.log` (same file daemon stdio already uses); soft-rotate at ~5 MiB to `daemon.log.1`. Set `HOMEGRAPH_DEBUG=1` for per-tool summaries (`tool.<name>` with duration / error / truncated query). No new `logs/` directory; default is not a full request ledger.
+- ArkUI index-time edge synthesis (Spec 0045): `build` / `@Builder` bodies that call another in-repo `@Component` / `@Builder` gain `arkui-child` edges (ambiguous names dropped); literal `pushPathByName` / `replacePathByName` / `pushNamedRoute({ name })` link to indexed `route` nodes as `arkui-named-nav`. Complements existing `arkui-route` (`pushUrl`) and Spec 0039 route_map edges — no query-time synthesis.
+- Explore locate contract (Spec 0044): Chinese/UI **literal witness** files stay in the first pack and rank ahead of Logger/hilog/Toast spines unless the query names those APIs; **Located** / **Partial** / **Miss** banners (Partial next-step → `node`/`usages`/`search`, no same-name Grep); Miss omits source bodies and lists fuzzy paths; filename≠primary-declaration risk note; `homegraph_node` for symbols already on the explore locate list bypasses the Partial depth-fuse cap. Dynamic-edge synthesis (10.3) remains deferred.
+- When an MCP session already has a bound default project (`--path` / opened root), a tool `projectPath` that resolves to a **different** `.homegraph/` index root is soft-pinned: HomeGraph keeps answering from the bound root and prepends a short English notice (not `isError`). Same-root nested paths are unchanged; sessions with no default project still open cross-project indexes (Spec 0043).
+- In-repo locate for explore: `taskContext` no longer enters the lexical/FTS query string (quoted literals from it still merge); PascalCase identifiers (≥8 chars) seed exact file/symbol roots like `Foo.ets`; business-oriented queries default `sourceScope=local` so SDK `.d.ts` stubs do not become roots; MCP trails / used-by / evidence packs hide `@dummyFile` and `%AM*` noise. `homegraph_project` adds a bounded HarmonyOS **resources path inventory** (string.json / rawfile / media dir counts / on-disk modules with zero indexed sources) — paths only, no JSON bodies or edges (Spec 0042).
+- Harmony `resources/**/element/string.json` is indexed as searchable `constant` nodes (key + UI value in FTS). Explore may lead with a short **Resource hits** table and a `$r('app.string.<key>')` Grep hint — **no** graph edges to controls. Color/media/rawfile stay out of scope (Spec 0041).
+- `homegraph_project` on Harmony repos now prints a **skeleton summary**: `bundle` from `app.json5`, a note that modules come from `build-profile.json5`, per-module `route profile:` paths (`route_map` / `router_map` / `main_pages`), and `oh-package` names when present. Still no call edges or profile JSON bodies — use explore for route→page (Spec 0039) and Read to edit. Tool descriptions and MCP initialize instructions spell out project vs explore (Spec 0040).
+- Harmony `route_map.json` / `router_map.json` / `main_pages.json` are indexed (basename allowlist) and linked into the graph as `route` nodes → page / `buildFunction` symbols. Edges carry `synthesizedBy: arkts-route-map` and `registeredAt` pointing at the config file so explore/trails show the JSON wiring site. When an explore query mentions those filenames, replies lead with a short **Registration sources** table — evidence from those profiles, reducing blind re-Read of the JSON (Spec 0039).
+- MCP tool replies that know the indexed project now begin with `HomeGraph project root: \`<absolute>\`` plus a one-line join rule: repo-relative paths below that root should be passed to Read/Grep as-is (or `<root>/<relative>` with `/`), without inventing experiment/result prefixes. MCP initialize instructions mention the same join base. Indexed path storage stays repo-relative (Spec 0038).
+
 ## [1.5.10] - 2026-09-20
 
 ### Fixes
@@ -256,3 +273,4 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 [1.5.7]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.7
 [1.5.8]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.8
 [1.5.10]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.10
+[1.6.0]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.6.0

package/dist/extraction/grammars.d.ts

@@ -45,6 +45,25 @@ export declare function isErlangAppFile(filePath: string): boolean;
 export declare function isPlayRoutesFile(filePath: string): boolean;
 /** HarmonyOS module manifest — parsed by the arkts-entry framework extractor. */
 export declare function isArkModuleJson5(filePath: string): boolean;
+/**
+ * Harmony Navigation / pages profile JSON (Spec 0039) — basename allowlist only.
+ * Parsed by arkts-entry; not general `.json` indexing.
+ */
+export declare function isHarmonyRouteProfileJson(filePath: string): boolean;
+/**
+ * Harmony element string resources (Spec 0041) — path allowlist only.
+ * `…/resources/…/element/string.json` (not bare string.json, not color/media).
+ * Indexed as yaml file-level + arkts-entry constants for FTS; no graph edges.
+ */
+export declare function isHarmonyElementStringJson(filePath: string): boolean;
+/**
+ * Harmony capability profiles (Spec 0048) — basename allowlist only.
+ * `form_config.json` (service widgets) and `shortcuts_config.json` (home-screen shortcuts).
+ * Indexed as yaml + arkts-entry constants; no UI call edges.
+ */
+export declare function isHarmonyCapabilityProfileJson(filePath: string): boolean;
+/** Config files that host ArkTS `route` nodes (module manifest + Spec 0039 profiles). */
+export declare function isHarmonyRouteConfigFile(filePath: string): boolean;
 /**
  * Initialize the tree-sitter WASM runtime. Must be called before loading grammars.
  * Does NOT load any grammar WASM files — use loadGrammarsForLanguages() for that.

package/dist/extraction/grammars.js

@@ -46,6 +46,10 @@ exports.isShopifyLiquidJson = isShopifyLiquidJson;
 exports.isErlangAppFile = isErlangAppFile;
 exports.isPlayRoutesFile = isPlayRoutesFile;
 exports.isArkModuleJson5 = isArkModuleJson5;
+exports.isHarmonyRouteProfileJson = isHarmonyRouteProfileJson;
+exports.isHarmonyElementStringJson = isHarmonyElementStringJson;
+exports.isHarmonyCapabilityProfileJson = isHarmonyCapabilityProfileJson;
+exports.isHarmonyRouteConfigFile = isHarmonyRouteConfigFile;
 exports.initGrammars = initGrammars;
 exports.vendoredWasmFilenames = vendoredWasmFilenames;
 exports.readGrammarWasmBytes = readGrammarWasmBytes;
@@ -235,6 +239,12 @@ function isSourceFile(filePath, overrides) {
         return true; // Play `conf/routes` is extensionless
     if (isArkModuleJson5(filePath))
         return true;
+    if (isHarmonyRouteProfileJson(filePath))
+        return true; // Spec 0039
+    if (isHarmonyElementStringJson(filePath))
+        return true; // Spec 0041
+    if (isHarmonyCapabilityProfileJson(filePath))
+        return true; // Spec 0048
     if (isShopifyLiquidJson(filePath))
         return true; // Shopify OS 2.0 JSON templates / section groups
     if (isErlangAppFile(filePath))
@@ -280,6 +290,35 @@ function isPlayRoutesFile(filePath) {
 function isArkModuleJson5(filePath) {
     return filePath.endsWith('module.json5');
 }
+/**
+ * Harmony Navigation / pages profile JSON (Spec 0039) — basename allowlist only.
+ * Parsed by arkts-entry; not general `.json` indexing.
+ */
+function isHarmonyRouteProfileJson(filePath) {
+    const base = filePath.replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+    return base === 'route_map.json' || base === 'router_map.json' || base === 'main_pages.json';
+}
+/**
+ * Harmony element string resources (Spec 0041) — path allowlist only.
+ * `…/resources/…/element/string.json` (not bare string.json, not color/media).
+ * Indexed as yaml file-level + arkts-entry constants for FTS; no graph edges.
+ */
+function isHarmonyElementStringJson(filePath) {
+    return /(?:^|\/)resources\/(?:[^/]+\/)*element\/string\.json$/i.test(filePath.replace(/\\/g, '/'));
+}
+/**
+ * Harmony capability profiles (Spec 0048) — basename allowlist only.
+ * `form_config.json` (service widgets) and `shortcuts_config.json` (home-screen shortcuts).
+ * Indexed as yaml + arkts-entry constants; no UI call edges.
+ */
+function isHarmonyCapabilityProfileJson(filePath) {
+    const base = filePath.replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+    return base === 'form_config.json' || base === 'shortcuts_config.json';
+}
+/** Config files that host ArkTS `route` nodes (module manifest + Spec 0039 profiles). */
+function isHarmonyRouteConfigFile(filePath) {
+    return isArkModuleJson5(filePath) || isHarmonyRouteProfileJson(filePath);
+}
 /**
  * Caches for loaded grammars and parsers
  */
@@ -450,8 +489,12 @@ function detectLanguage(filePath, source, overrides) {
         return 'yaml';
     if (isArkModuleJson5(filePath))
         return 'yaml';
-    if (isArkModuleJson5(filePath))
+    if (isHarmonyRouteProfileJson(filePath))
         return 'yaml';
+    if (isHarmonyElementStringJson(filePath))
+        return 'yaml'; // Spec 0041
+    if (isHarmonyCapabilityProfileJson(filePath))
+        return 'yaml'; // Spec 0048
     const ext = filePath.substring(filePath.lastIndexOf('.')).toLowerCase();
     // Shopify OS 2.0 JSON templates / section groups → the Liquid extractor (it
     // links each section `"type"` to its `sections/<type>.liquid`).

package/dist/mcp/arkts-evidence-packs.js

@@ -18,6 +18,7 @@ const local = (n) => !n.filePath.startsWith('ohos-sdk:') && !/\.d\.(?:ts|ets)$/i
 // ArkAnalyzer's virtual entry/implicit constructor has no declaration on disk.
 // Explicit constructors with a real range remain available through the normal renderer.
 const artifact = (n) => n.filePath.includes('@dummy') || n.name.startsWith('@dummy')
+    || /^%AM\d+/i.test(n.name)
     || (n.name === 'constructor' && n.startLine === 1 && n.endLine === 1);
 /** Consume already-located nodes. No text search, new planner call or recursive retrieval. */
 function buildArktsEvidencePacks(graph, options) {

package/dist/mcp/daemon.d.ts

@@ -20,9 +20,12 @@
  *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
  *     close then decrements the daemon's refcount.
  *   - When the last client disconnects the daemon lingers for
- *     `HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
- *     runs in the same project don't repay startup, then exits cleanly. This is
- *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *     `HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default **60s**, Spec 0047) so a
+ *     quick reconnect does not repay startup — but **only after** any in-flight
+ *     auto-init/full index finishes (`building_fast` / `indexing`). While a
+ *     client is connected (refcount > 0) the daemon never idle-exits. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277)
+ *     without killing a half-built graph when the IDE just closed.
  *
  * What this file owns:
  *   - Listening on the daemon socket and spawning per-connection sessions.
@@ -41,6 +44,21 @@
  */
 import * as net from 'net';
 import { DaemonLockInfo } from './daemon-paths';
+/**
+ * Spec 0047: phases that block daemon idle-exit when clients=0.
+ * Routine watch/sync is NOT included.
+ */
+export declare function isBuildPhaseBlockingIdle(phase: string | null | undefined): boolean;
+/**
+ * Decide idle-timer action when the linger timer fires (refcount already 0).
+ * Pure helper for unit tests.
+ */
+export declare function decideIdleExitAction(opts: {
+    clientCount: number;
+    buildBlocking: boolean;
+}): 'exit' | 'rearm-idle' | 'poll-build';
+/** Default idle linger after last client (exported for tests). */
+export declare function defaultDaemonIdleTimeoutMs(): number;
 /**
  * Finalize daemon shutdown. On POSIX, exit immediately — it's clean and fast.
  * On Windows, do NOT force an exit while watchers may still be closing (that

package/dist/mcp/daemon.js

@@ -21,9 +21,12 @@
  *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
  *     close then decrements the daemon's refcount.
  *   - When the last client disconnects the daemon lingers for
- *     `HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
- *     runs in the same project don't repay startup, then exits cleanly. This is
- *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *     `HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default **60s**, Spec 0047) so a
+ *     quick reconnect does not repay startup — but **only after** any in-flight
+ *     auto-init/full index finishes (`building_fast` / `indexing`). While a
+ *     client is connected (refcount > 0) the daemon never idle-exits. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277)
+ *     without killing a half-built graph when the IDE just closed.
  *
  * What this file owns:
  *   - Listening on the daemon socket and spawning per-connection sessions.
@@ -75,6 +78,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_HELLO_LINE_BYTES = exports.Daemon = void 0;
+exports.isBuildPhaseBlockingIdle = isBuildPhaseBlockingIdle;
+exports.decideIdleExitAction = decideIdleExitAction;
+exports.defaultDaemonIdleTimeoutMs = defaultDaemonIdleTimeoutMs;
 exports.finalizeDaemonExit = finalizeDaemonExit;
 exports.tryAcquireDaemonLock = tryAcquireDaemonLock;
 exports.acquireLockViaExclusiveOpen = acquireLockViaExclusiveOpen;
@@ -92,8 +98,32 @@ const transport_1 = require("./transport");
 const daemon_paths_1 = require("./daemon-paths");
 const version_1 = require("./version");
 const daemon_registry_1 = require("./daemon-registry");
-/** Default idle linger after the last client disconnects. */
-const DEFAULT_IDLE_TIMEOUT_MS = 300_000;
+/** How often to re-check build phase while deferring idle exit (Spec 0047). */
+const BUILD_IDLE_POLL_MS = 2_000;
+/** Default idle linger after the last client disconnects (Spec 0047: 60s). */
+const DEFAULT_IDLE_TIMEOUT_MS = 60_000;
+/**
+ * Spec 0047: phases that block daemon idle-exit when clients=0.
+ * Routine watch/sync is NOT included.
+ */
+function isBuildPhaseBlockingIdle(phase) {
+    return phase === 'building_fast' || phase === 'indexing';
+}
+/**
+ * Decide idle-timer action when the linger timer fires (refcount already 0).
+ * Pure helper for unit tests.
+ */
+function decideIdleExitAction(opts) {
+    if (opts.clientCount > 0)
+        return 'rearm-idle';
+    if (opts.buildBlocking)
+        return 'poll-build';
+    return 'exit';
+}
+/** Default idle linger after last client (exported for tests). */
+function defaultDaemonIdleTimeoutMs() {
+    return DEFAULT_IDLE_TIMEOUT_MS;
+}
 /**
  * Hard ceiling on how long the daemon stays up with clients connected but no
  * inbound traffic. A backstop (#692): if a client's socket-close is never
@@ -372,15 +402,39 @@ class Daemon {
             return;
         if (this.idleTimeoutMs <= 0)
             return; // 0 = never idle-exit
+        // Spec 0047: if the last window closed mid-index, wait for build to finish
+        // before starting the idle linger — never exit while clients>0 either.
+        if (this.clients.size === 0 && this.engine.isIndexBuildInProgress()) {
+            this.idleTimer = setTimeout(() => {
+                this.idleTimer = null;
+                if (this.clients.size > 0)
+                    return; // reconnect disarmed the need
+                if (this.engine.isIndexBuildInProgress()) {
+                    this.armIdleTimer(); // keep polling until build settles
+                    return;
+                }
+                this.armIdleTimer(); // build done → arm full idle linger
+            }, BUILD_IDLE_POLL_MS);
+            this.idleTimer.unref?.();
+            return;
+        }
         this.idleTimer = setTimeout(() => {
             this.idleTimer = null;
             // Last-second sanity check: if a connection landed between the timer
             // firing and now, don't exit. (setImmediate-ordering is the only way
             // this races; cheap to defend against.)
-            if (this.clients.size > 0) {
+            const action = decideIdleExitAction({
+                clientCount: this.clients.size,
+                buildBlocking: this.engine.isIndexBuildInProgress(),
+            });
+            if (action === 'rearm-idle') {
                 this.armIdleTimer();
                 return;
             }
+            if (action === 'poll-build') {
+                this.armIdleTimer(); // switches to build-poll branch above
+                return;
+            }
             void this.stop('idle timeout');
         }, this.idleTimeoutMs);
         // Don't keep the event loop alive just for this — the net.Server keeps the

package/dist/mcp/engine.d.ts

@@ -48,6 +48,13 @@ export declare class MCPEngine {
     private opts;
     private closed;
     private queryPool;
+    /**
+     * Spec 0049: auto-init deferred because the root was empty. Probe until
+     * indexable, then run the normal create-DB path once.
+     */
+    private deferredAutoInitRoot;
+    private deferProbeTimer;
+    private deferAutoInitPromise;
     constructor(opts?: MCPEngineOptions);
     /**
      * Start the worker-thread query pool once a default project is open (daemon
@@ -67,8 +74,21 @@ export declare class MCPEngine {
     getProjectPath(): string | null;
     /** Shared ToolHandler — sessions delegate tool dispatch through this. */
     getToolHandler(): ToolHandler;
+    /**
+     * Spec 0047: true while auto-init / full symbol build is in flight.
+     * Used by the daemon idle timer — never idle-exit mid-build when clients=0.
+     * Does not include routine watch/sync increments.
+     */
+    isIndexBuildInProgress(): boolean;
     /** Whether the default project's HomeGraph is open. */
     hasDefaultHomeGraph(): boolean;
+    /** Spec 0049: true while auto-init is waiting for an empty root to grow sources. */
+    isAutoInitDeferred(): boolean;
+    /**
+     * Spec 0049: on tool call (or timer), re-check the deferred root and start
+     * the normal auto-init once it becomes indexable. Idempotent.
+     */
+    kickDeferredAutoInit(): Promise<boolean>;
     /**
      * Walk up from `searchFrom` to find the nearest `.homegraph/` and open it.
      * Idempotent: concurrent callers share one in-flight init; subsequent
@@ -100,6 +120,11 @@ export declare class MCPEngine {
      * @returns true if the engine is fully wired to a new (or racing) index
      */
     private tryAutoInit;
+    /** Spec 0049: create DB + fast map + background full (shared by first hit and kick). */
+    private runAutoInitCreate;
+    /** Spec 0049: remember empty root and (optionally) poll until indexable. */
+    private armDeferProbe;
+    private clearDeferProbe;
     /**
      * Open an index another process just created (Spec 0032 cold-start race).
      * Brief retries cover the window between mkdir and db file create.
@@ -143,6 +168,7 @@ export declare class MCPEngine {
  * Range: 1s … 30min. Used by product hosts (e.g. DevEco Code = 5 minutes).
  */
 export declare function parseFixedWindowEnv(raw: string | undefined): number | undefined;
+export { isIndexableRoot, parseDeferProbeMs } from './indexable-root';
 /**
  * Parse and clamp the HOMEGRAPH_WATCH_DEBOUNCE_MS env override.
  *

package/dist/mcp/engine.js

@@ -44,7 +44,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MCPEngine = void 0;
+exports.parseDeferProbeMs = exports.isIndexableRoot = exports.MCPEngine = void 0;
 exports.parseFixedWindowEnv = parseFixedWindowEnv;
 exports.parseDebounceEnv = parseDebounceEnv;
 const os = __importStar(require("os"));
@@ -57,13 +57,28 @@ const memory_budget_1 = require("./memory-budget");
 const db_1 = require("../db");
 const graph_sources_1 = require("../graph-sources");
 const utils_1 = require("../utils");
+const runtime_log_1 = require("../runtime-log");
+const indexable_root_1 = require("./indexable-root");
 // Lazy-load the heavy HomeGraph chain (sqlite + query/graph/context layers) OFF
 // the MCP startup path. It's only needed once a tool actually opens a project —
 // not to answer initialize/tools-list — so deferring it lets `serve mcp` (and
 // the daemon it spawns) bind + register tools in ~Node-startup time instead of
 // ~800ms, closing the "No such tool available" cold-start race that made headless
-// agents flounder. require() is sync + cached on the CommonJS build.
-const loadHomeGraph = () => require('../index').default;
+// agents flounder. Prefer dynamic import (vitest + CJS); sync require remains for
+// the sync retry path after an async load has warmed the cache (or under dist/).
+let homeGraphCtor = null;
+const loadHomeGraph = async () => {
+    if (!homeGraphCtor) {
+        homeGraphCtor = (await Promise.resolve().then(() => __importStar(require('../index')))).default;
+    }
+    return homeGraphCtor;
+};
+const loadHomeGraphSync = () => {
+    if (homeGraphCtor)
+        return homeGraphCtor;
+    homeGraphCtor = require('../index').default;
+    return homeGraphCtor;
+};
 /**
  * Shared MCP engine. Thread-safe in the sense that multiple sessions can
  * call its methods concurrently — internally it serializes initialization
@@ -85,6 +100,13 @@ class MCPEngine {
     // Off-loop read-tool pool (daemon mode only). Created lazily once the default
     // project is open — workers each hold their own WAL read connection.
     queryPool = null;
+    /**
+     * Spec 0049: auto-init deferred because the root was empty. Probe until
+     * indexable, then run the normal create-DB path once.
+     */
+    deferredAutoInitRoot = null;
+    deferProbeTimer = null;
+    deferAutoInitPromise = null;
     constructor(opts = {}) {
         this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false, rootFloor: opts.rootFloor ?? null };
         this.toolHandler = new tools_1.ToolHandler(null);
@@ -132,10 +154,42 @@ class MCPEngine {
     getToolHandler() {
         return this.toolHandler;
     }
+    /**
+     * Spec 0047: true while auto-init / full symbol build is in flight.
+     * Used by the daemon idle timer — never idle-exit mid-build when clients=0.
+     * Does not include routine watch/sync increments.
+     */
+    isIndexBuildInProgress() {
+        if (!this.cg)
+            return false;
+        try {
+            const phase = this.cg.getBuildPhase();
+            return phase === 'building_fast' || phase === 'indexing';
+        }
+        catch {
+            return false;
+        }
+    }
     /** Whether the default project's HomeGraph is open. */
     hasDefaultHomeGraph() {
         return this.toolHandler.hasDefaultHomeGraph();
     }
+    /** Spec 0049: true while auto-init is waiting for an empty root to grow sources. */
+    isAutoInitDeferred() {
+        return this.deferredAutoInitRoot !== null && !this.toolHandler.hasDefaultHomeGraph();
+    }
+    /**
+     * Spec 0049: on tool call (or timer), re-check the deferred root and start
+     * the normal auto-init once it becomes indexable. Idempotent.
+     */
+    async kickDeferredAutoInit() {
+        if (this.closed || this.toolHandler.hasDefaultHomeGraph())
+            return false;
+        const root = this.deferredAutoInitRoot;
+        if (!root)
+            return false;
+        return this.tryAutoInit(root);
+    }
     /**
      * Walk up from `searchFrom` to find the nearest `.homegraph/` and open it.
      * Idempotent: concurrent callers share one in-flight init; subsequent
@@ -194,7 +248,7 @@ class MCPEngine {
                 catch { /* ignore */ }
                 this.cg = null;
             }
-            this.cg = loadHomeGraph().openSync(resolvedRoot, { sources: mode });
+            this.cg = loadHomeGraphSync().openSync(resolvedRoot, { sources: mode });
             this.projectPath = resolvedRoot;
             this.toolHandler.setDefaultHomeGraph(this.cg);
             this.startWatching();
@@ -213,6 +267,7 @@ class MCPEngine {
         if (this.closed)
             return;
         this.closed = true;
+        this.clearDeferProbe();
         // Detach + terminate the worker pool first so no tool call routes to a
         // worker mid-teardown; outstanding pool calls resolve with graceful guidance.
         this.toolHandler.setQueryPool(null);
@@ -252,7 +307,7 @@ class MCPEngine {
                 process.stderr.write(`[HomeGraph MCP] Graph sources=${mode} — skipping project/SDK open (tools return guidance).\n`);
                 return;
             }
-            this.cg = await loadHomeGraph().open(resolvedRoot, { sources: mode });
+            this.cg = await (await loadHomeGraph()).open(resolvedRoot, { sources: mode });
             this.toolHandler.setDefaultHomeGraph(this.cg);
             this.healBuildPhase(this.cg);
             this.startWatching();
@@ -282,11 +337,34 @@ class MCPEngine {
         // 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)) {
+            this.clearDeferProbe();
             return this.openAfterAutoInitRace(root);
         }
+        // Spec 0049: empty workspace — do not create `.homegraph/` (blocks
+        // in-place `devecocli create`). Probe later / on tool kick.
+        if (!(0, indexable_root_1.isIndexableRoot)(root)) {
+            this.armDeferProbe(root);
+            process.stderr.write(`[HomeGraph MCP] Auto-init deferred — empty root at ${root} ` +
+                `(no build-profile.json5 / indexable sources yet)\n`);
+            (0, runtime_log_1.logLifecycle)('auto-init.deferred', { projectRoot: root });
+            this.projectPath = root;
+            return false;
+        }
+        if (this.deferAutoInitPromise) {
+            return this.deferAutoInitPromise;
+        }
+        this.deferAutoInitPromise = this.runAutoInitCreate(root).finally(() => {
+            this.deferAutoInitPromise = null;
+        });
+        return this.deferAutoInitPromise;
+    }
+    /** Spec 0049: create DB + fast map + background full (shared by first hit and kick). */
+    async runAutoInitCreate(root) {
+        this.clearDeferProbe();
         try {
             process.stderr.write(`[HomeGraph MCP] Auto-init at ${root}\n`);
-            const HomeGraph = loadHomeGraph();
+            (0, runtime_log_1.logLifecycle)('auto-init.start', { projectRoot: root });
+            const HomeGraph = await 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`
@@ -312,6 +390,7 @@ class MCPEngine {
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
                     process.stderr.write(`[HomeGraph MCP] Fast build failed: ${msg}\n`);
+                    (0, runtime_log_1.logLifecycleError)('auto-init.fail', { projectRoot: root, phase: 'fast', msg });
                 }
                 this.startBackgroundFullBuild(cg);
             })();
@@ -324,9 +403,51 @@ class MCPEngine {
             }
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Auto-init failed: ${msg}\n`);
+            (0, runtime_log_1.logLifecycleError)('auto-init.fail', { projectRoot: root, msg });
+            // Keep probing so a later scaffold (or retry) can still land.
+            if (!(0, directory_1.isInitialized)(root)) {
+                this.armDeferProbe(root);
+            }
             return false;
         }
     }
+    /** Spec 0049: remember empty root and (optionally) poll until indexable. */
+    armDeferProbe(root) {
+        this.deferredAutoInitRoot = root;
+        if (this.deferProbeTimer)
+            return;
+        const ms = (0, indexable_root_1.parseDeferProbeMs)(process.env.HOMEGRAPH_DEFER_PROBE_MS);
+        if (ms <= 0)
+            return;
+        this.deferProbeTimer = setInterval(() => {
+            if (this.closed || this.toolHandler.hasDefaultHomeGraph()) {
+                this.clearDeferProbe();
+                return;
+            }
+            const target = this.deferredAutoInitRoot;
+            if (!target) {
+                this.clearDeferProbe();
+                return;
+            }
+            if (!(0, indexable_root_1.isIndexableRoot)(target))
+                return;
+            void this.tryAutoInit(target).then((ok) => {
+                if (ok)
+                    this.clearDeferProbe();
+            });
+        }, ms);
+        // Don't keep the process alive solely for the probe in direct mode.
+        if (typeof this.deferProbeTimer.unref === 'function') {
+            this.deferProbeTimer.unref();
+        }
+    }
+    clearDeferProbe() {
+        this.deferredAutoInitRoot = null;
+        if (this.deferProbeTimer) {
+            clearInterval(this.deferProbeTimer);
+            this.deferProbeTimer = null;
+        }
+    }
     /**
      * Open an index another process just created (Spec 0032 cold-start race).
      * Brief retries cover the window between mkdir and db file create.
@@ -342,7 +463,7 @@ class MCPEngine {
             }
             try {
                 process.stderr.write(`[HomeGraph MCP] Auto-init raced; opening existing index at ${root}\n`);
-                this.cg = await loadHomeGraph().open(root, { sources: mode });
+                this.cg = await (await loadHomeGraph()).open(root, { sources: mode });
                 this.projectPath = root;
                 this.toolHandler.setDefaultHomeGraph(this.cg);
                 this.healBuildPhase(this.cg);
@@ -400,6 +521,14 @@ class MCPEngine {
     startBackgroundFullBuild(cg) {
         cg.setBuildPhase('indexing');
         process.stderr.write('[HomeGraph MCP] Full build starting in-process (background)\n');
+        let projectRoot;
+        try {
+            projectRoot = cg.getProjectRoot();
+        }
+        catch {
+            projectRoot = this.projectPath ?? undefined;
+        }
+        (0, runtime_log_1.logLifecycle)('index.start', { projectRoot, via: 'auto-init' });
         void cg
             .indexAll()
             .then((result) => {
@@ -420,16 +549,20 @@ class MCPEngine {
                 cg.setBuildPhase('full');
                 process.stderr.write(`[HomeGraph MCP] Full build complete — files=${files || '?'} nodes=${nodes}` +
                     (ok ? '\n' : ' (soft-fail but symbols present)\n'));
+                (0, runtime_log_1.logLifecycle)('index.done', { projectRoot, files, nodes });
+                (0, runtime_log_1.logLifecycle)('auto-init.done', { projectRoot, files, nodes });
             }
             else {
                 cg.setBuildPhase('fast');
                 process.stderr.write('[HomeGraph MCP] Full build finished with no symbols — staying on fast map\n');
+                (0, runtime_log_1.logLifecycle)('index.done', { projectRoot, files: 0, nodes: 0, note: 'no-symbols' });
             }
             this.startWatchingAfterAutoInit();
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Full build failed: ${msg}\n`);
+            (0, runtime_log_1.logLifecycleError)('index.fail', { projectRoot, msg });
             try {
                 let nodes = 0;
                 try {
@@ -575,6 +708,9 @@ function parseFixedWindowEnv(raw) {
         return undefined;
     return n;
 }
+var indexable_root_2 = require("./indexable-root");
+Object.defineProperty(exports, "isIndexableRoot", { enumerable: true, get: function () { return indexable_root_2.isIndexableRoot; } });
+Object.defineProperty(exports, "parseDeferProbeMs", { enumerable: true, get: function () { return indexable_root_2.parseDeferProbeMs; } });
 /**
  * Parse and clamp the HOMEGRAPH_WATCH_DEBOUNCE_MS env override.
  *

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

@@ -28,4 +28,26 @@ export declare function resolveProductIndexState(cg: HomeGraph): ProductIndexSta
 export declare function isSqliteBusyMessage(message: string): boolean;
 /** True when text is already a pure (or leading) HomeGraph status line. */
 export declare function textAlreadyHasProductStatus(text: string): boolean;
+/** Marker line for Spec 0038 project-root path hint (idempotent prepend). */
+export declare const 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).
+ */
+export declare function formatProjectRootPathHint(absRoot: string): string;
+/** True when text already carries a Spec 0038 project-root hint. */
+export declare function textAlreadyHasProjectRootHint(text: string): boolean;
+/** Marker for Spec 0043 bound-root projectPath soft-pin notice (idempotent prepend). */
+export declare const 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.
+ */
+export declare function formatBoundProjectPathPinNotice(opts: {
+    boundRoot: string;
+    requestedPath: string;
+    resolvedRoot: string | null;
+}): string;
+/** True when text already carries a Spec 0043 pin notice. */
+export declare function textAlreadyHasBoundProjectPathPinNotice(text: string): boolean;
 //# sourceMappingURL=index-availability.d.ts.map