homegraph 1.5.0 → 1.5.2

package/dist/mcp/diff-impact.js

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * Diff → changed-symbol impact helpers for `homegraph_diff_impact`.
+ *
+ * Parses unified diffs (new-side line ranges), intersects those ranges with
+ * indexed symbol spans, and builds a capped evidence pack (callers / impact
+ * summary / UI edges). Spec attachment is left to the MCP handler.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIFF_IMPACT_LIMITS = exports.DIFF_IMPACT_UI_SYNTHESIZED_BY = exports.DIFF_IMPACT_MAX_DIFF_CHARS = void 0;
+exports.normalizeDiffFilePath = normalizeDiffFilePath;
+exports.parseUnifiedDiff = parseUnifiedDiff;
+exports.mergeRanges = mergeRanges;
+exports.rangesOverlap = rangesOverlap;
+exports.nodeOverlapsRanges = nodeOverlapsRanges;
+exports.selectChangedSymbols = selectChangedSymbols;
+exports.isDiffImpactUiEdge = isDiffImpactUiEdge;
+exports.buildDiffImpactPack = buildDiffImpactPack;
+exports.resolveDiffImpactHunks = resolveDiffImpactHunks;
+/** Max chars accepted for the `diff` argument (DoS bound; still success-shaped). */
+exports.DIFF_IMPACT_MAX_DIFF_CHARS = 500_000;
+exports.DIFF_IMPACT_UI_SYNTHESIZED_BY = new Set([
+    'viewtree',
+    'arkui-state',
+    'arkui-route',
+    'arkui-emitter',
+]);
+/** Kinds that are almost never useful as "what changed" anchors for review. */
+const SKIP_NODE_KINDS = new Set([
+    'file',
+    'module',
+    'parameter',
+    'import',
+    'export',
+]);
+exports.DIFF_IMPACT_LIMITS = {
+    maxSymbols: 80,
+    maxCallersPerSymbol: 8,
+    maxImpactSamples: 8,
+    maxUiEdges: 40,
+    maxSpecSymbols: 15,
+};
+/**
+ * Strip unified-diff path prefixes (`a/`, `b/`, `./`) and normalize slashes.
+ */
+function normalizeDiffFilePath(raw) {
+    let p = raw.trim().replace(/\\/g, '/');
+    if (p === '/dev/null' || p === 'nul' || p === 'NUL')
+        return '';
+    // git often emits "b/src/foo.ts\t" or with timestamps after a tab
+    const tab = p.indexOf('\t');
+    if (tab >= 0)
+        p = p.slice(0, tab);
+    if (p.startsWith('a/') || p.startsWith('b/'))
+        p = p.slice(2);
+    p = p.replace(/^\.\//, '');
+    return p;
+}
+/**
+ * Parse unified diff text into per-file **new-side** (post-change) line ranges.
+ * Pure deletions (new count 0) contribute no ranges but still list the file.
+ */
+function parseUnifiedDiff(diff) {
+    const notes = [];
+    const byFile = new Map();
+    let currentPath = '';
+    const lines = diff.split(/\r?\n/);
+    for (const line of lines) {
+        if (line.startsWith('+++ ')) {
+            const path = normalizeDiffFilePath(line.slice(4));
+            currentPath = path;
+            if (path && !byFile.has(path))
+                byFile.set(path, []);
+            continue;
+        }
+        if (line.startsWith('--- ')) {
+            // Prefer +++ when present; --- alone (e.g. unusual diffs) seeds the path.
+            const path = normalizeDiffFilePath(line.slice(4));
+            if (path && !currentPath) {
+                currentPath = path;
+                if (!byFile.has(path))
+                    byFile.set(path, []);
+            }
+            continue;
+        }
+        if (line.startsWith('diff --git ')) {
+            currentPath = '';
+            continue;
+        }
+        const m = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/.exec(line);
+        if (!m)
+            continue;
+        if (!currentPath) {
+            notes.push('Skipped a hunk with no preceding +++ file path.');
+            continue;
+        }
+        const newStart = parseInt(m[3], 10);
+        const newCount = m[4] !== undefined ? parseInt(m[4], 10) : 1;
+        if (newCount <= 0) {
+            // Pure deletion on the new side — keep file listed, no line ranges.
+            if (!byFile.has(currentPath))
+                byFile.set(currentPath, []);
+            continue;
+        }
+        const ranges = byFile.get(currentPath) ?? [];
+        ranges.push({
+            startLine: newStart,
+            endLine: newStart + newCount - 1,
+        });
+        byFile.set(currentPath, ranges);
+    }
+    const hunks = [];
+    for (const [path, ranges] of byFile) {
+        hunks.push({ path, ranges: mergeRanges(ranges) });
+    }
+    hunks.sort((a, b) => a.path.localeCompare(b.path));
+    return { hunks, notes };
+}
+/** Merge overlapping / adjacent line ranges. */
+function mergeRanges(ranges) {
+    if (ranges.length === 0)
+        return [];
+    const sorted = [...ranges].sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine);
+    const out = [{ ...sorted[0] }];
+    for (let i = 1; i < sorted.length; i++) {
+        const cur = sorted[i];
+        const last = out[out.length - 1];
+        if (cur.startLine <= last.endLine + 1) {
+            last.endLine = Math.max(last.endLine, cur.endLine);
+        }
+        else {
+            out.push({ ...cur });
+        }
+    }
+    return out;
+}
+function rangesOverlap(a, b) {
+    return a.startLine <= b.endLine && b.startLine <= a.endLine;
+}
+function nodeOverlapsRanges(node, ranges) {
+    const span = { startLine: node.startLine, endLine: node.endLine };
+    return ranges.some((r) => rangesOverlap(span, r));
+}
+/**
+ * Select indexed nodes whose spans intersect any changed line range.
+ * Skips container/noise kinds. Prefers tighter (inner) symbols when sorting.
+ */
+function selectChangedSymbols(nodesByFile, hunks, limits = { maxSymbols: exports.DIFF_IMPACT_LIMITS.maxSymbols }) {
+    const picked = [];
+    for (const hunk of hunks) {
+        if (hunk.ranges.length === 0)
+            continue;
+        const nodes = nodesByFile.get(hunk.path) ?? [];
+        for (const n of nodes) {
+            if (SKIP_NODE_KINDS.has(n.kind))
+                continue;
+            if (!nodeOverlapsRanges(n, hunk.ranges))
+                continue;
+            picked.push({
+                id: n.id,
+                name: n.name,
+                kind: n.kind,
+                filePath: n.filePath,
+                startLine: n.startLine,
+                endLine: n.endLine,
+            });
+        }
+    }
+    // Prefer smaller spans (inner defs) then earlier lines — review noise control.
+    picked.sort((a, b) => (a.endLine - a.startLine) - (b.endLine - b.startLine) ||
+        a.startLine - b.startLine ||
+        a.name.localeCompare(b.name));
+    const truncated = picked.length > limits.maxSymbols;
+    return {
+        symbols: truncated ? picked.slice(0, limits.maxSymbols) : picked,
+        truncated,
+    };
+}
+function isDiffImpactUiEdge(edge) {
+    if (edge.provenance !== 'heuristic')
+        return false;
+    const m = edge.metadata;
+    const by = m?.synthesizedBy;
+    return typeof by === 'string' && exports.DIFF_IMPACT_UI_SYNTHESIZED_BY.has(by);
+}
+/**
+ * Build the capped evidence pack from hunks + graph. Specs are not included.
+ */
+function buildDiffImpactPack(graph, hunks, options = {}) {
+    const limits = { ...exports.DIFF_IMPACT_LIMITS, ...options.limits };
+    const depth = Math.max(1, Math.min(options.depth ?? 2, 5));
+    const notes = [...(options.notes ?? [])];
+    const nodesByFile = new Map();
+    for (const h of hunks) {
+        try {
+            nodesByFile.set(h.path, graph.getNodesInFile(h.path));
+        }
+        catch {
+            nodesByFile.set(h.path, []);
+            notes.push(`Could not load nodes for ${h.path}`);
+        }
+    }
+    const { symbols, truncated: symbolsTruncated } = selectChangedSymbols(nodesByFile, hunks, {
+        maxSymbols: limits.maxSymbols,
+    });
+    if (symbols.length === 0) {
+        notes.push(hunks.some((h) => h.ranges.length > 0)
+            ? 'No indexed symbols intersect the changed line ranges (index may be stale relative to the diff, or changes are non-symbol).'
+            : 'Diff had no new-side line ranges (pure deletions or empty).');
+    }
+    const symbolIds = new Set(symbols.map((s) => s.id));
+    const nameById = new Map(symbols.map((s) => [s.id, s.name]));
+    const callers = [];
+    let callersTruncated = false;
+    for (const sym of symbols) {
+        let list = [];
+        try {
+            list = graph.getCallers(sym.id, 1);
+        }
+        catch {
+            continue;
+        }
+        if (list.length > limits.maxCallersPerSymbol) {
+            callersTruncated = true;
+            list = list.slice(0, limits.maxCallersPerSymbol);
+        }
+        for (const { node, edge } of list) {
+            callers.push({
+                symbol: sym.name,
+                callerName: node.name,
+                callerFile: node.filePath,
+                line: edge.line ?? null,
+            });
+        }
+    }
+    const impactSummary = [];
+    let impactTruncated = false;
+    for (const sym of symbols) {
+        try {
+            const impact = graph.getImpactRadius(sym.id, depth);
+            const nodes = normalizeImpactNodes(impact.nodes).filter((n) => n.id !== sym.id);
+            if (nodes.length > limits.maxImpactSamples)
+                impactTruncated = true;
+            impactSummary.push({
+                symbol: sym.name,
+                affectedCount: nodes.length,
+                sampleNames: nodes.slice(0, limits.maxImpactSamples).map((n) => n.name),
+            });
+        }
+        catch {
+            impactSummary.push({ symbol: sym.name, affectedCount: 0, sampleNames: [] });
+        }
+    }
+    const uiEdges = [];
+    const seenUi = new Set();
+    let uiTruncated = false;
+    for (const sym of symbols) {
+        if (uiEdges.length >= limits.maxUiEdges) {
+            uiTruncated = true;
+            break;
+        }
+        let edges = [];
+        try {
+            edges = [
+                ...graph.getOutgoingEdges(sym.id),
+                ...graph.getIncomingEdges(sym.id),
+            ];
+        }
+        catch {
+            continue;
+        }
+        for (const edge of edges) {
+            if (!isDiffImpactUiEdge(edge))
+                continue;
+            if (!symbolIds.has(edge.source) && !symbolIds.has(edge.target))
+                continue;
+            const key = `${edge.source}>${edge.target}>${edge.kind}>${String(edge.metadata?.via ?? '')}`;
+            if (seenUi.has(key))
+                continue;
+            seenUi.add(key);
+            const m = edge.metadata;
+            const sourceName = nameById.get(edge.source) ?? graph.getNode?.(edge.source)?.name ?? edge.source;
+            const targetName = nameById.get(edge.target) ?? graph.getNode?.(edge.target)?.name ?? edge.target;
+            uiEdges.push({
+                source: edge.source,
+                sourceName,
+                target: edge.target,
+                targetName,
+                kind: edge.kind,
+                synthesizedBy: String(m?.synthesizedBy ?? ''),
+                via: typeof m?.via === 'string' ? m.via : null,
+                line: edge.line ?? null,
+            });
+            if (uiEdges.length >= limits.maxUiEdges) {
+                uiTruncated = true;
+                break;
+            }
+        }
+    }
+    return {
+        changedFiles: hunks.map((h) => h.path),
+        hunks,
+        changedSymbols: symbols,
+        callers,
+        impactSummary,
+        uiEdges,
+        truncated: {
+            symbols: symbolsTruncated,
+            callers: callersTruncated,
+            impact: impactTruncated,
+            uiEdges: uiTruncated,
+        },
+        notes,
+    };
+}
+function normalizeImpactNodes(nodes) {
+    if (Array.isArray(nodes))
+        return nodes;
+    if (nodes instanceof Map)
+        return Array.from(nodes.values());
+    return Array.from(nodes);
+}
+/**
+ * Accept either a unified `diff` string or explicit `hunks` from the agent.
+ */
+function resolveDiffImpactHunks(args) {
+    if (typeof args.diff === 'string' && args.diff.length > 0) {
+        if (args.diff.length > exports.DIFF_IMPACT_MAX_DIFF_CHARS) {
+            return {
+                hunks: [],
+                notes: [],
+                error: `\`diff\` exceeds maximum length of ${exports.DIFF_IMPACT_MAX_DIFF_CHARS} characters ` +
+                    `(got ${args.diff.length}). Pass a smaller unified diff (e.g. one PR file at a time).`,
+            };
+        }
+        return parseUnifiedDiff(args.diff);
+    }
+    if (Array.isArray(args.hunks)) {
+        const hunks = [];
+        const notes = [];
+        for (const raw of args.hunks) {
+            if (!raw || typeof raw !== 'object') {
+                notes.push('Ignored a non-object hunk entry.');
+                continue;
+            }
+            const rec = raw;
+            const path = typeof rec.path === 'string'
+                ? normalizeDiffFilePath(rec.path)
+                : typeof rec.file === 'string'
+                    ? normalizeDiffFilePath(rec.file)
+                    : '';
+            if (!path) {
+                notes.push('Ignored a hunk with no path.');
+                continue;
+            }
+            const startLine = Number(rec.startLine ?? rec.start);
+            const endLine = Number(rec.endLine ?? rec.end ?? startLine);
+            if (!Number.isFinite(startLine) || startLine < 1) {
+                notes.push(`Ignored hunk for ${path}: invalid startLine.`);
+                continue;
+            }
+            const end = Number.isFinite(endLine) && endLine >= startLine ? endLine : startLine;
+            hunks.push({ path, ranges: [{ startLine, endLine: end }] });
+        }
+        // Merge by path
+        const byPath = new Map();
+        for (const h of hunks) {
+            const list = byPath.get(h.path) ?? [];
+            list.push(...h.ranges);
+            byPath.set(h.path, list);
+        }
+        const merged = [...byPath.entries()].map(([p, ranges]) => ({
+            path: p,
+            ranges: mergeRanges(ranges),
+        }));
+        merged.sort((a, b) => a.path.localeCompare(b.path));
+        return { hunks: merged, notes };
+    }
+    return {
+        hunks: [],
+        notes: [],
+        error: 'Provide either `diff` (unified diff text) or `hunks` (array of { path, startLine, endLine }).',
+    };
+}
+//# sourceMappingURL=diff-impact.js.map

package/dist/mcp/diff-impact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-impact.js","sourceRoot":"","sources":["../../src/mcp/diff-impact.ts"],"names":[],"mappings":"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"}

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

@@ -30,6 +30,24 @@ export interface WatchdogOptions {
  * handle to stop it, or `null` when disabled or when the child can't be spawned
  * (degraded, never throws — a missing watchdog must never keep a process from
  * starting).
+ *
+ * The returned handle is process-wide and stable across
+ * {@link suspendLivenessWatchdog} re-arms — `stop()` always tears down the
+ * current generation.
  */
 export declare function installMainThreadWatchdog(options?: WatchdogOptions): WatchdogHandle | null;
+/**
+ * Suspend the armed liveness watchdog for an opaque synchronous span that
+ * cannot cooperatively yield (ArkAnalyzer Scene builds). Returns an idempotent
+ * resume function. Nested calls refcount; a `stop()` while suspended cancels
+ * the pending re-arm.
+ *
+ * No-op when nothing is armed (tests, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
+ */
+export declare function suspendLivenessWatchdog(): () => void;
+/**
+ * Run `fn` with the liveness watchdog suspended, then resume. Use for native
+ * spans with no JS yield points; prefer cooperative yielding for JS-owned loops.
+ */
+export declare function runWithoutLivenessWatchdog<T>(fn: () => T): T;
 //# sourceMappingURL=liveness-watchdog.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"liveness-watchdog.d.ts","sourceRoot":"","sources":["../../src/mcp/liveness-watchdog.ts"],"names":[],"mappings":"AAwDA,uGAAuG;AACvG,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAQ1C,qFAAqF;AACrF,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,GAAE,MAAoC,GAC7C,MAAM,CAIR;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AASD,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,IAAI,IAAI,IAAI,CAAC;CACd;AA8DD,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,GAAG,IAAI,CAgE9F"}
+{"version":3,"file":"liveness-watchdog.d.ts","sourceRoot":"","sources":["../../src/mcp/liveness-watchdog.ts"],"names":[],"mappings":"AAiEA,uGAAuG;AACvG,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAQ1C,qFAAqF;AACrF,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,GAAE,MAAoC,GAC7C,MAAM,CAIR;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AASD,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,IAAI,IAAI,IAAI,CAAC;CACd;AA8DD,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAkHD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,GAAG,IAAI,CAY9F;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,IAAI,CAqBpD;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAO5D"}

package/dist/mcp/liveness-watchdog.js

@@ -37,6 +37,8 @@ exports.PROGRESS_CAP_MULTIPLIER = exports.DEFAULT_WATCHDOG_TIMEOUT_MS = void 0;
 exports.parseWatchdogTimeoutMs = parseWatchdogTimeoutMs;
 exports.deriveCheckIntervalMs = deriveCheckIntervalMs;
 exports.installMainThreadWatchdog = installMainThreadWatchdog;
+exports.suspendLivenessWatchdog = suspendLivenessWatchdog;
+exports.runWithoutLivenessWatchdog = runWithoutLivenessWatchdog;
 /**
  * Main-thread liveness watchdog — belt-and-suspenders for #850.
  *
@@ -88,6 +90,15 @@ exports.installMainThreadWatchdog = installMainThreadWatchdog;
  * coinciding with unrelated file activity — or I/O hung beyond all reason —
  * still dies. A true wedge with no disk progress dies at the base timeout,
  * exactly as before.
+ *
+ * **Opaque native spans (`suspendLivenessWatchdog` / `runWithoutLivenessWatchdog`).**
+ * ArkAnalyzer Scene builds (`analyseByModule` / full Scene) run synchronous
+ * native work on this thread with no JS yield points — a single module's BODIES
+ * load can exceed the 60s window while the process is healthy. Cooperative
+ * yielding can't help (the stall is between callbacks, inside native code), and
+ * disk-progress deferral's hard cap is too short for multi-module Harmony
+ * indexes. Those spans suspend the watchdog for the duration and re-arm after;
+ * prefer yielding for any JS-owned loop.
  */
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
@@ -187,14 +198,42 @@ process.stdin.on('error', () => process.exit(0)); // pipe broke -> parent gone
 process.stdin.resume();
 `;
 /**
- * Install the main-thread liveness watchdog for a long-lived process. Returns a
- * handle to stop it, or `null` when disabled or when the child can't be spawned
- * (degraded, never throws — a missing watchdog must never keep a process from
- * starting).
+ * Process-wide armed watchdog. `install` / `suspend` / `stop` all mutate this
+ * so a handle returned before a suspend+re-arm still stops the *current*
+ * generation (CLI supervision and the MCP server hold the handle across
+ * ArkTS Scene builds that suspend).
  */
-function installMainThreadWatchdog(options = {}) {
-    if (isEnvTruthy(process.env.HOMEGRAPH_NO_WATCHDOG))
-        return null;
+let active = null;
+/** Nested `suspendLivenessWatchdog` depth; disarm only at 0→1, re-arm at 1→0. */
+let suspendDepth = 0;
+/** Options to re-arm with after the outermost resume; cleared by `stop()`. */
+let optionsWhileSuspended = null;
+/** Stable handle: always stops whatever generation is current (or pending re-arm). */
+const SHARED_HANDLE = {
+    stop() {
+        suspendDepth = 0;
+        optionsWhileSuspended = null;
+        disarmActive();
+    },
+};
+function copyOptions(options) {
+    return {
+        progressPaths: options.progressPaths ? [...options.progressPaths] : undefined,
+    };
+}
+function disarmActive() {
+    if (!active)
+        return;
+    try {
+        active.disarm();
+    }
+    catch {
+        /* best-effort teardown */
+    }
+    active = null;
+}
+/** Spawn the watchdog child; returns a disarm fn, or null on spawn failure. */
+function armWatchdog(options) {
     const timeoutMs = parseWatchdogTimeoutMs(process.env.HOMEGRAPH_WATCHDOG_TIMEOUT_MS);
     const checkMs = deriveCheckIntervalMs(timeoutMs);
     const capMs = timeoutMs * exports.PROGRESS_CAP_MULTIPLIER;
@@ -247,21 +286,94 @@ function installMainThreadWatchdog(options = {}) {
     catch { /* ignore */ }
     debug(`armed (child pid ${child.pid ?? '?'}): timeoutMs=${timeoutMs} checkMs=${checkMs} progressPaths=${progressPaths.length}`);
     let stopped = false;
-    return {
-        stop() {
-            if (stopped)
-                return;
-            stopped = true;
-            clearInterval(heartbeat);
-            try {
-                stdin.end();
-            }
-            catch { /* ignore */ } // EOF -> child exits cleanly
-            try {
-                child.kill();
-            }
-            catch { /* ignore */ } // belt-and-suspenders
-        },
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(heartbeat);
+        try {
+            stdin.end();
+        }
+        catch { /* ignore */ } // EOF -> child exits cleanly
+        try {
+            child.kill();
+        }
+        catch { /* ignore */ } // belt-and-suspenders
     };
 }
+function rearmFromOptions(options) {
+    const disarm = armWatchdog(options);
+    if (!disarm)
+        return;
+    active = { disarm, options: copyOptions(options) };
+}
+/**
+ * Install the main-thread liveness watchdog for a long-lived process. Returns a
+ * handle to stop it, or `null` when disabled or when the child can't be spawned
+ * (degraded, never throws — a missing watchdog must never keep a process from
+ * starting).
+ *
+ * The returned handle is process-wide and stable across
+ * {@link suspendLivenessWatchdog} re-arms — `stop()` always tears down the
+ * current generation.
+ */
+function installMainThreadWatchdog(options = {}) {
+    if (isEnvTruthy(process.env.HOMEGRAPH_NO_WATCHDOG))
+        return null;
+    // Replace any prior generation (including a mid-suspend pending re-arm).
+    suspendDepth = 0;
+    optionsWhileSuspended = null;
+    disarmActive();
+    const disarm = armWatchdog(options);
+    if (!disarm)
+        return null;
+    active = { disarm, options: copyOptions(options) };
+    return SHARED_HANDLE;
+}
+/**
+ * Suspend the armed liveness watchdog for an opaque synchronous span that
+ * cannot cooperatively yield (ArkAnalyzer Scene builds). Returns an idempotent
+ * resume function. Nested calls refcount; a `stop()` while suspended cancels
+ * the pending re-arm.
+ *
+ * No-op when nothing is armed (tests, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
+ */
+function suspendLivenessWatchdog() {
+    suspendDepth++;
+    if (suspendDepth === 1 && active) {
+        optionsWhileSuspended = active.options;
+        disarmActive();
+        debug('suspended for opaque sync span');
+    }
+    let resumed = false;
+    return () => {
+        if (resumed)
+            return;
+        resumed = true;
+        if (suspendDepth <= 0)
+            return;
+        suspendDepth--;
+        if (suspendDepth > 0)
+            return;
+        if (optionsWhileSuspended) {
+            const opts = optionsWhileSuspended;
+            optionsWhileSuspended = null;
+            rearmFromOptions(opts);
+            debug('resumed after opaque sync span');
+        }
+    };
+}
+/**
+ * Run `fn` with the liveness watchdog suspended, then resume. Use for native
+ * spans with no JS yield points; prefer cooperative yielding for JS-owned loops.
+ */
+function runWithoutLivenessWatchdog(fn) {
+    const resume = suspendLivenessWatchdog();
+    try {
+        return fn();
+    }
+    finally {
+        resume();
+    }
+}
 //# sourceMappingURL=liveness-watchdog.js.map

package/dist/mcp/liveness-watchdog.js.map

@@ -1 +1 @@
-{"version":3,"file":"liveness-watchdog.js","sourceRoot":"","sources":["../../src/mcp/liveness-watchdog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"liveness-watchdog.js","sourceRoot":"","sources":["../../src/mcp/liveness-watchdog.ts"],"names":[],"mappings":"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"}

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

@@ -4,6 +4,6 @@
  * Single source of truth for agent-facing tool guidance (issue #529).
  * Edit here — not installer prompts or eval harness prompts.
  */
-export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 when to call\n\nHomeGraph is a **local structural index of THIS repo**: symbols + call/import/extends edges + files. Use it only when the answer needs that graph.\n\n## Call HomeGraph (closed set)\n\nUse `homegraph_explore` (primary) when **all** of these hold:\n\n1. The evidence lives **in this repository's source** (not an external SDK manual).\n2. You need **structure**: definition location, who calls whom, how A reaches B, multi-file wiring, or in-repo import/usage of a named API/`@kit` module.\n3. You can put **concrete names** in `query` \u2014 symbol, `Type.member`, file basename, or `@kit\u2026` (skip `homegraph_search` when names are already known).\n\nTypical fits:\n\n- How a **feature in this repo** is wired (mechanism / cross-file / click\u2192handler flow)\n- Callers / callees / blast radius of a **named** symbol\n- What a **named component/method** does (include the name; one explore is enough)\n- In-repo usages of an imported API (not the official feature catalog)\n\n**One explore with names** beats search\u2192explore\u2192node\u2192grep\u2192read. Treat returned line-numbered source as already Read. After a full explore \u2014 **answer**; do not re-verify with grep/read/node for the same symbols. Busy/partial \u2192 retry that **same** explore once.\n\n## Do not call HomeGraph otherwise\n\nIf the question is **outside the set above**, do **not** open any `homegraph_*` tool \u2014 use Read / Grep / Glob / SDK docs. HomeGraph is not a general Q&A layer; forcing it on the wrong shape costs time and tokens and often lowers quality.\n\n## Tool roles\n\n| Tool | Role |\n|------|------|\n| **homegraph_explore** | Primary for the closed set above |\n| homegraph_node | One known symbol body (or indexed file) after explore named it |\n| homegraph_callers / callees | Compact edge lists for a named symbol |\n| homegraph_search | Rare \u2014 unknown spelling only |\n| homegraph_files | Folder tree only |\n\n## Tips\n\n- **Deadline / partial** \u2014 success-shaped; retry ONE explore with the same names. Do not abandon to grep for those symbols.\n- **Staleness banner** \u2014 Read only the listed edited files.\n- **Not indexed** \u2014 built-in tools; user runs `homegraph init` \u2014 you do not.\n";
+export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 when to call\n\nHomeGraph is a **local structural index of THIS repo**: symbols + call/import/extends edges + files. Use it only when the answer needs that graph.\n\n## Call HomeGraph (closed set)\n\nUse `homegraph_explore` (primary) when **all** of these hold:\n\n1. The evidence lives **in this repository's source** (not an external SDK manual).\n2. You need **structure**: definition location, who calls whom, how A reaches B, multi-file wiring, or in-repo import/usage of a named API/`@kit` module.\n3. You can put **concrete names** in `query` \u2014 symbol, `Type.member`, file basename, or `@kit\u2026` (skip `homegraph_search` when names are already known).\n\nTypical fits:\n\n- How a **feature in this repo** is wired (mechanism / cross-file / click\u2192handler flow)\n- Callers / callees / blast radius of a **named** symbol\n- What a **named component/method** does (include the name; one explore is enough)\n- In-repo usages of an imported API (not the official feature catalog)\n\n**One explore with names** beats search\u2192explore\u2192node\u2192grep\u2192read. Treat returned line-numbered source as already Read. After a full explore \u2014 **answer**; do not re-verify with grep/read/node for the same symbols. Busy/partial \u2192 retry that **same** explore once.\n\n## Do not call HomeGraph otherwise\n\nIf the question is **outside the set above**, do **not** open any `homegraph_*` tool \u2014 use Read / Grep / Glob / SDK docs. HomeGraph is not a general Q&A layer; forcing it on the wrong shape costs time and tokens and often lowers quality.\n\n## Tool roles\n\n| Tool | Role |\n|------|------|\n| **homegraph_explore** | Primary for the closed set above |\n| homegraph_diff_impact | PR/diff review: unified `diff` or `hunks` \u2192 changed symbols (line\u2229span) + capped callers/impact/UI edges |\n| homegraph_node | One known symbol body (or indexed file) after explore named it |\n| homegraph_callers / callees | Compact edge lists for a named symbol |\n| homegraph_impact | Blast radius for one named symbol (not a whole PR) |\n| homegraph_search | Rare \u2014 unknown spelling only |\n| homegraph_files | Folder tree only |\n\n## Tips\n\n- **Deadline / partial** \u2014 success-shaped; retry ONE explore with the same names. Do not abandon to grep for those symbols.\n- **Staleness banner** \u2014 Read only the listed edited files.\n- **Not indexed** \u2014 built-in tools; user runs `homegraph init` \u2014 you do not.\n";
 export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 per-project (pass projectPath)\n\nHomeGraph indexes a codebase into a symbol graph. Call it **only** for in-repo structural / flow / usage questions on a project that has `.homegraph/`. Pass that project as `projectPath`.\n\n- Fits the closed set (structure, callers, wiring, named symbol/file) \u2192 `homegraph_explore`\n- Anything else \u2192 Read/Grep/Glob \u2014 **do not call homegraph_***\n- No index \u2192 Read/Grep/Glob; user runs `homegraph init` if they want indexing\n";
 //# sourceMappingURL=server-instructions.d.ts.map