@levnikolaevich/hex-line-mcp 1.15.0 → 1.16.0

package/README.md

@@ -39,7 +39,7 @@ Advanced / occasional:
 | `outline` | AST-based structural overview with hash anchors via tree-sitter WASM. Supports JavaScript/TypeScript, Python, C#, PHP, and fence-aware markdown headings | 95% token reduction, direct edit anchors |
 | `verify` | Check if held checksums / revision are still current | Staleness check without full re-read |
 | `inspect_path` | Unified file-or-directory inspection | Minimal tree discovery by default, deeper traversal on demand |
-| `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff |
+| `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff with risk/provenance preview |
 | `bulk_replace` | Search-and-replace across multiple files inside an explicit root path | Compact summary (default) or capped diffs via `format`, dry_run, max_files |
 
 ### Hooks (SessionStart + PreToolUse + PostToolUse)
@@ -86,6 +86,15 @@ npm run lint
 npm run check
 ```
 
+For the full MCP workspace regression pass from the repository root, run the package test scripts explicitly:
+
+```bash
+npm --prefix mcp --workspace hex-common test
+npm --prefix mcp --workspace hex-line-mcp test
+npm --prefix mcp --workspace hex-graph-mcp test
+npm --prefix mcp --workspace hex-ssh-mcp test:all
+```
+
 Maintainers can also run the internal scenario harness when they want reproducible repo-local workflow regressions:
 
 ```bash
@@ -93,7 +102,9 @@ npm run scenarios -- --repo /path/to/repo
 npm run scenarios:diagnostic -- --repo /path/to/repo
 ```
 
-Comparative built-in vs hex-line benchmarks are maintained outside this package.
+The diagnostics run reports graph payload overhead and auto-refresh telemetry. Read those rows as engineering diagnostics, not as a compression score.
+
+Comparative built-in vs hex-line benchmarks are maintained outside this package. External-baseline comparisons must reuse the same scenario suite and correctness contract before making broader claims.
 
 ### Optional Graph Enrichment
 
@@ -103,8 +114,16 @@ If a project already has `.hex-skills/codegraph/index.db`, `hex-line` automatica
 - Graph enrichment is project-deterministic. `hex-line` only uses the graph database that belongs to the resolved current project scope.
 - Nested projects do not inherit graph hints from a parent repo index once a nested project boundary is detected.
 - `better-sqlite3` is optional. If it is unavailable, `hex-line` still works without graph hints.
+- `read_file` only emits the top-line `Graph:` header in `verbosity=full`.
+- `grep_search` only emits line-level graph annotations in `output=content` when `editReady=true`. `summary`, `files`, `count`, and discovery-only content search stay graph-free.
+- Grep annotations are capped and count-suffixes are deduplicated so the first label keeps the counts and later labels stay short.
 - `read_file`, `outline`, and `grep_search` stay compact: they only surface high-signal local facts such as `api`, framework entrypoints, callers, flow, and clone hints.
 - `edit_file` and `changes` surface the deeper review layer: external callers, downstream return/property flow, clone peers, public API risk, framework entrypoint risk, and same-name sibling warnings when present.
+- Both tools now expose a short top-level preview before the detailed sections: `payload_sections`, `graph_enrichment`, count fields, and `provenance_summary`.
+- Stale graph data never changes correctness. `hex-line` suppresses stale hints, schedules a best-effort `reindexFile(...)` for a stale file, and escalates to one background `indexProject(...)` when several files go stale inside the burst window.
+- The threshold-crossing file still keeps its point refresh so a short stale burst does not create a blind gap before the project refresh finishes.
+- `edit_file` may still use stale graph context as same-response advisory metadata when the file was just edited, but stale graph never gates the edit protocol itself.
+- `npm run scenarios:diagnostic -- --with-graph` prints graph payload overhead plus an auto-refresh probe line with `suppressions`, `file_refresh`, `project_refresh`, and `threshold_hits`.
 
 `hex-line` does not read `hex-graph` internals directly anymore. The integration uses a small read-only contract exposed by `hex-graph-mcp`:
 
@@ -224,6 +243,11 @@ Result footer includes:
 - `reason: ...` as the canonical machine-readable cause for the current status
 - `revision: ...`
 - `file: ...`
+- `summary: ...` with edited line span / diff counts on successful edits
+- `payload_sections: ...` so callers know which detailed sections follow
+- `graph_enrichment: available | unavailable`
+- `semantic_impact_count: ...`, `semantic_fact_count: ...`, and `clone_warning_count: ...` when graph-backed review data is available
+- `provenance_summary: ...` for the edit protocol + optional graph source
 - `changed_ranges: ...` when relevant
 - `recovery_ranges: ...` with the narrowest recommended `read_file` ranges for retry
 - `next_action: ...` as the canonical immediate choice: `apply_retry_edit`, `apply_retry_batch`, or `reread_then_retry`
@@ -233,7 +257,7 @@ Result footer includes:
 - `retry_edits: ...` on conservative batch conflicts when every conflicted edit can be retried directly
 - `suggested_read_call: ...` when rereading is the safest next step
 - `retry_plan: ...` with a compact machine-readable next-call plan
-- `summary: ...` and `snippet: ...` instead of long prose blocks
+- `summary: ...` and `snippet: ...` instead of long prose blocks on conflicts
 - `edit_conflicts: N` on conservative multi-edit preflight conflicts
 
 ### write_file

package/dist/server.mjs

@@ -103,7 +103,7 @@ async function checkForUpdates(packageName, currentVersion) {
 }
 
 // lib/read.mjs
-import { statSync as statSync4 } from "node:fs";
+import { statSync as statSync5 } from "node:fs";
 
 // lib/security.mjs
 import { realpathSync, statSync as statSync2, existsSync, openSync, readSync, closeSync } from "node:fs";
@@ -307,7 +307,7 @@ function validateWritePath(filePath) {
 }
 
 // lib/graph-enrich.mjs
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync2, statSync as statSync3 } from "node:fs";
 import { join as join3, dirname as dirname2, relative } from "node:path";
 import { createRequire } from "node:module";
 var REQUIRED_VIEWS = [
@@ -331,6 +331,20 @@ var FACT_PRIORITY = /* @__PURE__ */ new Map([
 ]);
 var _dbs = /* @__PURE__ */ new Map();
 var _driverUnavailable = false;
+var _reindexUnavailable = false;
+var _reindexLoader = null;
+var _pendingRefreshes = /* @__PURE__ */ new Map();
+var _pendingProjectRefreshes = /* @__PURE__ */ new Map();
+var _freshnessCache = /* @__PURE__ */ new Map();
+var _projectRefreshWindows = /* @__PURE__ */ new Map();
+var _graphRefreshStats = {
+  staleSuppressions: 0,
+  fileRefreshScheduled: 0,
+  fileRefreshCompleted: 0,
+  projectRefreshThresholdHits: 0,
+  projectRefreshScheduled: 0,
+  projectRefreshCompleted: 0
+};
 var MAX_PROJECT_ROOT_ASCENT = 25;
 var PROJECT_BOUNDARY_MARKERS = [
   "package.json",
@@ -343,14 +357,24 @@ var PROJECT_BOUNDARY_MARKERS = [
   "deno.jsonc",
   ".git"
 ];
-function getGraphDB(filePath) {
+var FRESHNESS_TOLERANCE_MS = 1;
+var FRESHNESS_CACHE_TTL_MS = 1e3;
+var PROJECT_REFRESH_THRESHOLD = 3;
+var PROJECT_REFRESH_WINDOW_MS = 2e3;
+function getGraphDB(filePath, { allowStale = false } = {}) {
   if (_driverUnavailable) return null;
   try {
     const projectRoot = findProjectRoot(filePath);
     if (!projectRoot) return null;
     const dbPath = join3(projectRoot, ".hex-skills/codegraph", "index.db");
     if (!existsSync2(dbPath)) return null;
-    if (_dbs.has(dbPath)) return _dbs.get(dbPath);
+    if (_dbs.has(dbPath)) {
+      const cached = _dbs.get(dbPath);
+      if (isFilePathFresh(cached, projectRoot, filePath)) return cached;
+      if (allowStale) return cached;
+      _graphRefreshStats.staleSuppressions++;
+      return null;
+    }
     const require2 = createRequire(import.meta.url);
     const Database = require2("better-sqlite3");
     const db = new Database(dbPath, { readonly: true });
@@ -359,7 +383,10 @@ function getGraphDB(filePath) {
       return null;
     }
     _dbs.set(dbPath, db);
-    return db;
+    if (isFilePathFresh(db, projectRoot, filePath)) return db;
+    if (allowStale) return db;
+    _graphRefreshStats.staleSuppressions++;
+    return null;
   } catch {
     _driverUnavailable = true;
     return null;
@@ -402,6 +429,37 @@ function compactSymbolCounts(node) {
   if ((node.clone_sibling_count || 0) > 0) parts.push(`clone ${node.clone_sibling_count}`);
   return parts;
 }
+function lineFactLabel(fact) {
+  switch (fact.fact_kind) {
+    case "public_api":
+      return "api";
+    case "framework_entrypoint":
+      return fact.related_display_name ? `entry:${fact.related_display_name}` : "entry";
+    case "definition":
+      return shortKind(fact.kind);
+    case "callee":
+      return fact.related_display_name ? `callee:${fact.related_display_name}` : "callee";
+    case "caller":
+      return fact.related_display_name ? `caller:${fact.related_display_name}` : "caller";
+    case "outgoing_flow":
+      return `flow-out:${fact.target_anchor_kind || "?"}`;
+    case "incoming_flow":
+      return `flow-in:${fact.target_anchor_kind || "?"}`;
+    case "through_flow":
+      return "flow-through";
+    case "clone":
+      return "clone";
+    case "hotspot":
+      return "hotspot";
+    default:
+      return fact.fact_kind;
+  }
+}
+function formatLineFact(fact, { includeCounts = true } = {}) {
+  const countParts = includeCounts ? compactSymbolCounts(fact) : [];
+  const suffix = countParts.length > 0 ? ` | ${countParts.join(" | ")}` : "";
+  return `[${lineFactLabel(fact)}${suffix}]`;
+}
 function symbolAnnotation(db, file, name) {
   try {
     const node = db.prepare(
@@ -419,6 +477,18 @@ function symbolAnnotation(db, file, name) {
     return null;
   }
 }
+function ensureGraphFreshForFile(db, absoluteFilePath) {
+  if (!db) return false;
+  try {
+    const projectRoot = findProjectRoot(absoluteFilePath);
+    if (!projectRoot) return true;
+    const fresh = isFilePathFresh(db, projectRoot, absoluteFilePath);
+    if (!fresh) _graphRefreshStats.staleSuppressions++;
+    return fresh;
+  } catch {
+    return true;
+  }
+}
 function fileAnnotations(db, file, { startLine = null, endLine = null, limit = 8 } = {}) {
   try {
     const hasRange = Number.isInteger(startLine) && Number.isInteger(endLine);
@@ -457,34 +527,6 @@ function fileAnnotations(db, file, { startLine = null, endLine = null, limit = 8
     return [];
   }
 }
-function formatLineFact(fact) {
-  const countParts = compactSymbolCounts(fact);
-  const suffix = countParts.length > 0 ? ` | ${countParts.join(" | ")}` : "";
-  switch (fact.fact_kind) {
-    case "public_api":
-      return `[api${suffix}]`;
-    case "framework_entrypoint":
-      return fact.related_display_name ? `[entry:${fact.related_display_name}${suffix}]` : `[entry${suffix}]`;
-    case "definition":
-      return `[${shortKind(fact.kind)}${suffix}]`;
-    case "callee":
-      return fact.related_display_name ? `[callee:${fact.related_display_name}${suffix}]` : `[callee${suffix}]`;
-    case "caller":
-      return fact.related_display_name ? `[caller:${fact.related_display_name}${suffix}]` : `[caller${suffix}]`;
-    case "outgoing_flow":
-      return `[flow-out:${fact.target_anchor_kind || "?"}${suffix}]`;
-    case "incoming_flow":
-      return `[flow-in:${fact.target_anchor_kind || "?"}${suffix}]`;
-    case "through_flow":
-      return `[flow-through${suffix}]`;
-    case "clone":
-      return `[clone${suffix}]`;
-    case "hotspot":
-      return `[hotspot${suffix}]`;
-    default:
-      return `[${fact.fact_kind}${suffix}]`;
-  }
-}
 function priorityForFact(factKind) {
   return FACT_PRIORITY.get(factKind) ?? 99;
 }
@@ -513,10 +555,14 @@ function matchAnnotation(db, file, line) {
     facts.sort((left, right) => priorityForFact(left.fact_kind) - priorityForFact(right.fact_kind));
     const labels = [];
     const seenKinds = /* @__PURE__ */ new Set();
+    const seenCountKeys = /* @__PURE__ */ new Set();
     for (const fact of facts) {
       if (seenKinds.has(fact.fact_kind)) continue;
       seenKinds.add(fact.fact_kind);
-      labels.push(formatLineFact(fact));
+      const countKey = compactSymbolCounts(fact).join("|");
+      const includeCounts = countKey.length > 0 && !seenCountKeys.has(countKey);
+      if (includeCounts) seenCountKeys.add(countKey);
+      labels.push(formatLineFact(fact, { includeCounts }));
       if (labels.length >= 3) break;
     }
     return labels.join(" ");
@@ -639,9 +685,140 @@ function findProjectRoot(filePath) {
   }
   return null;
 }
+function freshnessCacheKey(projectRoot, relativeFile) {
+  return `${projectRoot}:${relativeFile}`;
+}
+function normalizeRelativeFile(projectRoot, filePath) {
+  const relFile = relative(projectRoot, filePath).replace(/\\/g, "/");
+  if (!relFile || relFile.startsWith("..")) return null;
+  return relFile;
+}
+function lookupIndexedMtime(db, relativeFile) {
+  try {
+    const row = db.prepare("SELECT mtime FROM files WHERE path = ? LIMIT 1").get(relativeFile);
+    return row?.mtime ?? null;
+  } catch {
+    return null;
+  }
+}
+function isFilePathFresh(db, projectRoot, filePath) {
+  let stat;
+  try {
+    stat = statSync3(filePath);
+  } catch {
+    return false;
+  }
+  if (!stat.isFile()) return true;
+  const relativeFile = normalizeRelativeFile(projectRoot, filePath);
+  if (!relativeFile) return true;
+  const cacheKey = freshnessCacheKey(projectRoot, relativeFile);
+  const cached = _freshnessCache.get(cacheKey);
+  if (cached && Date.now() - cached.checkedAt < FRESHNESS_CACHE_TTL_MS && Math.abs(cached.actualMtime - stat.mtimeMs) < FRESHNESS_TOLERANCE_MS) {
+    return cached.fresh;
+  }
+  const indexedMtime = lookupIndexedMtime(db, relativeFile);
+  const fresh = indexedMtime !== null && Math.abs(indexedMtime - stat.mtimeMs) < FRESHNESS_TOLERANCE_MS;
+  _freshnessCache.set(cacheKey, {
+    checkedAt: Date.now(),
+    actualMtime: stat.mtimeMs,
+    indexedMtime,
+    fresh
+  });
+  if (!fresh) scheduleGraphRefresh(projectRoot, relativeFile, cacheKey);
+  return fresh;
+}
+function scheduleGraphRefresh(projectRoot, relativeFile, cacheKey) {
+  if (_reindexUnavailable || _pendingRefreshes.has(cacheKey)) return;
+  const triggeredProjectRefresh = recordStaleFile(projectRoot, relativeFile);
+  if (triggeredProjectRefresh) {
+    _graphRefreshStats.projectRefreshThresholdHits++;
+    scheduleProjectGraphRefresh(projectRoot);
+  }
+  if (_pendingProjectRefreshes.has(projectRoot) && !triggeredProjectRefresh) return;
+  const refresh = (async () => {
+    const indexer = await loadGraphIndexer();
+    if (!indexer?.reindexFile) return;
+    try {
+      await indexer.reindexFile(projectRoot, relativeFile);
+    } catch {
+    } finally {
+      clearProjectDBCache(projectRoot);
+      _freshnessCache.delete(cacheKey);
+      _graphRefreshStats.fileRefreshCompleted++;
+    }
+  })();
+  _graphRefreshStats.fileRefreshScheduled++;
+  _pendingRefreshes.set(cacheKey, refresh);
+  void refresh.finally(() => {
+    _pendingRefreshes.delete(cacheKey);
+  });
+}
+function recordStaleFile(projectRoot, relativeFile) {
+  const now = Date.now();
+  let windowState = _projectRefreshWindows.get(projectRoot);
+  if (!windowState || now - windowState.startedAt > PROJECT_REFRESH_WINDOW_MS) {
+    windowState = { startedAt: now, files: /* @__PURE__ */ new Set() };
+    _projectRefreshWindows.set(projectRoot, windowState);
+  }
+  windowState.files.add(relativeFile);
+  return windowState.files.size >= PROJECT_REFRESH_THRESHOLD;
+}
+function clearProjectFreshness(projectRoot) {
+  const prefix = `${projectRoot}::`;
+  for (const key of _freshnessCache.keys()) {
+    if (key.startsWith(prefix)) _freshnessCache.delete(key);
+  }
+}
+function clearProjectDBCache(projectRoot) {
+  const dbPath = join3(projectRoot, ".hex-skills/codegraph", "index.db");
+  const db = _dbs.get(dbPath);
+  if (!db) return;
+  try {
+    db.close();
+  } catch {
+  }
+  _dbs.delete(dbPath);
+}
+function scheduleProjectGraphRefresh(projectRoot) {
+  if (_reindexUnavailable || _pendingProjectRefreshes.has(projectRoot)) return;
+  const refresh = (async () => {
+    const indexer = await loadGraphIndexer();
+    if (!indexer?.indexProject) return;
+    try {
+      await indexer.indexProject(projectRoot);
+    } catch {
+    } finally {
+      clearProjectDBCache(projectRoot);
+      clearProjectFreshness(projectRoot);
+      _projectRefreshWindows.delete(projectRoot);
+      _graphRefreshStats.projectRefreshCompleted++;
+    }
+  })();
+  _graphRefreshStats.projectRefreshScheduled++;
+  _pendingProjectRefreshes.set(projectRoot, refresh);
+  void refresh.finally(() => {
+    _pendingProjectRefreshes.delete(projectRoot);
+  });
+}
+async function loadGraphIndexer() {
+  if (_reindexUnavailable) return null;
+  if (_reindexLoader) return _reindexLoader;
+  _reindexLoader = (async () => {
+    try {
+      const mod = await import(new URL("../../hex-graph-mcp/lib/indexer.mjs", import.meta.url));
+      const reindexFile = typeof mod.reindexFile === "function" ? mod.reindexFile : null;
+      const indexProject = typeof mod.indexProject === "function" ? mod.indexProject : null;
+      if (reindexFile || indexProject) return { reindexFile, indexProject };
+    } catch {
+    }
+    _reindexUnavailable = true;
+    return null;
+  })();
+  return _reindexLoader;
+}
 
 // lib/snapshot.mjs
-import { statSync as statSync3 } from "node:fs";
+import { statSync as statSync4 } from "node:fs";
 import { diffLines } from "diff";
 
 // ../hex-common/src/text-protocol/hash.mjs
@@ -942,7 +1119,7 @@ function rememberSnapshot(filePath, input, meta = {}) {
 }
 function readSnapshot(filePath) {
   pruneExpired();
-  const stat = statSync3(filePath);
+  const stat = statSync4(filePath);
   const latest = latestByFile.get(filePath);
   if (latest && latest.mtimeMs === stat.mtimeMs && latest.size === stat.size) {
     touchFile(filePath);
@@ -1219,7 +1396,7 @@ function buildContinuation({ nextOffset, limit }) {
 function readFile2(filePath, opts = {}) {
   filePath = normalizePath(filePath);
   const real = validatePath(filePath);
-  const stat = statSync4(real);
+  const stat = statSync5(real);
   if (stat.isDirectory()) {
     throw new Error(`READ_FILE_EXPECTS_FILE: ${filePath} is a directory. Use inspect_path for directory trees and path discovery.`);
   }
@@ -1256,7 +1433,7 @@ function readFile2(filePath, opts = {}) {
     if (db && relFile) {
       const visibleStart = normalizedRanges.length > 0 ? Math.min(...normalizedRanges.map((range) => range.startLine)) : 1;
       const visibleEnd = normalizedRanges.length > 0 ? Math.max(...normalizedRanges.map((range) => range.endLine)) : total;
-      const annos = fileAnnotations(db, relFile, { startLine: visibleStart, endLine: visibleEnd, limit: 6 });
+      const annos = fileAnnotations(db, relFile, { startLine: visibleStart, endLine: visibleEnd, limit: 4 });
       if (annos.length > 0) {
         const items = annos.map((a) => {
           const parts = [];
@@ -1346,7 +1523,7 @@ ${serializedBlocks.join("\n\n")}`.trim();
 }
 
 // lib/edit.mjs
-import { statSync as statSync5, writeFileSync } from "node:fs";
+import { statSync as statSync6, writeFileSync } from "node:fs";
 import { diffLines as diffLines2 } from "diff";
 
 // lib/edit-resolution.mjs
@@ -1870,6 +2047,16 @@ function deriveNextAction({ retryEdit = null, retryEdits = null, suggestedReadCa
   if (suggestedReadCall) return ACTION.REREAD_THEN_RETRY;
   return ACTION.INSPECT_SNIPPET;
 }
+function summarizeChangedSpan(minLine, maxLine) {
+  return Number.isFinite(minLine) && Number.isFinite(maxLine) && minLine !== Infinity && maxLine > 0 ? `${minLine}-${maxLine}` : "unknown";
+}
+function countDiffEntries(fullDiff) {
+  if (!fullDiff) return 0;
+  return fullDiff.split("\n").filter((line) => /^[+-]\d+\|/.test(line)).length;
+}
+function payloadSections(sections) {
+  return sections.length > 0 ? sections.join(",") : "summary_only";
+}
 function buildRetryEdit(edit, lines, options = {}) {
   const retryChecksum = options.retryChecksum || null;
   if (edit.set_line) {
@@ -2581,14 +2768,26 @@ ${snip.text}`;
       }
     }
   }
+  const diffEntryCount = countDiffEntries(fullDiff);
+  const changedSpan = summarizeChangedSpan(minLine, maxLine);
   if (opts.dryRun) {
     let msg2 = `status: ${autoRebased ? STATUS.AUTO_REBASED : STATUS.OK}
 reason: ${REASON.DRY_RUN_PREVIEW}
 revision: ${currentSnapshot.revision}
-file: ${currentSnapshot.fileChecksum}
-Dry run: ${filePath} would change (${lines.length} lines)`;
+file: ${currentSnapshot.fileChecksum}`;
     if (staleRevision && hasBaseSnapshot) msg2 += `
 changed_ranges: ${describeChangedRanges(changedRanges)}`;
+    msg2 += `
+summary: lines_changed=${changedSpan} diff_entries=${diffEntryCount} lines_after=${lines.length}`;
+    msg2 += `
+payload_sections: ${payloadSections(displayDiff ? ["diff"] : [])}`;
+    msg2 += "\ngraph_enrichment: unavailable";
+    msg2 += "\nsemantic_impact_count: 0";
+    msg2 += "\nsemantic_fact_count: 0";
+    msg2 += "\nclone_warning_count: 0";
+    msg2 += "\nprovenance_summary: edit_protocol=snapshot+anchors graph=unavailable";
+    msg2 += `
+Dry run: ${filePath} would change (${lines.length} lines)`;
     if (displayDiff) msg2 += `
 
 Diff:
@@ -2598,7 +2797,7 @@ ${displayDiff}
     return msg2;
   }
   writeFileSync(real, content, "utf-8");
-  const nextStat = statSync5(real);
+  const nextStat = statSync6(real);
   const nextSnapshot = rememberSnapshot(real, content, { mtimeMs: nextStat.mtimeMs, size: nextStat.size });
   let msg = `status: ${autoRebased ? STATUS.AUTO_REBASED : STATUS.OK}
 reason: ${autoRebased ? REASON.EDIT_AUTO_REBASED : REASON.EDIT_APPLIED}
@@ -2613,6 +2812,10 @@ changed_ranges: ${describeChangedRanges(changedRanges)}`;
 remapped_refs:
 ${remaps.map(({ from, to }) => `${from} -> ${to}`).join("\n")}`;
   }
+  let hasPostEditBlock = false;
+  let graphEnrichment = "unavailable";
+  let semanticImpacts = [];
+  let cloneWarnings = [];
   msg += `
 Updated ${filePath} (${lines.length} lines)`;
   if (fullDiff && minLine <= maxLine) {
@@ -2629,18 +2832,20 @@ Updated ${filePath} (${lines.length} lines)`;
           trailing_newline: nextSnapshot.trailingNewline
         }
       });
+      hasPostEditBlock = true;
       msg += `
 
 ${serializeReadBlock(block)}`;
     }
   }
   try {
-    const db = getGraphDB(real);
+    const db = getGraphDB(real, { allowStale: true });
     const relFile = db ? getRelativePath(real) : null;
     if (db && relFile && fullDiff && minLine <= maxLine) {
-      const impacts = semanticImpact(db, relFile, minLine, maxLine);
-      if (impacts.length > 0) {
-        const sections = impacts.map((impact) => {
+      graphEnrichment = "available";
+      semanticImpacts = semanticImpact(db, relFile, minLine, maxLine);
+      if (semanticImpacts.length > 0) {
+        const sections = semanticImpacts.map((impact) => {
           const totals = [];
           if (impact.counts.publicApi > 0) totals.push("public API");
           if (impact.counts.frameworkEntrypoints > 0) totals.push(`${impact.counts.frameworkEntrypoints} framework entrypoint`);
@@ -2668,16 +2873,35 @@ ${serializeReadBlock(block)}`;
 \u26A0 Semantic impact:
 ${sections.join("\n")}`;
       }
-      const clones = cloneWarning(db, relFile, minLine, maxLine);
-      if (clones.length > 0) {
-        const list = clones.map((c) => `${c.file}:${c.line}`).join(", ");
+      cloneWarnings = cloneWarning(db, relFile, minLine, maxLine);
+      if (cloneWarnings.length > 0) {
+        const list = cloneWarnings.map((c) => `${c.file}:${c.line}`).join(", ");
         msg += `
 
-\u26A0 ${clones.length} clone(s): ${list}`;
+\u26A0 ${cloneWarnings.length} clone(s): ${list}`;
       }
     }
   } catch {
   }
+  const payloadKinds = [];
+  if (hasPostEditBlock) payloadKinds.push("post_edit");
+  if (semanticImpacts.length > 0) payloadKinds.push("semantic_impact");
+  if (cloneWarnings.length > 0) payloadKinds.push("clone_warning");
+  if (displayDiff) payloadKinds.push("diff");
+  const semanticFactCount = semanticImpacts.reduce((sum, impact) => sum + (impact.facts?.length || 0), 0);
+  const summaryLines = [
+    `summary: lines_changed=${changedSpan} diff_entries=${diffEntryCount} lines_after=${lines.length}`,
+    `payload_sections: ${payloadSections(payloadKinds)}`,
+    `graph_enrichment: ${graphEnrichment}`,
+    `semantic_impact_count: ${semanticImpacts.length}`,
+    `semantic_fact_count: ${semanticFactCount}`,
+    `clone_warning_count: ${cloneWarnings.length}`,
+    `provenance_summary: edit_protocol=snapshot+anchors graph=${graphEnrichment === "available" ? "hex_line_contract" : "unavailable"}`
+  ].join("\n");
+  msg = msg.replace(`
+Updated ${filePath} (${lines.length} lines)`, `
+${summaryLines}
+Updated ${filePath} (${lines.length} lines)`);
   if (displayDiff) msg += `
 
 Diff:
@@ -2703,6 +2927,7 @@ var DEFAULT_TOTAL_LIMIT_LIST = 1e3;
 var MAX_OUTPUT = 10 * 1024 * 1024;
 var TIMEOUT2 = 3e4;
 var MAX_SEARCH_OUTPUT_CHARS = 8e4;
+var GRAPH_MATCH_ANNOTATION_BUDGET = 12;
 function spawnRg(args) {
   return new Promise((resolve_, reject) => {
     let stdout = "";
@@ -2832,6 +3057,7 @@ async function summaryMode(pattern, target, opts, totalLimit) {
 async function contentMode(pattern, target, opts, plain, editReady, totalLimit) {
   const realArgs = ["--json"];
   const plainOutput = plain || !editReady;
+  const shouldUseGraph = editReady && !plain;
   if (opts.caseInsensitive) realArgs.push("-i");
   else if (opts.smartCase) realArgs.push("-S");
   if (opts.literal) realArgs.push("-F");
@@ -2850,8 +3076,9 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit)
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const jsonLines = stdout.trimEnd().split("\n").filter(Boolean);
   const blocks = [];
-  const db = getGraphDB(target);
+  const db = shouldUseGraph ? getGraphDB(target) : null;
   const relCache = /* @__PURE__ */ new Map();
+  let annotationBudget = GRAPH_MATCH_ANNOTATION_BUDGET;
   let groupFile = null;
   let groupEntries = [];
   let matchCount = 0;
@@ -2916,15 +3143,20 @@ async function contentMode(pattern, target, opts, plain, editReady, totalLimit)
       }
       const isMatch = msg.type === "match";
       let annotation = "";
-      if (db && isMatch) {
-        let rel = relCache.get(filePath);
-        if (rel === void 0) {
-          rel = getRelativePath(resolve2(filePath)) || "";
-          relCache.set(filePath, rel);
-        }
-        if (rel) {
-          const a = matchAnnotation(db, rel, ln);
-          if (a) annotation = a;
+      if (db && isMatch && annotationBudget > 0) {
+        if (ensureGraphFreshForFile(db, resolve2(filePath))) {
+          let rel = relCache.get(filePath);
+          if (rel === void 0) {
+            rel = getRelativePath(resolve2(filePath)) || "";
+            relCache.set(filePath, rel);
+          }
+          if (rel) {
+            const a = matchAnnotation(db, rel, ln);
+            if (a) {
+              annotation = a;
+              annotationBudget--;
+            }
+          }
         }
       }
       groupEntries.push({
@@ -3390,11 +3622,11 @@ function verifyChecksums(filePath, checksums, opts = {}) {
 }
 
 // lib/inspect-path.mjs
-import { statSync as statSync8 } from "node:fs";
+import { statSync as statSync9 } from "node:fs";
 import { resolve as resolve6 } from "node:path";
 
 // lib/tree.mjs
-import { readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync6, existsSync as existsSync5 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync7, existsSync as existsSync5 } from "node:fs";
 import { resolve as resolve4, basename, join as join4, relative as relative2 } from "node:path";
 import ignore from "ignore";
 var SKIP_DIRS = /* @__PURE__ */ new Set([
@@ -3431,7 +3663,7 @@ function findByPattern(dirPath, opts) {
   const maxDepth = opts.max_depth ?? 20;
   const abs = resolve4(normalizePath(dirPath));
   if (!existsSync5(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}`);
-  if (!statSync6(abs).isDirectory()) throw new Error(`Not a directory: ${abs}`);
+  if (!statSync7(abs).isDirectory()) throw new Error(`Not a directory: ${abs}`);
   const ig = opts.gitignore ?? true ? loadGitignore(abs) : null;
   const matches = [];
   function walk(dir, depth) {
@@ -3472,7 +3704,7 @@ function directoryTree(dirPath, opts = {}) {
   const maxDepth = compact ? 1 : opts.max_depth ?? 3;
   const abs = resolve4(normalizePath(dirPath));
   if (!existsSync5(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}. Check path or use inspect_path on the parent directory.`);
-  const rootStat = statSync6(abs);
+  const rootStat = statSync7(abs);
   if (!rootStat.isDirectory()) throw new Error(`Not a directory: ${abs}`);
   const ig = opts.gitignore ?? true ? loadGitignore(abs) : null;
   let totalFiles = 0;
@@ -3518,7 +3750,7 @@ function directoryTree(dirPath, opts = {}) {
         } else {
           let size = 0, mtime = null, lineCount = null;
           try {
-            const st = statSync6(full);
+            const st = statSync7(full);
             size = st.size;
             mtime = st.mtime;
           } catch {
@@ -3567,7 +3799,7 @@ ${lines.join("\n")}`;
 }
 
 // lib/info.mjs
-import { statSync as statSync7, openSync as openSync2, readSync as readSync2, closeSync as closeSync2 } from "node:fs";
+import { statSync as statSync8, openSync as openSync2, readSync as readSync2, closeSync as closeSync2 } from "node:fs";
 import { resolve as resolve5, isAbsolute as isAbsolute3, extname as extname2, basename as basename2 } from "node:path";
 var MAX_LINE_COUNT_SIZE = 10 * 1024 * 1024;
 var EXT_NAMES = {
@@ -3638,7 +3870,7 @@ function fileInfo(filePath) {
   if (!filePath) throw new Error("Empty file path");
   const normalized = normalizePath(filePath);
   const abs = isAbsolute3(normalized) ? normalized : resolve5(process.cwd(), normalized);
-  const stat = statSync7(abs);
+  const stat = statSync8(abs);
   if (!stat.isFile()) throw new Error(`Not a regular file: ${abs}`);
   const size = stat.size;
   const mtime = stat.mtime;
@@ -3663,7 +3895,7 @@ function fileInfo(filePath) {
 // lib/inspect-path.mjs
 function inspectPath(inputPath, opts = {}) {
   const abs = resolve6(normalizePath(inputPath));
-  const stat = statSync8(abs);
+  const stat = statSync9(abs);
   if (stat.isFile()) return fileInfo(abs);
   if (stat.isDirectory()) return directoryTree(abs, opts);
   throw new Error(`Unsupported path type: ${abs}`);
@@ -3814,12 +4046,12 @@ function autoSync() {
 }
 
 // lib/changes.mjs
-import { statSync as statSync10 } from "node:fs";
+import { statSync as statSync11 } from "node:fs";
 import { join as join6 } from "node:path";
 
 // ../hex-common/src/git/semantic-diff.mjs
 import { execFileSync } from "node:child_process";
-import { existsSync as existsSync7, readFileSync as readFileSync6, statSync as statSync9 } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync6, statSync as statSync10 } from "node:fs";
 import { dirname as dirname5, extname as extname3, relative as relative3, resolve as resolve8 } from "node:path";
 function normalizePath2(value) {
   return value.replace(/\\/g, "/");
@@ -3828,7 +4060,7 @@ function repoCwd(targetPath) {
   if (!existsSync7(targetPath)) {
     throw new Error(`Path does not exist: ${targetPath}`);
   }
-  return statSync9(targetPath).isDirectory() ? targetPath : dirname5(targetPath);
+  return statSync10(targetPath).isDirectory() ? targetPath : dirname5(targetPath);
 }
 function runGit(args, cwd, allowFailure = false) {
   try {
@@ -4076,6 +4308,15 @@ async function semanticGitDiff(targetPath, { baseRef = "HEAD", headRef = null }
 }
 
 // lib/changes.mjs
+function graphEnrichmentState(db) {
+  return db ? "available" : "unavailable";
+}
+function provenanceSummary(semanticDiffState, db) {
+  return `semantic_diff=${semanticDiffState} graph=${db ? "hex_line_contract" : "unavailable"}`;
+}
+function payloadSections2(sections) {
+  return sections.length > 0 ? sections.join(",") : "summary_only";
+}
 function exportedLooking(symbol) {
   return /^\s*(export|public)\b/.test(symbol.text || "");
 }
@@ -4114,9 +4355,10 @@ function summarizeRiskLine(line) {
 async function fileChanges(filePath, compareAgainst = "HEAD") {
   filePath = normalizePath(filePath);
   const real = validatePath(filePath);
-  if (statSync10(real).isDirectory()) {
+  if (statSync11(real).isDirectory()) {
     const db2 = getGraphDB(join6(real, "__hex-line_probe__"));
     const diff2 = await semanticGitDiff(real, { baseRef: compareAgainst });
+    const graphEnrichment2 = graphEnrichmentState(db2);
     if (diff2.summary.changed_file_count === 0) {
       return [
         "status: NO_CHANGES",
@@ -4125,9 +4367,19 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
         `compare_against: ${compareAgainst}`,
         "scope: directory",
         "summary: changed_files=0",
-        `next_action: ${ACTION.NO_ACTION}`
+        `next_action: ${ACTION.NO_ACTION}`,
+        `graph_enrichment: ${graphEnrichment2}`,
+        "risk_summary_count: 0",
+        "removed_api_warning_count: 0",
+        `payload_sections: ${payloadSections2([])}`,
+        `provenance_summary: ${provenanceSummary("clean", db2)}`
       ].join("\n");
     }
+    const supportedCount = diff2.changed_files.filter((entry) => entry.semantic_supported).length;
+    const semanticDiffState = supportedCount === 0 ? "unsupported" : supportedCount === diff2.changed_files.length ? "semantic" : "mixed";
+    let emittedRiskCount = 0;
+    let emittedRemovedApiWarnings = 0;
+    const sectionKinds2 = ["files"];
     const sections = [
       "status: CHANGED",
       `reason: ${REASON.DIRECTORY_CHANGED}`,
@@ -4136,6 +4388,7 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
       "scope: directory",
       `summary: changed_files=${diff2.summary.changed_file_count}`,
       `next_action: ${ACTION.INSPECT_FILE}`,
+      `graph_enrichment: ${graphEnrichment2}`,
       ""
     ];
     for (const file2 of diff2.changed_files) {
@@ -4145,16 +4398,32 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
       ];
       sections.push(parts2.join(" | "));
       const riskLines2 = summarizeGraphRisk(db2, file2.path.replace(/\\/g, "/"), file2);
-      for (const line of riskLines2.slice(0, 2)) sections.push(`risk_summary: ${summarizeRiskLine(line)}`);
+      const visibleRiskLines = riskLines2.slice(0, 2);
+      emittedRiskCount += visibleRiskLines.length;
+      for (const line of visibleRiskLines) sections.push(`risk_summary: ${summarizeRiskLine(line)}`);
       for (const symbol of file2.removed_symbols.slice(0, 2)) {
-        if (exportedLooking(symbol)) sections.push(`removed_api_warning: ${symbol.text}`);
+        if (exportedLooking(symbol)) {
+          emittedRemovedApiWarnings += 1;
+          sections.push(`removed_api_warning: ${symbol.text}`);
+        }
       }
     }
+    if (emittedRiskCount > 0) sectionKinds2.push("risk_summary");
+    if (emittedRemovedApiWarnings > 0) sectionKinds2.push("removed_api_warning");
+    sections.splice(
+      8,
+      0,
+      `risk_summary_count: ${emittedRiskCount}`,
+      `removed_api_warning_count: ${emittedRemovedApiWarnings}`,
+      `payload_sections: ${payloadSections2(sectionKinds2)}`,
+      `provenance_summary: ${provenanceSummary(semanticDiffState, db2)}`
+    );
     return sections.join("\n");
   }
   const db = getGraphDB(real);
   const diff = await semanticGitDiff(real, { baseRef: compareAgainst });
   const file = diff.changed_files[0];
+  const graphEnrichment = graphEnrichmentState(db);
   if (!file) {
     return [
       "status: NO_CHANGES",
@@ -4163,7 +4432,12 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
       `compare_against: ${compareAgainst}`,
       "scope: file",
       "summary: added=0 removed=0 modified=0",
-      `next_action: ${ACTION.NO_ACTION}`
+      `next_action: ${ACTION.NO_ACTION}`,
+      `graph_enrichment: ${graphEnrichment}`,
+      "risk_summary_count: 0",
+      "removed_api_warning_count: 0",
+      `payload_sections: ${payloadSections2([])}`,
+      `provenance_summary: ${provenanceSummary("clean", db)}`
     ].join("\n");
   }
   if (!file.semantic_supported) {
@@ -4174,30 +4448,45 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
       `compare_against: ${compareAgainst}`,
       "scope: file",
       `summary: semantic diff unavailable for ${file.extension} files`,
-      `next_action: ${ACTION.INSPECT_RAW_DIFF}`
+      `next_action: ${ACTION.INSPECT_RAW_DIFF}`,
+      `graph_enrichment: ${graphEnrichment}`,
+      "risk_summary_count: 0",
+      "removed_api_warning_count: 0",
+      `payload_sections: ${payloadSections2([])}`,
+      `provenance_summary: ${provenanceSummary("unsupported", db)}`
     ].join("\n");
   }
+  const relFile = getRelativePath(real) || file.path?.replace(/\\/g, "/");
+  const riskLines = summarizeGraphRisk(db, relFile, file);
+  const removedApiWarnings = file.removed_symbols.filter(exportedLooking).slice(0, 4);
+  const sectionKinds = [];
   const parts = [
     "status: CHANGED",
     `reason: ${REASON.FILE_CHANGED}`,
     `path: ${filePath}`,
     `compare_against: ${compareAgainst}`,
     "scope: file",
-    `summary: ${symbolCountSummary(file)}`
+    `summary: ${symbolCountSummary(file)}`,
+    `graph_enrichment: ${graphEnrichment}`,
+    `risk_summary_count: ${riskLines.length}`,
+    `removed_api_warning_count: ${removedApiWarnings.length}`
   ];
   if (file.added_symbols.length) {
+    sectionKinds.push("added");
     parts.push(`next_action: ${ACTION.REVIEW_RISKS}`);
     parts.push("");
     parts.push("added:");
     for (const symbol of file.added_symbols) parts.push(`  + ${symbol.start}-${symbol.end}: ${symbol.text}`);
   }
   if (file.removed_symbols.length) {
+    sectionKinds.push("removed");
     if (!parts.includes(`next_action: ${ACTION.REVIEW_RISKS}`)) parts.push(`next_action: ${ACTION.REVIEW_RISKS}`);
     parts.push("");
     parts.push("removed:");
     for (const symbol of file.removed_symbols) parts.push(`  - ${symbol.start}-${symbol.end}: ${symbol.text}`);
   }
   if (file.modified_symbols.length) {
+    sectionKinds.push("modified");
     if (!parts.includes(`next_action: ${ACTION.REVIEW_RISKS}`)) parts.push(`next_action: ${ACTION.REVIEW_RISKS}`);
     parts.push("");
     parts.push("modified:");
@@ -4212,9 +4501,14 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
     parts.push("");
     parts.push("summary_detail: no symbol changes detected");
   }
-  const relFile = getRelativePath(real) || file.path?.replace(/\\/g, "/");
-  const riskLines = summarizeGraphRisk(db, relFile, file);
-  const removedApiWarnings = file.removed_symbols.filter(exportedLooking).slice(0, 4);
+  if (riskLines.length > 0) sectionKinds.push("risk_summary");
+  if (removedApiWarnings.length > 0) sectionKinds.push("removed_api_warning");
+  parts.splice(
+    9,
+    0,
+    `payload_sections: ${payloadSections2(sectionKinds)}`,
+    `provenance_summary: ${provenanceSummary("semantic", db)}`
+  );
   if (riskLines.length || removedApiWarnings.length) {
     parts.push("");
     parts.push("risk_summary:");
@@ -4344,7 +4638,7 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
 }
 
 // server.mjs
-var version = true ? "1.15.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.16.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 9 tools: inspect_path, read, edit, write, grep, outline, verify, changes, bulk_replace.",