homegraph 1.6.1 → 1.6.2

package/CHANGELOG.md

@@ -10,6 +10,27 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 
+## [1.6.2] - 2026-10-19
+
+### New Features
+
+- **iCode support** in the installer. `homegraph install --target icode` wires the MCP server into iCode agent profiles (`~/.chrys/agents/` on macOS/Linux, `%APPDATA%\chrys\agents\` on Windows). The target is global-only. It edits existing profiles in place and, when the iCode runtime is found, writes shadow profiles for the built-in agents. If the runtime is missing, install still updates existing profiles and prints manual guidance. `HOMEGRAPH_ICODE_NO_BUILTINS=1` skips shadows. No instructions file is written (Spec 0057).
+
+### Improvements
+
+- `homegraph_explore` no longer stops after 2 calls on a long-lived MCP connection. Another explore within 10 seconds of the previous result is refused; a later call, including a different question, is allowed. The tool description, initialize instructions, and explore footer state that wait (Spec 0058).
+- MCP initialize / `homegraph_explore` description: drop bash-first and "HomeGraph is optional" wording that conflicted with DevEco Code's graph-first product prompt; existing-code tasks open with `homegraph_explore` alone. Tool list, budgets, and evidence caveats unchanged.
+- MCP under Bun skips the Node/V8 `--liftoff-only` relaunch (those flags do not apply), so product hosts can spawn `homegraph.js` with the host Bun binary (Spec 0052).
+- MCP product hosts that prefix tools with the server name (e.g. DevEco Code) can set `HOMEGRAPH_MCP_SHORT_TOOL_NAMES=1` so tools/list exposes short names (`explore`, `project`) and tools/call still accepts both short and `homegraph_*` forms — avoiding a doubled `homegraph_homegraph_*` name after the host prefix. Unset by default; Cursor/Claude keep canonical `homegraph_*` names.
+
+### Fixes
+
+- C/C++: a call no longer binds another file's `static` function when a definition with external linkage exists. A C definition compiled only under a feature flag nothing in the project sets yields to the definition the default build compiles (Spec 0056).
+- Windows: a file the daemon only read no longer shows up as edited. Watcher events whose size and modification time still match the index are ignored, so an NTFS last-access update does not mark the file pending sync (Spec 0055).
+- C/C++: a header whose only C++ signal is `struct Derived : Base` is indexed as C++. A call that names a function-like macro visible at that line is not linked to a same-named function, and the include walk that decides this is bounded so a deep guard graph cannot blow the heap (Spec 0054).
+- MCP `homegraph_explore` call budget shown to agents is **2** on every repo size, matching the session hard cap. Output sizing tiers are unchanged. Heuristic edges store `synthesized_by`, and ArkTS cross-file call cleanup deletes that channel by column instead of a JSON text match. Explore and Partial replies no longer tell the agent to call `homegraph_node`. Name search still tries FTS first, including Chinese literals (Spec 0053).
+- MCP tools/list: when a session has no default project, `projectPath` is already marked `required` in the schema — its property description no longer says "Omit to use this session's default project", so agents are not told the field is both required and optional.
+
 ## [1.6.1] - 2026-09-28
 
 ### Improvements
@@ -283,3 +304,4 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 [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
 [1.6.1]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.6.1
+[1.6.2]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.6.2

package/dist/bin/homegraph.js

@@ -1917,7 +1917,7 @@ function main() {
      */
     program
         .command('install')
-        .description('Install homegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent)')
+        .description('Install homegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent, iCode)')
         .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "auto"|"all"|"none". Default: prompt')
         .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt')
         .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=auto, auto-allow on')
@@ -1976,7 +1976,7 @@ function main() {
      */
     program
         .command('uninstall')
-        .description('Remove homegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent)')
+        .description('Remove homegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent, iCode)')
         .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "all". Default: all')
         .option('-l, --location <where>', 'Uninstall location: "global" or "local". Default: prompt')
         .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=all')

package/dist/db/index.js

@@ -329,6 +329,7 @@ class DatabaseConnection {
         'idx_edges_source_kind',
         'idx_edges_target_kind',
         'idx_edges_provenance',
+        'idx_edges_synthesized_by',
     ];
     /**
      * Enter bulk-edge-load mode: drop the non-unique edge indexes so the mass

package/dist/db/migrations.d.ts

@@ -7,7 +7,7 @@ import { SqliteDatabase } from './sqlite-adapter';
 /**
  * Current schema version
  */
-export declare const CURRENT_SCHEMA_VERSION = 11;
+export declare const CURRENT_SCHEMA_VERSION = 12;
 /**
  * Migration definition
  */
@@ -16,6 +16,11 @@ interface Migration {
     description: string;
     up: (db: SqliteDatabase) => void;
 }
+/**
+ * Copy `metadata.synthesizedBy` onto `edges.synthesized_by` when the column is empty.
+ * Channel deletes read the column, not JSON text (Spec 0053).
+ */
+export declare function backfillEdgeSynthesizedBy(db: SqliteDatabase): void;
 /**
  * Get the current schema version from the database
  */

package/dist/db/migrations.js

@@ -6,6 +6,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CURRENT_SCHEMA_VERSION = void 0;
+exports.backfillEdgeSynthesizedBy = backfillEdgeSynthesizedBy;
 exports.getCurrentVersion = getCurrentVersion;
 exports.runMigrations = runMigrations;
 exports.needsMigration = needsMigration;
@@ -14,7 +15,7 @@ exports.getMigrationHistory = getMigrationHistory;
 /**
  * Current schema version
  */
-exports.CURRENT_SCHEMA_VERSION = 11;
+exports.CURRENT_SCHEMA_VERSION = 12;
 /**
  * All migrations in order
  *
@@ -175,7 +176,31 @@ const migrations = [
       `);
         },
     },
+    {
+        version: 12,
+        description: 'Add edges.synthesized_by and backfill from metadata.synthesizedBy (Spec 0053)',
+        up: (db) => {
+            const cols = db.prepare('PRAGMA table_info(edges)').all();
+            if (!cols.some((c) => c.name === 'synthesized_by')) {
+                db.exec('ALTER TABLE edges ADD COLUMN synthesized_by TEXT');
+            }
+            backfillEdgeSynthesizedBy(db);
+            db.exec('CREATE INDEX IF NOT EXISTS idx_edges_synthesized_by ON edges(synthesized_by) WHERE synthesized_by IS NOT NULL');
+        },
+    },
 ];
+/**
+ * Copy `metadata.synthesizedBy` onto `edges.synthesized_by` when the column is empty.
+ * Channel deletes read the column, not JSON text (Spec 0053).
+ */
+function backfillEdgeSynthesizedBy(db) {
+    db.exec(`
+    UPDATE edges
+    SET synthesized_by = json_extract(metadata, '$.synthesizedBy')
+    WHERE (synthesized_by IS NULL OR synthesized_by = '')
+      AND json_extract(metadata, '$.synthesizedBy') IS NOT NULL
+  `);
+}
 /**
  * Get the current schema version from the database
  */

package/dist/db/queries.d.ts

@@ -5,6 +5,11 @@
  */
 import { SqliteDatabase } from './sqlite-adapter';
 import { Node, Edge, FileRecord, UnresolvedReference, NodeKind, EdgeKind, Language, GraphStats, SearchOptions, SearchResult } from '../types';
+/**
+ * Convert database row to Edge object
+ */
+/** Channel name stored on `edges.synthesized_by` (Spec 0053). */
+export declare function edgeSynthesizedBy(edge: Edge): string | null;
 /**
  * Query builder for the knowledge graph database
  */

package/dist/db/queries.js

@@ -39,6 +39,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryBuilder = void 0;
+exports.edgeSynthesizedBy = edgeSynthesizedBy;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const utils_1 = require("../utils");
@@ -110,6 +111,11 @@ function rowToNode(row) {
 /**
  * Convert database row to Edge object
  */
+/** Channel name stored on `edges.synthesized_by` (Spec 0053). */
+function edgeSynthesizedBy(edge) {
+    const value = edge.metadata?.synthesizedBy;
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
 function rowToEdge(row) {
     return {
         source: row.source,
@@ -383,9 +389,10 @@ class QueryBuilder {
                         edge.line ?? null,
                         edge.column ?? null,
                         edge.provenance ?? null,
+                        edgeSynthesizedBy(edge),
                     ]);
                 }
-                this.runBatched('insertEdges', 'INSERT OR IGNORE INTO edges (source, target, kind, metadata, line, col, provenance) VALUES ', '(?,?,?,?,?,?,?)', rows);
+                this.runBatched('insertEdges', 'INSERT OR IGNORE INTO edges (source, target, kind, metadata, line, col, provenance, synthesized_by) VALUES ', '(?,?,?,?,?,?,?,?)', rows);
             }
             if (bundle.refs.length > 0)
                 this.insertUnresolvedRefsBatch(bundle.refs);
@@ -994,11 +1001,13 @@ class QueryBuilder {
                 return [];
             return this.mergeOhosApiTextSearch(text, { kinds, languages, limit }, []);
         }
-        // First try FTS5 with prefix matching
+        // First try FTS5 with prefix matching. Chinese literals (for example
+        // string.json values in docstring) are real FTS tokens — do not skip them.
         let results = text
             ? this.searchNodesFTS(text, { kinds, languages, limit, offset })
             // Over-fetch by 5× when running filter-only (no text). The
-            // post-scoring path: + name: filters can be very selective, so      // a smaller multiplier risks returning fewer than `limit`
+            // post-scoring path: name: filters can be very selective, so
+            // a smaller multiplier risks returning fewer than `limit`
             // results despite the DB having plenty of matches.
             : this.searchAllByFilters({ kinds, languages, limit: limit * 5 });
         // If no FTS results, try LIKE-based substring search
@@ -1497,8 +1506,8 @@ class QueryBuilder {
     insertEdge(edge) {
         if (!this.stmts.insertEdge) {
             this.stmts.insertEdge = this.db.prepare(`
-        INSERT OR IGNORE INTO edges (source, target, kind, metadata, line, col, provenance)
-        VALUES (@source, @target, @kind, @metadata, @line, @col, @provenance)
+        INSERT OR IGNORE INTO edges (source, target, kind, metadata, line, col, provenance, synthesized_by)
+        VALUES (@source, @target, @kind, @metadata, @line, @col, @provenance, @synthesizedBy)
       `);
         }
         this.stmts.insertEdge.run({
@@ -1509,6 +1518,7 @@ class QueryBuilder {
             line: edge.line ?? null,
             col: edge.column ?? null,
             provenance: edge.provenance ?? null,
+            synthesizedBy: edgeSynthesizedBy(edge),
         });
     }
     /**
@@ -1713,8 +1723,8 @@ class QueryBuilder {
             .prepare(`DELETE FROM edges
          WHERE kind = 'calls'
            AND provenance = 'heuristic'
-           AND metadata LIKE '%"synthesizedBy":"arkanalyzer"%'
-           AND metadata LIKE '%"sourceFile"%'`)
+           AND synthesized_by = 'arkanalyzer'
+           AND json_extract(metadata, '$.sourceFile') IS NOT NULL`)
             .run();
         return result.changes;
     }

package/dist/db/schema.sql

@@ -52,6 +52,9 @@ CREATE TABLE IF NOT EXISTS edges (
     line INTEGER,
     col INTEGER,
     provenance TEXT DEFAULT NULL,
+    -- Channel of a heuristic edge (`metadata.synthesizedBy`). Written on insert
+    -- so re-index can delete by channel without matching JSON text (Spec 0053).
+    synthesized_by TEXT,
     FOREIGN KEY (source) REFERENCES nodes(id) ON DELETE CASCADE,
     FOREIGN KEY (target) REFERENCES nodes(id) ON DELETE CASCADE
 );
@@ -192,6 +195,7 @@ CREATE INDEX IF NOT EXISTS idx_unresolved_from_name ON unresolved_refs(from_node
 CREATE INDEX IF NOT EXISTS idx_unresolved_status ON unresolved_refs(status);
 CREATE INDEX IF NOT EXISTS idx_unresolved_failed_tail ON unresolved_refs(name_tail) WHERE status = 'failed';
 CREATE INDEX IF NOT EXISTS idx_edges_provenance ON edges(provenance);
+CREATE INDEX IF NOT EXISTS idx_edges_synthesized_by ON edges(synthesized_by) WHERE synthesized_by IS NOT NULL;
 
 -- Project metadata for version/provenance tracking
 CREATE TABLE IF NOT EXISTS project_metadata (

package/dist/extraction/grammars.js

@@ -529,7 +529,8 @@ function looksLikeCpp(source) {
     // routed through the C extractor (which extracts no classes), and its class
     // definition silently vanishes. The two-token shape (`<KW> <MACRO> <Name>`
     // before a `[:{]`) never occurs in valid C, so this can't misclassify C headers.
-    return /\bnamespace\b|\bclass\s+\w+\s*[:{]|\b(?:class|struct)\s+[A-Z][A-Z0-9_]+\s+\w+\s*(?:final\s*)?[:{]|\btemplate\s*<|\b(?:public|private|protected)\s*:|\bvirtual\b|\busing\s+(?:namespace\b|\w+\s*=)/.test(sample);
+    // `struct Derived : Base` is C++. A plain `struct Point {` stays C.
+    return /\bnamespace\b|\bclass\s+\w+\s*[:{]|\bstruct\s+\w+\s*:|\b(?:class|struct)\s+[A-Z][A-Z0-9_]+\s+\w+\s*(?:final\s*)?[:{]|\btemplate\s*<|\b(?:public|private|protected)\s*:|\bvirtual\b|\busing\s+(?:namespace\b|\w+\s*=)/.test(sample);
 }
 /**
  * Heuristic: does a .h file contain Objective-C constructs?

package/dist/extraction/languages/c-cpp.d.ts

@@ -102,6 +102,14 @@ export declare function blankMetalAttributes(source: string): string;
  * ALL-CAPS call that isn't markup only loses that one annotation, never a whole
  * class.
  */
+/**
+ * Mask C++ raw string literals (`R"delim(...)delim"`) so later blankers do not
+ * treat their contents as code. Offsets stay aligned with the original source.
+ */
+export declare function maskCppRawStrings(source: string): {
+    source: string;
+    restore: (blanked: string) => string;
+};
 export declare function blankCppAnnotationMacroCalls(source: string): string;
 export declare function blankCppApiPrefixMacros(source: string): string;
 export declare function blankCppInlineAnnotationMacros(source: string): string;

package/dist/extraction/languages/c-cpp.js

@@ -7,6 +7,7 @@ exports.blankCppExportMacros = blankCppExportMacros;
 exports.blankCppInlineMacros = blankCppInlineMacros;
 exports.recoverMangledCppName = recoverMangledCppName;
 exports.blankMetalAttributes = blankMetalAttributes;
+exports.maskCppRawStrings = maskCppRawStrings;
 exports.blankCppAnnotationMacroCalls = blankCppAnnotationMacroCalls;
 exports.blankCppApiPrefixMacros = blankCppApiPrefixMacros;
 exports.blankCppInlineAnnotationMacros = blankCppInlineAnnotationMacros;
@@ -493,6 +494,49 @@ function blankMetalAttributes(source) {
  * ALL-CAPS call that isn't markup only loses that one annotation, never a whole
  * class.
  */
+/**
+ * Mask C++ raw string literals (`R"delim(...)delim"`) so later blankers do not
+ * treat their contents as code. Offsets stay aligned with the original source.
+ */
+function maskCppRawStrings(source) {
+    const unchanged = { source, restore: (blanked) => blanked };
+    if (source.indexOf('R"') === -1)
+        return unchanged;
+    const re = /\/\/[^\r\n]*|\/\*[\s\S]*?(?:\*\/|$)|\b(?:u8|[LuU])?R"([^ \t\v\f\r\n()\\]{0,16})\(|"(?:\\[\s\S]|[^"\\])*(?:"|$)|(?<!\w)(?:u8|[LuU])?'(?:\\[\s\S]|[^'\\])*(?:'|$)/g;
+    const spans = [];
+    const parts = [];
+    let last = 0;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        if (m[1] === undefined)
+            continue;
+        const closer = `)${m[1]}"`;
+        const close = source.indexOf(closer, re.lastIndex);
+        const end = close < 0 ? source.length : close + closer.length;
+        spans.push({ start: m.index, end });
+        parts.push(source.slice(last, m.index), source.slice(m.index, end).replace(/[^\r\n]/g, '\0'));
+        last = re.lastIndex = end;
+    }
+    if (spans.length === 0)
+        return unchanged;
+    parts.push(source.slice(last));
+    const masked = parts.join('');
+    return {
+        source: masked,
+        restore(blanked) {
+            if (blanked === masked || blanked.length !== source.length)
+                return source;
+            const chars = blanked.split('');
+            for (const { start, end } of spans) {
+                for (let i = start; i < end; i++) {
+                    if (chars[i] === '\0')
+                        chars[i] = source[i];
+                }
+            }
+            return chars.join('');
+        },
+    };
+}
 function blankCppAnnotationMacroCalls(source) {
     if (!/^[ \t]*[A-Z][A-Z0-9_]{2,}\s*\(/m.test(source))
         return source;

package/dist/extraction/wasm-runtime-flags.d.ts

@@ -44,5 +44,9 @@ export declare function buildRelaunchArgv(scriptPath: string, scriptArgs: readon
  * On spawn failure, returns so the caller runs in-process anyway — risking the
  * OOM is still better than refusing to start.
  */
+/** Bun is not V8 — `--liftoff-only` / `--max-old-space-size` relaunch does not apply. */
+export declare function isBunRuntime(g?: {
+    Bun?: unknown;
+}): boolean;
 export declare function relaunchWithWasmRuntimeFlagsIfNeeded(scriptPath: string): void;
 //# sourceMappingURL=wasm-runtime-flags.d.ts.map

package/dist/extraction/wasm-runtime-flags.js

@@ -6,6 +6,7 @@ exports.maxOldSpaceSizeFlag = maxOldSpaceSizeFlag;
 exports.processHasWasmRuntimeFlags = processHasWasmRuntimeFlags;
 exports.processHasRequiredRuntimeFlags = processHasRequiredRuntimeFlags;
 exports.buildRelaunchArgv = buildRelaunchArgv;
+exports.isBunRuntime = isBunRuntime;
 exports.relaunchWithWasmRuntimeFlagsIfNeeded = relaunchWithWasmRuntimeFlagsIfNeeded;
 /**
  * WASM runtime flags — workaround for the V8 turboshaft WASM Zone OOM.
@@ -134,6 +135,10 @@ function buildRelaunchArgv(scriptPath, scriptArgs, execArgv = process.execArgv)
  * On spawn failure, returns so the caller runs in-process anyway — risking the
  * OOM is still better than refusing to start.
  */
+/** Bun is not V8 — `--liftoff-only` / `--max-old-space-size` relaunch does not apply. */
+function isBunRuntime(g = globalThis) {
+    return typeof g.Bun !== 'undefined';
+}
 function relaunchWithWasmRuntimeFlagsIfNeeded(scriptPath) {
     if (processHasRequiredRuntimeFlags())
         return;
@@ -141,6 +146,10 @@ function relaunchWithWasmRuntimeFlagsIfNeeded(scriptPath) {
         return;
     if (process.env.HOMEGRAPH_NO_RELAUNCH)
         return;
+    // Product hosts (e.g. DevEco Code) spawn MCP under Bun; V8 flags would be
+    // ignored or break relaunch. Stay in-process.
+    if (isBunRuntime())
+        return;
     const argv = buildRelaunchArgv(scriptPath, process.argv.slice(2));
     const result = (0, child_process_1.spawnSync)(process.execPath, argv, {
         stdio: 'inherit',

package/dist/index.js

@@ -854,7 +854,13 @@ class HomeGraph {
             }
             const filesChanged = result.filesAdded + result.filesModified + result.filesRemoved;
             return { filesChanged, durationMs: result.durationMs };
-        }, options);
+        }, {
+            ...options,
+            indexedFingerprint: options.indexedFingerprint ?? ((rel) => {
+                const rec = this.getFile(rel);
+                return rec ? { size: rec.size, modifiedAt: rec.modifiedAt } : null;
+            }),
+        });
         return this.watcher.start();
     }
     /**

package/dist/installer/targets/icode.d.ts

@@ -0,0 +1,43 @@
+/**
+ * iCode target.
+ *
+ * iCode (product name) ships as the Python package `chrys`; agent profiles
+ * are individual YAML files, one per profile, under `~/.chrys/agents/`
+ * (macOS/Linux) or `%APPDATA%\chrys\agents\` (Windows). Each profile is a
+ * complete agent definition carrying a `tools.mcp` list of MCP server
+ * configs.
+ *
+ * iCode has NO project-local config concept — this target is global-only.
+ *
+ * Install (synchronous, non-interactive — no per-profile prompt):
+ *   1. Every EXISTING user profile under `~/.chrys/agents/*.yaml|yml` gets
+ *      the homegraph MCP entry injected in place — a surgical line edit
+ *      that preserves sibling MCP servers and every other section.
+ *   2. Built-in agents (Code / QA / Explore / General) are discovered from
+ *      the installed iCode runtime
+ *      (`.../site-packages/chrys/service/profiles/agents/builtins/`). A
+ *      built-in with no user profile of the same name gets a "shadow"
+ *      profile written to `~/.chrys/agents/<name>.yaml`: the built-in's
+ *      FULL content plus the homegraph entry. (iCode's own override rule:
+ *      a user profile with a built-in's name REPLACES the built-in
+ *      entirely, so the copy must be complete.)
+ *      If the runtime can't be located, install degrades to editing
+ *      existing profiles only and returns manual guidance in `notes` — it
+ *      never throws.
+ *
+ * Uninstall strips the homegraph entry from every user profile that
+ * carries it (shadow files are left as plain built-in copies), matching
+ * the other targets' "remove only what install wrote" contract.
+ *
+ * No instructions file is written (#529/#704) — guidance ships in the MCP
+ * `initialize` response, which iCode injects into system reminders by
+ * default (`expose_instructions: true`).
+ *
+ * NOTE: unlike the codegraph fork, this target must NOT suppress the
+ * "install the CLI on PATH" step in `src/installer/index.ts` — the MCP
+ * command is the `homegraph` Node CLI, which iCode (a Python app) does not
+ * bundle.
+ */
+import { AgentTarget } from './types';
+export declare const icodeTarget: AgentTarget;
+//# sourceMappingURL=icode.d.ts.map