homegraph 1.5.8 → 1.5.10

package/dist/mcp/index-availability.js

@@ -1,44 +1,58 @@
 "use strict";
 /**
- * Product-facing index availability for MCP tool results (Spec 0032).
+ * Product-facing index availability for MCP tool results (Spec 0032 + 0035).
  *
- * 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.
+ * Internal `build_phase` stays as-is; this layer maps it (+ write-lock / busy /
+ * 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.productIndexGuidance = productIndexGuidance;
+exports.formatProductStatusLine = formatProductStatusLine;
 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.',
-];
+exports.textAlreadyHasProductStatus = textAlreadyHasProductStatus;
+/** 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;
+/** Whole-response guidance when the tool cannot usefully answer yet. */
 function productIndexGuidance(state) {
     switch (state) {
         case 'empty':
-            return EMPTY_LINES.join('\n');
+            return 'HomeGraph status=empty — not ready; retry shortly.';
         case 'fast':
-            return FAST_LINES.join('\n');
+            return 'HomeGraph status=fast — map only; use homegraph_project; retry other tools later.';
         case 'syncing':
-            return SYNCING_LINES.join('\n');
+            return 'HomeGraph status=syncing — locked; retry shortly, do not loop.';
+    }
+}
+/**
+ * Single status line for tool footers (and for guidance-only replies).
+ * `pendingPaths` only used when `state === 'dirty'`.
+ */
+function formatProductStatusLine(state, opts) {
+    switch (state) {
+        case 'empty':
+        case 'fast':
+        case 'syncing':
+            return productIndexGuidance(state);
+        case 'full':
+            return 'HomeGraph status=full — complete and up to date.';
+        case 'dirty': {
+            const paths = opts?.pendingPaths ?? [];
+            if (paths.length === 0) {
+                return 'HomeGraph status=dirty — outdated: pending files';
+            }
+            const shown = paths.slice(0, MAX_DIRTY_PATHS);
+            const more = paths.length > MAX_DIRTY_PATHS ? `, …+${paths.length - MAX_DIRTY_PATHS}` : '';
+            return `HomeGraph status=dirty — outdated: ${shown.join(', ')}${more}`;
+        }
     }
 }
 /**
  * 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
+ * Priority: syncing > empty > fast > dirty > full
  */
 function resolveProductIndexState(cg) {
     let phase;
@@ -69,10 +83,23 @@ function resolveProductIndexState(cg) {
     catch {
         return 'syncing';
     }
+    let pendingCount = 0;
+    try {
+        pendingCount = cg.getPendingFiles?.()?.length ?? 0;
+    }
+    catch {
+        pendingCount = 0;
+    }
+    if (pendingCount > 0)
+        return 'dirty';
     return 'full';
 }
 /** True when an error message indicates SQLite writer contention. */
 function isSqliteBusyMessage(message) {
     return /SQLITE_BUSY|database is locked/i.test(message);
 }
+/** True when text is already a pure (or leading) HomeGraph status line. */
+function textAlreadyHasProductStatus(text) {
+    return /^\s*HomeGraph status=/m.test(text);
+}
 //# sourceMappingURL=index-availability.js.map

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

@@ -1,7 +1,3 @@
-/**
- * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
- * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
- */
-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";
+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";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/server-instructions.js

@@ -1,10 +1,11 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
+const index_availability_1 = require("./index-availability");
 /**
  * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
  * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
 const SOURCE_AND_VALIDATION = `
 - 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.
 - 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.
@@ -33,10 +34,15 @@ Write one focused sentence: requested action + target + known anchors + unresolv
 
 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.
 `;
+const INDEX_STATUS = `## Index status
+
+Tool replies end with \`HomeGraph status=…\`. ${index_availability_1.PRODUCT_STATUS_GLOSSARY}.
+`;
 exports.SERVER_INSTRUCTIONS = `# HomeGraph — optional structural evidence for this repo
 
 ${ON_DEMAND}
 ${QUERY}
+${INDEX_STATUS}
 ${SOURCE_AND_VALIDATION}
 No index → use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.
 `;
@@ -46,6 +52,7 @@ Pass \`projectPath\` to an already indexed folder with \`.homegraph/\`. No index
 
 ${ON_DEMAND}
 ${QUERY}
+${INDEX_STATUS}
 ${SOURCE_AND_VALIDATION}
 `;
 //# sourceMappingURL=server-instructions.js.map

package/dist/mcp/tools.d.ts

@@ -418,6 +418,11 @@ export declare class ToolHandler {
      */
     private isFileStaleOnDisk;
     private withStalenessNotice;
+    /**
+     * Append a one-line product index status footer (Spec 0035).
+     * Guidance-only replies that already start with `HomeGraph status=` are left alone.
+     */
+    private withProductStatusFooter;
     /**
      * Execute a tool by name.
      *

package/dist/mcp/tools.js

@@ -26,7 +26,6 @@ const evidence_rendering_1 = require("./evidence-rendering");
 const arkts_evidence_packs_1 = require("./arkts-evidence-packs");
 const evidence_paths_1 = require("../graph/evidence-paths");
 const query_plan_1 = require("../search/query-plan");
-const memory_budget_1 = require("./memory-budget");
 const index_availability_1 = require("./index-availability");
 const directory_1 = require("../directory");
 // Lazy-load the heavy HomeGraph chain off the MCP startup path — see the same
@@ -1560,12 +1559,11 @@ class ToolHandler {
                 if (state === 'empty') {
                     return (0, index_availability_1.productIndexGuidance)('empty');
                 }
-                if (state === 'fast' || state === 'syncing') {
-                    // Keep the Spec 0027 "still building → homegraph_project" story for
-                    // frozen tools/list descriptions (hosts snapshot once at connect).
-                    return state === 'syncing'
-                        ? (0, index_availability_1.productIndexGuidance)('syncing')
-                        : "HomeGraph is still building this project's index. A call right now returns build-progress guidance; use `homegraph_project` for the module/file map, then retry once indexing finishes.";
+                if (state === 'fast') {
+                    return (0, index_availability_1.productIndexGuidance)('fast');
+                }
+                if (state === 'syncing') {
+                    return (0, index_availability_1.productIndexGuidance)('syncing');
                 }
             }
             catch {
@@ -1894,55 +1892,61 @@ class ToolHandler {
             const composed = `${formatDegradedBanner(reason)}\n\n${head.text}`;
             return { ...result, content: [{ type: 'text', text: composed }, ...tail] };
         }
-        // Defensive: some test fakes inject a partial HomeGraph stub without the
-        // newer pending-files API. Treat missing/throwing as "no pending files."
-        let pending = [];
-        try {
-            pending = cg.getPendingFiles?.() ?? [];
-        }
-        catch {
-            return result;
-        }
-        if (pending.length === 0)
+        // Spec 0035: pending/dirty is a one-line status footer (withProductStatusFooter),
+        // not the long ⚠️ stale banner. Keep formatStaleBanner helpers for tests /
+        // status tool; do not prepend them on every read tool.
+        return result;
+    }
+    /**
+     * Append a one-line product index status footer (Spec 0035).
+     * Guidance-only replies that already start with `HomeGraph status=` are left alone.
+     */
+    withProductStatusFooter(result, projectPath) {
+        if (result.isError)
             return result;
         const [first, ...rest] = result.content;
         if (!first || first.type !== 'text')
             return result;
-        const text = first.text;
-        const inResponse = [];
-        const elsewhere = [];
-        for (const p of pending) {
-            // Substring match against the project-relative POSIX path — that's
-            // exactly the format both the watcher and every homegraph response
-            // emit, so a plain includes() is sufficient and avoids regex pitfalls.
-            if (text.includes(p.path))
-                inResponse.push(p);
-            else
-                elsewhere.push(p);
+        if ((0, index_availability_1.textAlreadyHasProductStatus)(first.text))
+            return result;
+        let cg;
+        try {
+            cg = this.getHomeGraph(projectPath);
+        }
+        catch {
+            return result;
         }
-        let banner = '';
-        if (inResponse.length > 0) {
-            let dbPath = null;
+        if (this.cg && cg !== this.cg) {
             try {
-                // Large indexes skip catch-up — soft banner so agents don't abandon HG for Read.
-                const root = cg.getProjectRoot();
-                dbPath = (0, path_1.resolve)(root, '.homegraph', 'homegraph.db');
+                const sameProject = (0, path_1.resolve)(this.cg.getProjectRoot()) === (0, path_1.resolve)(cg.getProjectRoot());
+                if (sameProject)
+                    cg = this.cg;
             }
             catch {
-                dbPath = null;
+                /* leave cg */
             }
-            banner = formatStaleBanner(inResponse, {
-                catchUpDeferred: (0, memory_budget_1.shouldSkipCatchUpSync)(dbPath),
-            });
         }
-        let footer = '';
-        if (elsewhere.length > 0) {
-            footer = formatStaleFooter(elsewhere);
+        let state;
+        try {
+            state = (0, index_availability_1.resolveProductIndexState)(cg);
         }
-        if (!banner && !footer)
+        catch {
             return result;
-        const composed = [banner, text, footer].filter(Boolean).join('\n\n');
-        return { ...result, content: [{ type: 'text', text: composed }, ...rest] };
+        }
+        let pendingPaths;
+        if (state === 'dirty') {
+            try {
+                pendingPaths = (cg.getPendingFiles?.() ?? []).map((p) => p.path);
+            }
+            catch {
+                pendingPaths = [];
+            }
+        }
+        const line = (0, index_availability_1.formatProductStatusLine)(state, { pendingPaths });
+        return {
+            ...result,
+            content: [{ type: 'text', text: `${first.text}\n\n${line}` }, ...rest],
+        };
     }
     /**
      * Execute a tool by name.
@@ -2069,7 +2073,7 @@ class ToolHandler {
                         && this.areEvidenceFilesCurrent(cachedFiles ?? [], cacheCg.getProjectRoot())))) {
                         const diagnosed = this.withQueryPlanDiagnostics(cached, args, true);
                         const withWorktree = this.withWorktreeNotice(diagnosed, projectPath);
-                        return this.withStalenessNotice(withWorktree, projectPath);
+                        return this.withProductStatusFooter(this.withStalenessNotice(withWorktree, projectPath), projectPath);
                     }
                 }
                 catch {
@@ -2133,7 +2137,7 @@ class ToolHandler {
                                 cacheIndex.setEntry(cacheQueries, cacheKey, toolName, served);
                             }
                             const withWorktree = this.withWorktreeNotice(served, projectPath);
-                            return this.withStalenessNotice(withWorktree, projectPath);
+                            return this.withProductStatusFooter(this.withStalenessNotice(withWorktree, projectPath), projectPath);
                         }
                         if (requestPlan)
                             args[QUERY_FAST_ATTEMPTED_ARG] = true;
@@ -2164,7 +2168,7 @@ class ToolHandler {
                 cacheIndex.setEntry(cacheQueries, cacheKey, toolName, result);
             }
             const withWorktree = this.withWorktreeNotice(result, projectPath);
-            return this.withStalenessNotice(withWorktree, projectPath);
+            return this.withProductStatusFooter(this.withStalenessNotice(withWorktree, projectPath), projectPath);
         }
         catch (err) {
             // Expected condition, not a malfunction: answer as a SUCCESS so the
@@ -2509,7 +2513,7 @@ class ToolHandler {
      */
     maybeDeepToolPhaseGate(cg, _toolName) {
         const state = (0, index_availability_1.resolveProductIndexState)(cg);
-        if (state === 'full')
+        if (state === 'full' || state === 'dirty')
             return null;
         if (state === 'syncing') {
             return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
@@ -12190,18 +12194,11 @@ class ToolHandler {
             return this.textResult('No modules found in the project map.');
         }
         const FILE_CAP = 80;
-        const productState = (0, index_availability_1.resolveProductIndexState)(cg);
         const lines = [
-            `**Project map** (status=${productState}, phase=${map.phase})`,
+            `**Project map** (phase=${map.phase})`,
             `modules: ${map.modules.length} · files: ${map.fileCount}`,
             '',
         ];
-        if (productState === 'fast' || map.phase === 'fast' || map.phase === 'indexing') {
-            lines.push('_Full symbol index still building — this map has modules/files only (no call graph)._', '');
-        }
-        if (productState === 'syncing') {
-            lines.push('_Index write in progress — map may be briefly stale._', '');
-        }
         for (const m of map.modules) {
             const rootLabel = m.rootPath || '.';
             lines.push(`### ${m.name} (\`${rootLabel}\`) · ${m.kind} · ${m.fileCount} files`);

package/dist/project-map/index.js

@@ -103,7 +103,8 @@ function discoverModules(projectRoot) {
         rootPath: '',
         kind: 'root',
     });
-    const harmony = listHarmonyProjectModulesLoose(projectRoot);
+    // Same parser as ArkTS dirty-module mapping (Spec 0034): bare keys + single quotes.
+    const harmony = (0, arkts_1.listHarmonyProjectModules)(projectRoot);
     if (harmony.length > 0) {
         for (const m of harmony) {
             ensure({
@@ -132,47 +133,6 @@ function discoverModules(projectRoot) {
     }
     return [...byId.values()];
 }
-function listHarmonyProjectModulesLoose(projectRoot) {
-    const strict = (0, arkts_1.listHarmonyProjectModules)(projectRoot);
-    if (strict.length > 0)
-        return strict;
-    // Real DevEco `build-profile.json5` often uses unquoted keys; the strict
-    // parser only strips comments/trailing commas. Quote bare keys and retry.
-    const profilePath = path.join(projectRoot, 'build-profile.json5');
-    if (!fs.existsSync(profilePath))
-        return [];
-    let raw;
-    try {
-        const text = fs.readFileSync(profilePath, 'utf-8');
-        const stripped = text
-            .replace(/\/\/.*$/gm, '')
-            .replace(/\/\*[\s\S]*?\*\//g, '')
-            .replace(/,(\s*[}\]])/g, '$1')
-            .replace(/([{,]\s*)([A-Za-z_][\w]*)\s*:/g, '$1"$2":');
-        raw = JSON.parse(stripped);
-    }
-    catch {
-        return [];
-    }
-    if (!raw || typeof raw !== 'object')
-        return [];
-    const modules = raw.modules;
-    if (!Array.isArray(modules))
-        return [];
-    const out = [];
-    for (const entry of modules) {
-        if (!entry || typeof entry !== 'object')
-            continue;
-        const rec = entry;
-        if (typeof rec.name !== 'string' || typeof rec.srcPath !== 'string')
-            continue;
-        const srcPath = (0, arkts_1.normalizeHarmonyModuleSrcPath)(rec.srcPath);
-        if (!srcPath)
-            continue;
-        out.push({ name: rec.name, srcPath });
-    }
-    return out;
-}
 function discoverOhpmPackages(projectRoot) {
     const out = [];
     const queue = [{ rel: '', depth: 0 }];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homegraph",
-  "version": "1.5.8",
+  "version": "1.5.10",
   "description": "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,7 +36,7 @@
   "license": "MIT",
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "arkanalyzer": "^1.0.92",
+    "arkanalyzer": "^1.0.94",
     "commander": "^14.0.3",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",