@levnikolaevich/hex-line-mcp 1.4.0 → 1.6.0

package/dist/server.mjs

@@ -109,64 +109,6 @@ async function checkForUpdates(packageName, currentVersion) {
 // lib/read.mjs
 import { statSync as statSync4 } from "node:fs";
 
-// ../hex-common/src/text-protocol/hash.mjs
-var FNV_OFFSET = 2166136261;
-var FNV_PRIME = 16777619;
-var TAG_CHARS = "abcdefghijklmnopqrstuvwxyz234567";
-function fnv1a(str) {
-  const normalized = str.replace(/\r$/, "").replace(/\s+/g, "");
-  let h = FNV_OFFSET;
-  for (let i = 0; i < normalized.length; i++) {
-    let code = normalized.charCodeAt(i);
-    if (code >= 55296 && code <= 56319 && i + 1 < normalized.length) {
-      const lo = normalized.charCodeAt(i + 1);
-      if (lo >= 56320 && lo <= 57343) {
-        code = (code - 55296 << 10) + (lo - 56320) + 65536;
-        i++;
-      }
-    }
-    if (code < 128) {
-      h = Math.imul(h ^ code, FNV_PRIME) >>> 0;
-    } else if (code < 2048) {
-      h = Math.imul(h ^ (192 | code >> 6), FNV_PRIME) >>> 0;
-      h = Math.imul(h ^ (128 | code & 63), FNV_PRIME) >>> 0;
-    } else if (code < 65536) {
-      h = Math.imul(h ^ (224 | code >> 12), FNV_PRIME) >>> 0;
-      h = Math.imul(h ^ (128 | code >> 6 & 63), FNV_PRIME) >>> 0;
-      h = Math.imul(h ^ (128 | code & 63), FNV_PRIME) >>> 0;
-    } else {
-      h = Math.imul(h ^ (240 | code >> 18), FNV_PRIME) >>> 0;
-      h = Math.imul(h ^ (128 | code >> 12 & 63), FNV_PRIME) >>> 0;
-      h = Math.imul(h ^ (128 | code >> 6 & 63), FNV_PRIME) >>> 0;
-      h = Math.imul(h ^ (128 | code & 63), FNV_PRIME) >>> 0;
-    }
-  }
-  return h;
-}
-function lineTag(hash32) {
-  return TAG_CHARS[hash32 & 31] + TAG_CHARS[hash32 >>> 8 & 31];
-}
-function rangeChecksum(lineHashes, startLine, endLine) {
-  let acc = FNV_OFFSET;
-  for (const h of lineHashes) {
-    acc = Math.imul(acc ^ h & 255, FNV_PRIME) >>> 0;
-    acc = Math.imul(acc ^ h >>> 8 & 255, FNV_PRIME) >>> 0;
-    acc = Math.imul(acc ^ h >>> 16 & 255, FNV_PRIME) >>> 0;
-    acc = Math.imul(acc ^ h >>> 24 & 255, FNV_PRIME) >>> 0;
-  }
-  return `${startLine}-${endLine}:${acc.toString(16).padStart(8, "0")}`;
-}
-function parseRef(ref) {
-  const m = ref.trim().match(/^([a-z2-7]{2})\.(\d+)$/);
-  if (!m) throw new Error(`Bad ref: "${ref}". Expected "ab.12" (tag.lineNum)`);
-  return { tag: m[1], line: parseInt(m[2], 10) };
-}
-function parseChecksum(cs) {
-  const m = cs.trim().match(/^(\d+)-(\d+):([0-9a-f]{8})$/);
-  if (!m) throw new Error(`Bad checksum: "${cs}". Expected "1-50:f7e2a1b0"`);
-  return { start: parseInt(m[1], 10), end: parseInt(m[2], 10), hex: m[3] };
-}
-
 // lib/security.mjs
 import { realpathSync, statSync as statSync2, existsSync, openSync, readSync, closeSync } from "node:fs";
 import { resolve, isAbsolute, dirname } from "node:path";
@@ -476,9 +418,69 @@ function findProjectRoot(filePath) {
   return null;
 }
 
-// lib/revisions.mjs
+// lib/snapshot.mjs
 import { statSync as statSync3 } from "node:fs";
 import { diffLines } from "diff";
+
+// ../hex-common/src/text-protocol/hash.mjs
+var FNV_OFFSET = 2166136261;
+var FNV_PRIME = 16777619;
+var TAG_CHARS = "abcdefghijklmnopqrstuvwxyz234567";
+function fnv1a(str) {
+  const normalized = str.replace(/\r$/, "").replace(/\s+/g, "");
+  let h = FNV_OFFSET;
+  for (let i = 0; i < normalized.length; i++) {
+    let code = normalized.charCodeAt(i);
+    if (code >= 55296 && code <= 56319 && i + 1 < normalized.length) {
+      const lo = normalized.charCodeAt(i + 1);
+      if (lo >= 56320 && lo <= 57343) {
+        code = (code - 55296 << 10) + (lo - 56320) + 65536;
+        i++;
+      }
+    }
+    if (code < 128) {
+      h = Math.imul(h ^ code, FNV_PRIME) >>> 0;
+    } else if (code < 2048) {
+      h = Math.imul(h ^ (192 | code >> 6), FNV_PRIME) >>> 0;
+      h = Math.imul(h ^ (128 | code & 63), FNV_PRIME) >>> 0;
+    } else if (code < 65536) {
+      h = Math.imul(h ^ (224 | code >> 12), FNV_PRIME) >>> 0;
+      h = Math.imul(h ^ (128 | code >> 6 & 63), FNV_PRIME) >>> 0;
+      h = Math.imul(h ^ (128 | code & 63), FNV_PRIME) >>> 0;
+    } else {
+      h = Math.imul(h ^ (240 | code >> 18), FNV_PRIME) >>> 0;
+      h = Math.imul(h ^ (128 | code >> 12 & 63), FNV_PRIME) >>> 0;
+      h = Math.imul(h ^ (128 | code >> 6 & 63), FNV_PRIME) >>> 0;
+      h = Math.imul(h ^ (128 | code & 63), FNV_PRIME) >>> 0;
+    }
+  }
+  return h;
+}
+function lineTag(hash32) {
+  return TAG_CHARS[hash32 & 31] + TAG_CHARS[hash32 >>> 8 & 31];
+}
+function rangeChecksum(lineHashes, startLine, endLine) {
+  let acc = FNV_OFFSET;
+  for (const h of lineHashes) {
+    acc = Math.imul(acc ^ h & 255, FNV_PRIME) >>> 0;
+    acc = Math.imul(acc ^ h >>> 8 & 255, FNV_PRIME) >>> 0;
+    acc = Math.imul(acc ^ h >>> 16 & 255, FNV_PRIME) >>> 0;
+    acc = Math.imul(acc ^ h >>> 24 & 255, FNV_PRIME) >>> 0;
+  }
+  return `${startLine}-${endLine}:${acc.toString(16).padStart(8, "0")}`;
+}
+function parseRef(ref) {
+  const m = ref.trim().match(/^([a-z2-7]{2})\.(\d+)$/);
+  if (!m) throw new Error(`Bad ref: "${ref}". Expected "ab.12" (tag.lineNum)`);
+  return { tag: m[1], line: parseInt(m[2], 10) };
+}
+function parseChecksum(cs) {
+  const m = cs.trim().match(/^(\d+)-(\d+):([0-9a-f]{8})$/);
+  if (!m) throw new Error(`Bad checksum: "${cs}". Expected "1-50:f7e2a1b0"`);
+  return { start: parseInt(m[1], 10), end: parseInt(m[2], 10), hex: m[3] };
+}
+
+// lib/snapshot.mjs
 var MAX_FILES = 200;
 var MAX_REVISIONS_PER_FILE = 5;
 var TTL_MS = 5 * 60 * 1e3;
@@ -658,17 +660,223 @@ function getSnapshotByRevision(revision) {
   return revisionsById.get(revision) || null;
 }
 function overlapsChangedRanges(ranges, startLine, endLine) {
-  return (ranges || []).some((range) => range.start <= endLine && startLine <= range.end);
+  return (ranges || []).some((range) => range.start <= endLine && range.end >= startLine);
 }
 function buildRangeChecksum(snapshot, startLine, endLine) {
-  const startIdx = startLine - 1;
-  const endIdx = endLine - 1;
-  if (startIdx < 0 || endIdx >= snapshot.lineHashes.length || startIdx > endIdx) return null;
-  return rangeChecksum(snapshot.lineHashes.slice(startIdx, endIdx + 1), startLine, endLine);
+  if (startLine < 1 || endLine > snapshot.lineHashes.length || startLine > endLine) return null;
+  return rangeChecksum(snapshot.lineHashes.slice(startLine - 1, endLine), startLine, endLine);
+}
+
+// lib/block-protocol.mjs
+function normalizeEntry(entry) {
+  const text = String(entry.text ?? "");
+  const hash32 = entry.hash32 ?? fnv1a(text);
+  return {
+    lineNumber: entry.lineNumber,
+    text,
+    hash32,
+    tag: entry.tag ?? lineTag(hash32),
+    role: entry.role ?? "content",
+    annotation: entry.annotation ?? ""
+  };
+}
+function renderRequestedSpan(block) {
+  if (block.requestedStartLine === null || block.requestedEndLine === null) return null;
+  if (block.requestedStartLine === block.startLine && block.requestedEndLine === block.endLine) return null;
+  return `requested_span: ${block.requestedStartLine}-${block.requestedEndLine}`;
+}
+function renderBaseEntry(entry, plain = false) {
+  return plain ? `${entry.lineNumber}|${entry.text}` : `${entry.tag}.${entry.lineNumber}	${entry.text}`;
+}
+function createSnapshotEntries(snapshot, startLine, endLine, extra = {}) {
+  const entries = [];
+  for (let lineNumber = startLine; lineNumber <= endLine; lineNumber++) {
+    const idx = lineNumber - 1;
+    entries.push(normalizeEntry({
+      lineNumber,
+      text: snapshot.lines[idx],
+      hash32: snapshot.lineHashes[idx],
+      ...extra
+    }));
+  }
+  return entries;
+}
+function buildEditReadyBlock({ path, kind, entries, requestedStartLine = null, requestedEndLine = null, meta = {} }) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    throw new Error("EditReadyBlock requires at least one entry");
+  }
+  const normalized = entries.map(normalizeEntry).sort((a, b) => a.lineNumber - b.lineNumber);
+  const startLine = normalized[0].lineNumber;
+  const endLine = normalized[normalized.length - 1].lineNumber;
+  return {
+    type: "edit_ready_block",
+    path,
+    kind,
+    startLine,
+    endLine,
+    requestedStartLine: requestedStartLine ?? startLine,
+    requestedEndLine: requestedEndLine ?? endLine,
+    entries: normalized,
+    checksum: rangeChecksum(normalized.map((entry) => entry.hash32), startLine, endLine),
+    meta
+  };
+}
+function buildDiagnosticBlock({
+  path = "",
+  kind,
+  message,
+  requestedStartLine = null,
+  requestedEndLine = null,
+  startLine = null,
+  endLine = null,
+  meta = {}
+}) {
+  return {
+    type: "diagnostic_block",
+    path,
+    kind,
+    message,
+    requestedStartLine,
+    requestedEndLine,
+    startLine,
+    endLine,
+    meta
+  };
+}
+function serializeReadEntry(entry, opts = {}) {
+  return renderBaseEntry(entry, opts.plain);
+}
+function serializeSearchEntry(entry, opts = {}) {
+  const body = renderBaseEntry(entry, opts.plain);
+  if (opts.plain) return body;
+  const prefix = entry.role === "match" ? ">>" : "  ";
+  const suffix = entry.annotation ? `  ${entry.annotation}` : "";
+  return `${prefix}${body}${suffix}`;
+}
+function serializeReadBlock(block, opts = {}) {
+  if (block.type !== "edit_ready_block") return serializeDiagnosticBlock(block);
+  const lines = [
+    `block: ${block.kind}`,
+    `span: ${block.startLine}-${block.endLine}`
+  ];
+  const requestedSpan = renderRequestedSpan(block);
+  if (requestedSpan) lines.push(requestedSpan);
+  lines.push(...block.entries.map((entry) => serializeReadEntry(entry, opts)));
+  lines.push(`checksum: ${block.checksum}`);
+  return lines.join("\n");
+}
+function serializeSearchBlock(block, opts = {}) {
+  if (block.type !== "edit_ready_block") return serializeDiagnosticBlock(block);
+  const lines = [
+    `block: ${block.kind}`,
+    `file: ${block.path}`,
+    `span: ${block.startLine}-${block.endLine}`
+  ];
+  const requestedSpan = renderRequestedSpan(block);
+  if (requestedSpan) lines.push(requestedSpan);
+  if (Array.isArray(block.meta.matchLines) && block.meta.matchLines.length > 0) {
+    lines.push(`match_lines: ${block.meta.matchLines.join(",")}`);
+  }
+  if (block.meta.summary) lines.push(`summary: ${block.meta.summary}`);
+  lines.push(...block.entries.map((entry) => serializeSearchEntry(entry, opts)));
+  lines.push(`checksum: ${block.checksum}`);
+  return lines.join("\n");
+}
+function serializeDiagnosticBlock(block) {
+  const lines = ["block: diagnostic"];
+  if (block.path) lines.push(`file: ${block.path}`);
+  lines.push(`kind: ${block.kind}`);
+  if (block.startLine !== null && block.endLine !== null) {
+    lines.push(`span: ${block.startLine}-${block.endLine}`);
+  }
+  if (block.requestedStartLine !== null && block.requestedEndLine !== null) {
+    lines.push(`requested_span: ${block.requestedStartLine}-${block.requestedEndLine}`);
+  }
+  lines.push(`message: ${block.message}`);
+  return lines.join("\n");
 }
 
 // lib/read.mjs
 var DEFAULT_LIMIT = 2e3;
+function parseRangeEntry(entry, total) {
+  if (typeof entry === "string") {
+    const match = entry.trim().match(/^(\d+)(?:-(\d*)?)?$/);
+    if (!match) throw new Error(`Invalid range "${entry}". Use "10", "10-25", or "10-"`);
+    const start2 = Number(match[1]);
+    const end2 = match[2] === void 0 || match[2] === "" ? total : Number(match[2]);
+    return { start: start2, end: end2 };
+  }
+  if (!entry || typeof entry !== "object") {
+    throw new Error("ranges entries must be strings or {start,end} objects");
+  }
+  const start = Number(entry.start ?? 1);
+  const end = entry.end === void 0 || entry.end === null ? total : Number(entry.end);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    throw new Error("ranges entries must contain numeric start/end values");
+  }
+  return { start, end };
+}
+function normalizeRange(entry, total) {
+  const parsed = parseRangeEntry(entry, total);
+  if (!Number.isInteger(parsed.start) || !Number.isInteger(parsed.end)) {
+    throw new Error("ranges entries must resolve to integer start/end values");
+  }
+  if (parsed.start > parsed.end) {
+    return buildDiagnosticBlock({
+      kind: "invalid_range",
+      message: `Requested range ${parsed.start}-${parsed.end} has start greater than end.`,
+      requestedStartLine: parsed.start,
+      requestedEndLine: parsed.end
+    });
+  }
+  if (parsed.end < 1 || parsed.start > total) {
+    return buildDiagnosticBlock({
+      kind: "invalid_range",
+      message: `Requested range ${parsed.start}-${parsed.end} is outside file length ${total}.`,
+      requestedStartLine: parsed.start,
+      requestedEndLine: parsed.end
+    });
+  }
+  return {
+    requestedStartLine: parsed.start,
+    requestedEndLine: parsed.end,
+    startLine: Math.max(1, parsed.start),
+    endLine: Math.min(total, parsed.end)
+  };
+}
+function buildReadBlock(snapshot, range, plain, remainingChars) {
+  const entries = [];
+  let nextBudget = remainingChars;
+  let cappedAtLine = 0;
+  for (let lineNumber = range.startLine; lineNumber <= range.endLine; lineNumber++) {
+    const entry = createSnapshotEntries(snapshot, lineNumber, lineNumber)[0];
+    const rendered = serializeReadEntry(entry, { plain });
+    const nextCost = rendered.length + 1;
+    if (entries.length > 0 && nextBudget - nextCost < 0) {
+      cappedAtLine = lineNumber;
+      break;
+    }
+    entries.push(entry);
+    nextBudget -= nextCost;
+  }
+  if (entries.length === 0) {
+    const entry = createSnapshotEntries(snapshot, range.startLine, range.startLine)[0];
+    entries.push(entry);
+    nextBudget -= serializeReadEntry(entry, { plain }).length + 1;
+    if (range.endLine > range.startLine) cappedAtLine = range.startLine + 1;
+  }
+  return {
+    block: buildEditReadyBlock({
+      path: snapshot.path,
+      kind: "read_range",
+      entries,
+      requestedStartLine: range.requestedStartLine,
+      requestedEndLine: range.requestedEndLine
+    }),
+    remainingChars: nextBudget,
+    cappedAtLine
+  };
+}
 function readFile2(filePath, opts = {}) {
   filePath = normalizePath(filePath);
   const real = validatePath(filePath);
@@ -681,62 +889,55 @@ function readFile2(filePath, opts = {}) {
 ${text}
 \`\`\``;
   }
-  const snapshot = rememberSnapshot(real, readText(real), { mtimeMs: stat.mtimeMs, size: stat.size });
-  const lines = snapshot.lines;
-  const total = lines.length;
-  let ranges;
+  const snapshot = readSnapshot(real);
+  const total = snapshot.lines.length;
+  let requestedRanges;
   if (opts.ranges && opts.ranges.length > 0) {
-    ranges = opts.ranges.map((r) => ({
-      start: Math.max(1, r.start || 1),
-      end: Math.min(total, r.end || total)
-    }));
+    requestedRanges = opts.ranges;
   } else {
     const startLine = Math.max(1, opts.offset || 1);
     const maxLines = opts.limit && opts.limit > 0 ? opts.limit : DEFAULT_LIMIT;
-    ranges = [{ start: startLine, end: Math.min(total, startLine - 1 + maxLines) }];
+    requestedRanges = [{ start: startLine, end: Math.min(total, startLine - 1 + maxLines) }];
   }
-  const parts = [];
+  const blocks = [];
+  const diagnostics = [];
+  let remainingChars = MAX_OUTPUT_CHARS;
   let cappedAtLine = 0;
-  for (const range of ranges) {
-    const selected = lines.slice(range.start - 1, range.end);
-    const lineHashes = [];
-    const formatted = [];
-    let charCount = 0;
-    for (let i = 0; i < selected.length; i++) {
-      const line = selected[i];
-      const num = range.start + i;
-      const hash32 = fnv1a(line);
-      const entry = opts.plain ? `${num}|${line}` : `${lineTag(hash32)}.${num}	${line}`;
-      if (charCount + entry.length > MAX_OUTPUT_CHARS && formatted.length > 0) {
-        cappedAtLine = num;
-        break;
-      }
-      lineHashes.push(hash32);
-      formatted.push(entry);
-      charCount += entry.length + 1;
-    }
-    const actualEnd = formatted.length > 0 ? range.start + formatted.length - 1 : range.start;
-    range.end = actualEnd;
-    parts.push(formatted.join("\n"));
-    const cs = rangeChecksum(lineHashes, range.start, actualEnd);
-    parts.push(`
-checksum: ${cs}`);
-    if (cappedAtLine) break;
-  }
-  const sizeKB = (stat.size / 1024).toFixed(1);
-  const mtime = stat.mtime;
-  const ago = relativeTime(mtime);
-  let header = `File: ${filePath} (${total} lines, ${sizeKB}KB, ${ago})`;
-  if (ranges.length === 1) {
-    const r = ranges[0];
-    if (r.start > 1 || r.end < total) {
-      header += ` [showing ${r.start}-${r.end}]`;
+  for (const requested of requestedRanges) {
+    const normalized = normalizeRange(requested, total);
+    if (normalized.type === "diagnostic_block") {
+      diagnostics.push(normalized);
+      continue;
     }
-    if (r.end < total) {
-      header += ` (${total - r.end} more below)`;
+    const built = buildReadBlock(snapshot, normalized, opts.plain, remainingChars);
+    blocks.push(built.block);
+    remainingChars = built.remainingChars;
+    if (built.cappedAtLine) {
+      cappedAtLine = built.cappedAtLine;
+      diagnostics.push(buildDiagnosticBlock({
+        kind: "output_capped",
+        message: `OUTPUT_CAPPED at line ${built.cappedAtLine} (${MAX_OUTPUT_CHARS} char limit). Use offset=${built.cappedAtLine} to continue reading.`,
+        requestedStartLine: built.cappedAtLine,
+        requestedEndLine: built.cappedAtLine,
+        startLine: built.block.startLine,
+        endLine: built.block.endLine
+      }));
+      break;
     }
   }
-  const db = getGraphDB(real);
+  const sizeText = formatSize(stat.size);
+  const ago = relativeTime(stat.mtime);
+  let meta = `${total} lines, ${sizeText}, ${ago}`;
+  if (requestedRanges.length === 1 && blocks.length === 1) {
+    const block = blocks[0];
+    if (block.startLine > 1 || block.endLine < total) {
+      meta += `, showing ${block.startLine}-${block.endLine}`;
+    }
+    if (block.endLine < total) {
+      meta += `, ${total - block.endLine} more below`;
+    }
+  }
+  const db = opts.includeGraph ? getGraphDB(real) : null;
   const relFile = db ? getRelativePath(real) : null;
   let graphLine = "";
   if (db && relFile) {
@@ -750,29 +951,112 @@ checksum: ${cs}`);
 Graph: ${items.join(" | ")}`;
     }
   }
-  let result = `${header}${graphLine}
+  const serializedBlocks = [
+    ...blocks.map((block) => serializeReadBlock(block, { plain: opts.plain })),
+    ...diagnostics.map((block) => serializeDiagnosticBlock(block))
+  ];
+  if (cappedAtLine && serializedBlocks.length === 0) {
+    serializedBlocks.push(serializeDiagnosticBlock(buildDiagnosticBlock({
+      kind: "output_capped",
+      message: `OUTPUT_CAPPED at line ${cappedAtLine} (${MAX_OUTPUT_CHARS} char limit). Use offset=${cappedAtLine} to continue reading.`,
+      requestedStartLine: cappedAtLine,
+      requestedEndLine: cappedAtLine
+    })));
+  }
+  return `File: ${filePath}${graphLine}
+meta: ${meta}
 revision: ${snapshot.revision}
 file: ${snapshot.fileChecksum}
 
-\`\`\`
-${parts.join("\n")}
-\`\`\``;
-  if (total > 200 && (!opts.offset || opts.offset <= 1) && !cappedAtLine) {
-    result += `
+${serializedBlocks.join("\n\n")}`.trim();
+}
 
-\u26A1 Tip: This file has ${total} lines. Use outline first, then read_file with offset/limit for 75% fewer tokens.`;
-  }
-  if (cappedAtLine) {
-    result += `
+// lib/edit.mjs
+import { statSync as statSync5, writeFileSync } from "node:fs";
+import { diffLines as diffLines2 } from "diff";
 
-OUTPUT_CAPPED at line ${cappedAtLine} (${MAX_OUTPUT_CHARS} char limit). Use offset=${cappedAtLine} to continue reading.`;
+// lib/edit-resolution.mjs
+function normalizeAnchoredEdits(edits) {
+  const anchored = [];
+  for (const edit of edits) {
+    if (edit.set_line || edit.replace_lines || edit.insert_after || edit.replace_between) {
+      anchored.push(edit);
+      continue;
+    }
+    if (edit.replace) {
+      throw new Error("REPLACE_REMOVED: replace is no longer supported in edit_file. Use set_line/replace_lines for single edits, bulk_replace tool for rename/refactor.");
+    }
+    throw new Error(`BAD_INPUT: unknown edit type: ${JSON.stringify(edit)}`);
+  }
+  return anchored;
+}
+function getEditStartLine(edit) {
+  if (edit.set_line) return parseRef(edit.set_line.anchor).line;
+  if (edit.replace_lines) return parseRef(edit.replace_lines.start_anchor).line;
+  if (edit.insert_after) return parseRef(edit.insert_after.anchor).line;
+  if (edit.replace_between) return parseRef(edit.replace_between.start_anchor).line;
+  throw new Error(`BAD_INPUT: unsupported edit shape: ${JSON.stringify(edit)}`);
+}
+function collectEditTargets(edits) {
+  return edits.map((edit) => {
+    if (edit.set_line) {
+      const line = parseRef(edit.set_line.anchor).line;
+      return { start: line, end: line, insert: false, kind: "set_line" };
+    }
+    if (edit.replace_lines) {
+      const start = parseRef(edit.replace_lines.start_anchor).line;
+      const end = parseRef(edit.replace_lines.end_anchor).line;
+      return { start, end, insert: false, kind: "replace_lines" };
+    }
+    if (edit.insert_after) {
+      const line = parseRef(edit.insert_after.anchor).line;
+      return { start: line, end: line, insert: true, kind: "insert_after" };
+    }
+    if (edit.replace_between) {
+      const start = parseRef(edit.replace_between.start_anchor).line;
+      const end = parseRef(edit.replace_between.end_anchor).line;
+      return { start, end, insert: false, kind: "replace_between" };
+    }
+    throw new Error(`BAD_INPUT: unsupported edit shape: ${JSON.stringify(edit)}`);
+  });
+}
+function assertNonOverlappingTargets(targets) {
+  for (let i = 0; i < targets.length; i++) {
+    for (let j = i + 1; j < targets.length; j++) {
+      const a = targets[i];
+      const b = targets[j];
+      if (a.insert || b.insert) continue;
+      if (a.start <= b.end && b.start <= a.end) {
+        throw new Error(
+          `OVERLAPPING_EDITS: lines ${a.start}-${a.end} and ${b.start}-${b.end} overlap. Split into separate edit_file calls.`
+        );
+      }
+    }
   }
-  return result;
+}
+function sortEditsForApply(edits) {
+  return edits.map((edit) => ({ ...edit, _k: getEditStartLine(edit) })).sort((a, b) => b._k - a._k);
+}
+function targetRangeForReplaceBetween(startIdx, endIdx, boundaryMode) {
+  if (boundaryMode === "exclusive") {
+    return { start: startIdx + 2, end: Math.max(startIdx + 1, endIdx) };
+  }
+  return { start: startIdx + 1, end: endIdx + 1 };
+}
+function validateChecksumCoverage(rangeChecksum2, actualStart, actualEnd) {
+  const { start, end } = parseChecksum(rangeChecksum2);
+  if (start > actualStart || end < actualEnd) {
+    return {
+      ok: false,
+      start,
+      end,
+      reason: `CHECKSUM_RANGE_GAP: checksum covers lines ${start}-${end} but edit spans ${actualStart}-${actualEnd} (inclusive). Checksum range must fully contain the anchor range.`
+    };
+  }
+  return { ok: true, start, end, reason: null };
 }
 
 // lib/edit.mjs
-import { statSync as statSync5, writeFileSync } from "node:fs";
-import { diffLines as diffLines2 } from "diff";
 function restoreIndent(origLines, newLines) {
   if (!origLines.length || !newLines.length) return newLines;
   const origIndent = origLines[0].match(/^\s*/)[0];
@@ -794,6 +1078,26 @@ function buildErrorSnippet(lines, centerIdx, radius = 5) {
   }).join("\n");
   return { start: start + 1, end, text };
 }
+function stripAnchorOrDiffPrefix(line) {
+  let next = line;
+  next = next.replace(/^\s*(?:>>|  )?[a-z2-7]{2}\.\d+\t/, "");
+  next = next.replace(/^.+:(?:>>|  )[a-z2-7]{2}\.\d+\t/, "");
+  next = next.replace(/^[ +-]\d+\|\s?/, "");
+  return next;
+}
+function sanitizeEditText(text) {
+  const original = String(text ?? "");
+  const hadTrailingNewline = original.endsWith("\n");
+  let lines = original.split("\n");
+  const nonEmpty = lines.filter((line) => line.length > 0);
+  if (nonEmpty.length > 0 && nonEmpty.every((line) => /^\+(?!\+)/.test(line))) {
+    lines = lines.map((line) => line.startsWith("+") && !line.startsWith("++") ? line.slice(1) : line);
+  }
+  lines = lines.map(stripAnchorOrDiffPrefix);
+  let cleaned = lines.join("\n");
+  if (hadTrailingNewline && !cleaned.endsWith("\n")) cleaned += "\n";
+  return cleaned;
+}
 function findLine(lines, lineNum, expectedTag, hashIndex) {
   const idx = lineNum - 1;
   if (idx < 0 || idx >= lines.length) {
@@ -909,6 +1213,7 @@ function buildConflictMessage({
   centerIdx,
   changedRanges,
   retryChecksum,
+  remaps,
   details
 }) {
   const safeCenter = Math.max(0, Math.min(lines.length - 1, centerIdx));
@@ -921,6 +1226,9 @@ file: ${fileChecksum}`;
 changed_ranges: ${describeChangedRanges(changedRanges)}`;
   if (retryChecksum) msg += `
 retry_checksum: ${retryChecksum}`;
+  if (remaps?.length) msg += `
+remapped_refs:
+${remaps.map(({ from, to }) => `${from} -> ${to}`).join("\n")}`;
   msg += `
 
 ${details}
@@ -934,11 +1242,137 @@ Tip: Retry from the fresh local snippet above.`;
 path: ${filePath}`;
   return msg;
 }
-function targetRangeForReplaceBetween(startIdx, endIdx, boundaryMode) {
-  if (boundaryMode === "exclusive") {
-    return { start: startIdx + 2, end: Math.max(startIdx + 1, endIdx) };
+function applySetLineEdit(edit, ctx) {
+  const { lines, opts, locateOrConflict, ensureRevisionContext } = ctx;
+  const { tag, line } = parseRef(edit.set_line.anchor);
+  const idx = locateOrConflict({ tag, line });
+  if (typeof idx === "string") return idx;
+  const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
+  if (conflict) return conflict;
+  const txt = edit.set_line.new_text;
+  if (!txt && txt !== 0) {
+    lines.splice(idx, 1);
+    return null;
   }
-  return { start: startIdx + 1, end: endIdx + 1 };
+  const origLine = [lines[idx]];
+  const raw = sanitizeEditText(txt).split("\n");
+  const newLines = opts.restoreIndent ? restoreIndent(origLine, raw) : raw;
+  lines.splice(idx, 1, ...newLines);
+  return null;
+}
+function applyInsertAfterEdit(edit, ctx) {
+  const { lines, opts, locateOrConflict, ensureRevisionContext } = ctx;
+  const { tag, line } = parseRef(edit.insert_after.anchor);
+  const idx = locateOrConflict({ tag, line });
+  if (typeof idx === "string") return idx;
+  const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
+  if (conflict) return conflict;
+  let insertLines = sanitizeEditText(edit.insert_after.text).split("\n");
+  if (opts.restoreIndent) insertLines = restoreIndent([lines[idx]], insertLines);
+  lines.splice(idx + 1, 0, ...insertLines);
+  return null;
+}
+function applyReplaceLinesEdit(edit, ctx) {
+  const {
+    baseSnapshot,
+    buildStrictChecksumMismatchError,
+    conflictIfNeeded,
+    currentSnapshot,
+    ensureRevisionContext,
+    hasBaseSnapshot,
+    lines,
+    locateOrConflict,
+    opts,
+    origLines,
+    staleRevision
+  } = ctx;
+  const startRef = parseRef(edit.replace_lines.start_anchor);
+  const endRef = parseRef(edit.replace_lines.end_anchor);
+  const startIdx = locateOrConflict(startRef);
+  if (typeof startIdx === "string") return startIdx;
+  const endIdx = locateOrConflict(endRef);
+  if (typeof endIdx === "string") return endIdx;
+  const actualStart = startIdx + 1;
+  const actualEnd = endIdx + 1;
+  const rangeChecksum2 = edit.replace_lines.range_checksum;
+  if (!rangeChecksum2) {
+    throw new Error("range_checksum required for replace_lines. Read the range first via read_file, then pass its checksum. The checksum range must cover start-to-end anchors (inclusive).");
+  }
+  if (staleRevision && opts.conflictPolicy === "conservative") {
+    const conflict = ensureRevisionContext(actualStart, actualEnd, startIdx);
+    if (conflict) return conflict;
+    const baseCheck = hasBaseSnapshot ? verifyChecksumAgainstSnapshot(baseSnapshot, rangeChecksum2) : null;
+    if (!baseCheck?.ok) {
+      return conflictIfNeeded(
+        "stale_checksum",
+        startIdx,
+        baseCheck?.actual || null,
+        baseCheck?.actual ? `Provided checksum ${rangeChecksum2} does not match base revision ${opts.baseRevision}.` : `Checksum range from ${rangeChecksum2} is outside the available base revision.`
+      );
+    }
+  } else {
+    const coverage = validateChecksumCoverage(rangeChecksum2, actualStart, actualEnd);
+    const { start: csStart, end: csEnd, hex: csHex } = parseChecksum(rangeChecksum2);
+    if (!coverage.ok) {
+      const snip = buildErrorSnippet(origLines, actualStart - 1);
+      throw new Error(
+        `${coverage.reason}
+
+Current content (lines ${snip.start}-${snip.end}):
+${snip.text}
+
+Tip: Use updated hashes above for retry.`
+      );
+    }
+    const actual = buildRangeChecksum(currentSnapshot, csStart, csEnd);
+    const actualHex = actual?.split(":")[1];
+    if (!actual || csHex !== actualHex) {
+      const details = `CHECKSUM_MISMATCH: expected ${rangeChecksum2}, got ${actual}. Content at lines ${csStart}-${csEnd} differs from when you read it.
+Recovery: read_file path ranges=["${csStart}-${csEnd}"], then retry edit with fresh checksum.`;
+      if (opts.conflictPolicy === "conservative") {
+        return conflictIfNeeded("stale_checksum", csStart - 1, actual, details);
+      }
+      throw buildStrictChecksumMismatchError(details, csStart, actual);
+    }
+  }
+  const txt = edit.replace_lines.new_text;
+  if (!txt && txt !== 0) {
+    lines.splice(startIdx, endIdx - startIdx + 1);
+    return null;
+  }
+  const origRange = lines.slice(startIdx, endIdx + 1);
+  let newLines = sanitizeEditText(txt).split("\n");
+  if (opts.restoreIndent) newLines = restoreIndent(origRange, newLines);
+  lines.splice(startIdx, endIdx - startIdx + 1, ...newLines);
+  return null;
+}
+function applyReplaceBetweenEdit(edit, ctx) {
+  const { lines, opts, locateOrConflict, ensureRevisionContext } = ctx;
+  const boundaryMode = edit.replace_between.boundary_mode || "inclusive";
+  if (boundaryMode !== "inclusive" && boundaryMode !== "exclusive") {
+    throw new Error(`BAD_INPUT: replace_between boundary_mode must be inclusive or exclusive, got ${boundaryMode}`);
+  }
+  const startRef = parseRef(edit.replace_between.start_anchor);
+  const endRef = parseRef(edit.replace_between.end_anchor);
+  const startIdx = locateOrConflict(startRef);
+  if (typeof startIdx === "string") return startIdx;
+  const endIdx = locateOrConflict(endRef);
+  if (typeof endIdx === "string") return endIdx;
+  if (startIdx > endIdx) {
+    throw new Error(`BAD_INPUT: replace_between start anchor resolves after end anchor (${startIdx + 1} > ${endIdx + 1})`);
+  }
+  const targetRange = targetRangeForReplaceBetween(startIdx, endIdx, boundaryMode);
+  const conflict = ensureRevisionContext(targetRange.start, targetRange.end, startIdx);
+  if (conflict) return conflict;
+  const txt = edit.replace_between.new_text;
+  let newLines = sanitizeEditText(txt ?? "").split("\n");
+  const sliceStart = boundaryMode === "exclusive" ? startIdx + 1 : startIdx;
+  const removeCount = boundaryMode === "exclusive" ? Math.max(0, endIdx - startIdx - 1) : endIdx - startIdx + 1;
+  const origRange = lines.slice(sliceStart, sliceStart + removeCount);
+  if (opts.restoreIndent && origRange.length > 0) newLines = restoreIndent(origRange, newLines);
+  if (txt === "" || txt === null) newLines = [];
+  lines.splice(sliceStart, removeCount, ...newLines);
+  return null;
 }
 function editFile(filePath, edits, opts = {}) {
   filePath = normalizePath(filePath);
@@ -955,49 +1389,11 @@ function editFile(filePath, edits, opts = {}) {
   const hadTrailingNewline = original.endsWith("\n");
   const hashIndex = currentSnapshot.uniqueTagIndex;
   let autoRebased = false;
-  const anchored = [];
-  for (const e of edits) {
-    if (e.set_line || e.replace_lines || e.insert_after || e.replace_between) anchored.push(e);
-    else if (e.replace) throw new Error("REPLACE_REMOVED: replace is no longer supported in edit_file. Use set_line/replace_lines for single edits, bulk_replace tool for rename/refactor.");
-    else throw new Error(`BAD_INPUT: unknown edit type: ${JSON.stringify(e)}`);
-  }
-  const editTargets = [];
-  for (const e of anchored) {
-    if (e.set_line) {
-      const line = parseRef(e.set_line.anchor).line;
-      editTargets.push({ start: line, end: line });
-    } else if (e.replace_lines) {
-      const s = parseRef(e.replace_lines.start_anchor).line;
-      const en = parseRef(e.replace_lines.end_anchor).line;
-      editTargets.push({ start: s, end: en });
-    } else if (e.insert_after) {
-      const line = parseRef(e.insert_after.anchor).line;
-      editTargets.push({ start: line, end: line, insert: true });
-    } else if (e.replace_between) {
-      const s = parseRef(e.replace_between.start_anchor).line;
-      const en = parseRef(e.replace_between.end_anchor).line;
-      editTargets.push({ start: s, end: en });
-    }
-  }
-  for (let i = 0; i < editTargets.length; i++) {
-    for (let j = i + 1; j < editTargets.length; j++) {
-      const a = editTargets[i], b = editTargets[j];
-      if (a.insert || b.insert) continue;
-      if (a.start <= b.end && b.start <= a.end) {
-        throw new Error(
-          `OVERLAPPING_EDITS: lines ${a.start}-${a.end} and ${b.start}-${b.end} overlap. Split into separate edit_file calls.`
-        );
-      }
-    }
-  }
-  const sorted = anchored.map((e) => {
-    let sortKey;
-    if (e.set_line) sortKey = parseRef(e.set_line.anchor).line;
-    else if (e.replace_lines) sortKey = parseRef(e.replace_lines.start_anchor).line;
-    else if (e.insert_after) sortKey = parseRef(e.insert_after.anchor).line;
-    else if (e.replace_between) sortKey = parseRef(e.replace_between.start_anchor).line;
-    return { ...e, _k: sortKey };
-  }).sort((a, b) => b._k - a._k);
+  const remaps = [];
+  const remapKeys = /* @__PURE__ */ new Set();
+  const anchored = normalizeAnchoredEdits(edits);
+  assertNonOverlappingTargets(collectEditTargets(anchored));
+  const sorted = sortEditsForApply(anchored);
   const conflictIfNeeded = (reason, centerIdx, retryChecksum, details) => {
     if (conflictPolicy !== "conservative") {
       throw new Error(details);
@@ -1011,12 +1407,24 @@ function editFile(filePath, edits, opts = {}) {
       centerIdx,
       changedRanges: staleRevision && hasBaseSnapshot ? changedRanges : null,
       retryChecksum,
+      remaps,
       details
     });
   };
+  const trackRemap = (ref, idx) => {
+    const actualRef = `${lineTag(fnv1a(lines[idx]))}.${idx + 1}`;
+    const expectedRef = `${ref.tag}.${ref.line}`;
+    if (actualRef === expectedRef) return;
+    const key = `${expectedRef}->${actualRef}`;
+    if (remapKeys.has(key)) return;
+    remapKeys.add(key);
+    remaps.push({ from: expectedRef, to: actualRef });
+  };
   const locateOrConflict = (ref, reason = "stale_anchor") => {
     try {
-      return findLine(lines, ref.line, ref.tag, hashIndex);
+      const idx = findLine(lines, ref.line, ref.tag, hashIndex);
+      trackRemap(ref, idx);
+      return idx;
     } catch (e) {
       if (conflictPolicy !== "conservative" || !staleRevision) throw e;
       const centerIdx = Math.max(0, Math.min(lines.length - 1, ref.line - 1));
@@ -1030,7 +1438,7 @@ function editFile(filePath, edits, opts = {}) {
         "base_revision_evicted",
         centerIdx,
         null,
-        `Base revision ${opts.baseRevision} is not available in the local revision cache.`
+        `Base revision ${opts.baseRevision} is not available in the local revision cache. Recovery: re-read the file with read_file to get a fresh revision, then retry.`
       );
     }
     if (overlapsChangedRanges(changedRanges, actualStart, actualEnd)) {
@@ -1038,134 +1446,45 @@ function editFile(filePath, edits, opts = {}) {
         "overlap",
         centerIdx,
         null,
-        `Changes since ${opts.baseRevision} overlap edit range ${actualStart}-${actualEnd}.`
+        `Changes since ${opts.baseRevision} overlap edit range ${actualStart}-${actualEnd}. Recovery: re-read lines ${actualStart}-${actualEnd} with read_file, then retry with fresh anchors and checksum.`
       );
     }
     autoRebased = true;
     return null;
   };
-  for (let _ei = 0; _ei < sorted.length; _ei++) {
-    const e = sorted[_ei];
-    try {
-      if (e.set_line) {
-        const { tag, line } = parseRef(e.set_line.anchor);
-        const idx = locateOrConflict({ tag, line });
-        if (typeof idx === "string") return idx;
-        const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
-        if (conflict) return conflict;
-        const txt = e.set_line.new_text;
-        if (!txt && txt !== 0) {
-          lines.splice(idx, 1);
-        } else {
-          const origLine = [lines[idx]];
-          const raw = String(txt).split("\n");
-          const newLines = opts.restoreIndent ? restoreIndent(origLine, raw) : raw;
-          lines.splice(idx, 1, ...newLines);
-        }
-        continue;
-      }
-      if (e.insert_after) {
-        const { tag, line } = parseRef(e.insert_after.anchor);
-        const idx = locateOrConflict({ tag, line });
-        if (typeof idx === "string") return idx;
-        const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
-        if (conflict) return conflict;
-        let insertLines = e.insert_after.text.split("\n");
-        if (opts.restoreIndent) insertLines = restoreIndent([lines[idx]], insertLines);
-        lines.splice(idx + 1, 0, ...insertLines);
-        continue;
-      }
-      if (e.replace_lines) {
-        const s = parseRef(e.replace_lines.start_anchor);
-        const en = parseRef(e.replace_lines.end_anchor);
-        const si = locateOrConflict(s);
-        if (typeof si === "string") return si;
-        const ei = locateOrConflict(en);
-        if (typeof ei === "string") return ei;
-        const actualStart = si + 1;
-        const actualEnd = ei + 1;
-        const rc = e.replace_lines.range_checksum;
-        if (!rc) throw new Error("range_checksum required for replace_lines. Read the range first via read_file, then pass its checksum. The checksum range must cover start-to-end anchors (inclusive).");
-        if (staleRevision && conflictPolicy === "conservative") {
-          const conflict = ensureRevisionContext(actualStart, actualEnd, si);
-          if (conflict) return conflict;
-          const baseCheck = hasBaseSnapshot ? verifyChecksumAgainstSnapshot(baseSnapshot, rc) : null;
-          if (!baseCheck?.ok) {
-            return conflictIfNeeded(
-              "stale_checksum",
-              si,
-              baseCheck?.actual || null,
-              baseCheck?.actual ? `Provided checksum ${rc} does not match base revision ${opts.baseRevision}.` : `Checksum range from ${rc} is outside the available base revision.`
-            );
-          }
-        } else {
-          const { start: csStart, end: csEnd, hex: csHex } = parseChecksum(rc);
-          if (csStart > actualStart || csEnd < actualEnd) {
-            const snip = buildErrorSnippet(origLines, actualStart - 1);
-            throw new Error(
-              `CHECKSUM_RANGE_GAP: checksum covers lines ${csStart}-${csEnd} but edit spans ${actualStart}-${actualEnd} (inclusive). Checksum range must fully contain the anchor range.
-
-Current content (lines ${snip.start}-${snip.end}):
-${snip.text}
-
-Tip: Use updated hashes above for retry.`
-            );
-          }
-          const actual = buildRangeChecksum(currentSnapshot, csStart, csEnd);
-          const actualHex = actual?.split(":")[1];
-          if (!actual || csHex !== actualHex) {
-            const details = `CHECKSUM_MISMATCH: expected ${rc}, got ${actual}. Content at lines ${csStart}-${csEnd} differs from when you read it \u2014 re-read before editing.`;
-            if (conflictPolicy === "conservative") {
-              return conflictIfNeeded("stale_checksum", csStart - 1, actual, details);
-            }
-            const snip = buildErrorSnippet(origLines, csStart - 1);
-            throw new Error(
-              `${details}
+  const buildStrictChecksumMismatchError = (details, checksumStart, actual) => {
+    const snip = buildErrorSnippet(origLines, checksumStart - 1);
+    return new Error(
+      `${details}
 
 Current content (lines ${snip.start}-${snip.end}):
 ${snip.text}
 
 Retry with fresh checksum ${actual}, or use set_line with hashes above.`
-            );
-          }
-        }
-        const txt = e.replace_lines.new_text;
-        if (!txt && txt !== 0) {
-          lines.splice(si, ei - si + 1);
-        } else {
-          const origRange = lines.slice(si, ei + 1);
-          let newLines = String(txt).split("\n");
-          if (opts.restoreIndent) newLines = restoreIndent(origRange, newLines);
-          lines.splice(si, ei - si + 1, ...newLines);
-        }
-        continue;
-      }
-      if (e.replace_between) {
-        const boundaryMode = e.replace_between.boundary_mode || "inclusive";
-        if (boundaryMode !== "inclusive" && boundaryMode !== "exclusive") {
-          throw new Error(`BAD_INPUT: replace_between boundary_mode must be inclusive or exclusive, got ${boundaryMode}`);
-        }
-        const s = parseRef(e.replace_between.start_anchor);
-        const en = parseRef(e.replace_between.end_anchor);
-        const si = locateOrConflict(s);
-        if (typeof si === "string") return si;
-        const ei = locateOrConflict(en);
-        if (typeof ei === "string") return ei;
-        if (si > ei) {
-          throw new Error(`BAD_INPUT: replace_between start anchor resolves after end anchor (${si + 1} > ${ei + 1})`);
-        }
-        const targetRange = targetRangeForReplaceBetween(si, ei, boundaryMode);
-        const conflict = ensureRevisionContext(targetRange.start, targetRange.end, si);
-        if (conflict) return conflict;
-        const txt = e.replace_between.new_text;
-        let newLines = String(txt ?? "").split("\n");
-        const sliceStart = boundaryMode === "exclusive" ? si + 1 : si;
-        const removeCount = boundaryMode === "exclusive" ? Math.max(0, ei - si - 1) : ei - si + 1;
-        const origRange = lines.slice(sliceStart, sliceStart + removeCount);
-        if (opts.restoreIndent && origRange.length > 0) newLines = restoreIndent(origRange, newLines);
-        if (txt === "" || txt === null) newLines = [];
-        lines.splice(sliceStart, removeCount, ...newLines);
-      }
+    );
+  };
+  const editContext = {
+    baseSnapshot,
+    buildStrictChecksumMismatchError,
+    conflictIfNeeded,
+    currentSnapshot,
+    ensureRevisionContext,
+    hasBaseSnapshot,
+    lines,
+    locateOrConflict,
+    opts,
+    origLines,
+    staleRevision
+  };
+  for (let _ei = 0; _ei < sorted.length; _ei++) {
+    const e = sorted[_ei];
+    try {
+      let conflictResult = null;
+      if (e.set_line) conflictResult = applySetLineEdit(e, editContext);
+      else if (e.insert_after) conflictResult = applyInsertAfterEdit(e, editContext);
+      else if (e.replace_lines) conflictResult = applyReplaceLinesEdit(e, editContext);
+      else if (e.replace_between) conflictResult = applyReplaceBetweenEdit(e, editContext);
+      if (typeof conflictResult === "string") return conflictResult;
     } catch (editErr) {
       if (sorted.length > 1) editErr.message = `Edit ${_ei + 1}/${sorted.length}: ${editErr.message}`;
       throw editErr;
@@ -1219,25 +1538,24 @@ file: ${nextSnapshot.fileChecksum}`;
   if (autoRebased && staleRevision && hasBaseSnapshot) {
     msg += `
 changed_ranges: ${describeChangedRanges(changedRanges)}`;
+  }
+  if (remaps.length > 0) {
+    msg += `
+remapped_refs:
+${remaps.map(({ from, to }) => `${from} -> ${to}`).join("\n")}`;
   }
   msg += `
 Updated ${filePath} (${content.split("\n").length} lines)`;
   if (fullDiff && minLine <= maxLine) {
-    const ctxStart = Math.max(0, minLine - 6);
+    const ctxStart = Math.max(0, minLine - 6) + 1;
     const ctxEnd = Math.min(newLinesAll.length, maxLine + 5);
-    const ctxLines = [];
-    const ctxHashes = [];
-    for (let i = ctxStart; i < ctxEnd; i++) {
-      const h = fnv1a(newLinesAll[i]);
-      ctxHashes.push(h);
-      ctxLines.push(`${lineTag(h)}.${i + 1}	${newLinesAll[i]}`);
-    }
-    const ctxCs = rangeChecksum(ctxHashes, ctxStart + 1, ctxEnd);
-    msg += `
+    const entries = createSnapshotEntries(nextSnapshot, ctxStart, ctxEnd);
+    if (entries.length > 0) {
+      const block = buildEditReadyBlock({ path: real, kind: "post_edit", entries });
+      msg += `
 
-Post-edit (lines ${ctxStart + 1}-${ctxEnd}):
-${ctxLines.join("\n")}
-checksum: ${ctxCs}`;
+${serializeReadBlock(block)}`;
+    }
   }
   try {
     const db = getGraphDB(real);
@@ -1334,9 +1652,7 @@ async function filesMode(pattern, target, opts) {
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const lines = stdout.trimEnd().split("\n").filter(Boolean);
   const normalized = lines.map((l) => l.replace(/\\/g, "/"));
-  return `\`\`\`
-${normalized.join("\n")}
-\`\`\``;
+  return normalized.join("\n");
 }
 async function countMode(pattern, target, opts) {
   const realArgs = ["-c"];
@@ -1353,9 +1669,7 @@ async function countMode(pattern, target, opts) {
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const lines = stdout.trimEnd().split("\n").filter(Boolean);
   const normalized = lines.map((l) => l.replace(/\\/g, "/"));
-  return `\`\`\`
-${normalized.join("\n")}
-\`\`\``;
+  return normalized.join("\n");
 }
 async function contentMode(pattern, target, opts, plain, totalLimit) {
   const realArgs = ["--json"];
@@ -1376,21 +1690,33 @@ async function contentMode(pattern, target, opts, plain, totalLimit) {
   if (code === 1) return "No matches found.";
   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 formatted = [];
+  const blocks = [];
   const db = getGraphDB(target);
   const relCache = /* @__PURE__ */ new Map();
   let groupFile = null;
-  let groupLines = [];
+  let groupEntries = [];
   let matchCount = 0;
   function flushGroup() {
-    if (groupLines.length === 0) return;
-    const sorted = [...groupLines].sort((a, b) => a.lineNum - b.lineNum);
-    const start = sorted[0].lineNum;
-    const end = sorted[sorted.length - 1].lineNum;
-    const hashes = sorted.map((l) => l.hash32);
-    const cs = rangeChecksum(hashes, start, end);
-    formatted.push(`checksum: ${cs}`);
-    groupLines = [];
+    if (groupEntries.length === 0) return;
+    const matchLines = groupEntries.filter((entry) => entry.role === "match").map((entry) => entry.lineNumber);
+    let graphScore = 0;
+    let defs = 0;
+    let usages = 0;
+    for (const entry of groupEntries) {
+      if (!entry.annotation) continue;
+      const callerMatch = entry.annotation.match(/(\d+)\u2191/);
+      if (callerMatch) graphScore += parseInt(callerMatch[1], 10);
+      if (/\[fn|\[cls|\[mtd/.test(entry.annotation)) defs++;
+      else usages++;
+    }
+    const summary = defs || usages ? `${defs} definition(s), ${usages} usage(s)` : null;
+    blocks.push(buildEditReadyBlock({
+      path: groupFile,
+      kind: "search_hunk",
+      entries: groupEntries,
+      meta: { matchLines, graphScore, ...summary ? { summary } : {} }
+    }));
+    groupEntries = [];
   }
   for (const jl of jsonLines) {
     let msg;
@@ -1404,11 +1730,6 @@ async function contentMode(pattern, target, opts, plain, totalLimit) {
         flushGroup();
         groupFile = null;
       }
-      if (msg.type === "begin") {
-        if (formatted.length > 0 && formatted[formatted.length - 1] !== "") {
-          formatted.push("");
-        }
-      }
       continue;
     }
     if (msg.type !== "match" && msg.type !== "context") continue;
@@ -1430,48 +1751,46 @@ async function contentMode(pattern, target, opts, plain, totalLimit) {
     for (let i = 0; i < subLines.length; i++) {
       const ln = lineNum + i;
       const lineContent = subLines[i];
-      const hash32 = fnv1a(lineContent);
-      const tag = lineTag(hash32);
-      if (groupLines.length > 0) {
-        const lastLn = groupLines[groupLines.length - 1].lineNum;
+      if (groupEntries.length > 0) {
+        const lastLn = groupEntries[groupEntries.length - 1].lineNumber;
         if (ln > lastLn + 1) flushGroup();
       }
-      groupLines.push({ lineNum: ln, hash32 });
       const isMatch = msg.type === "match";
-      if (plain) {
-        formatted.push(`${filePath}:${ln}:${lineContent}`);
-      } else {
-        let anno = "";
-        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) anno = `  ${a}`;
-          }
+      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;
         }
-        const prefix = isMatch ? ">>" : "  ";
-        formatted.push(`${filePath}:${prefix}${tag}.${ln}	${lineContent}${anno}`);
       }
+      groupEntries.push({
+        lineNumber: ln,
+        text: lineContent,
+        role: isMatch ? "match" : "context",
+        annotation
+      });
     }
     if (msg.type === "match") {
       matchCount++;
       if (totalLimit > 0 && matchCount >= totalLimit) {
         flushGroup();
-        formatted.push(`--- total_limit reached (${totalLimit}) ---`);
-        return `\`\`\`
-${formatted.join("\n")}
-\`\`\``;
+        blocks.push(buildDiagnosticBlock({
+          kind: "total_limit",
+          message: `Search stopped after ${totalLimit} match event(s). Narrow the query to continue.`,
+          path: String(target).replace(/\\/g, "/")
+        }));
+        return blocks.map((block) => block.type === "edit_ready_block" ? serializeSearchBlock(block, { plain }) : serializeDiagnosticBlock(block)).join("\n\n");
       }
     }
   }
   flushGroup();
-  return `\`\`\`
-${formatted.join("\n")}
-\`\`\``;
+  if (db) blocks.sort((a, b) => (b.meta.graphScore || 0) - (a.meta.graphScore || 0));
+  return blocks.map((block) => block.type === "edit_ready_block" ? serializeSearchBlock(block, { plain }) : serializeDiagnosticBlock(block)).join("\n\n");
 }
 
 // lib/outline.mjs
@@ -1535,15 +1854,6 @@ function supportedExtensions() {
   return Object.keys(EXTENSION_GRAMMARS);
 }
 
-// ../hex-common/src/text/file-text.mjs
-import { readFileSync as readFileSync2 } from "node:fs";
-function normalizeSourceText(text) {
-  return text.replace(/\r\n/g, "\n");
-}
-function readUtf8Normalized(filePath) {
-  return normalizeSourceText(readFileSync2(filePath, "utf-8"));
-}
-
 // lib/outline.mjs
 var LANG_CONFIGS = {
   ".js": { outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
@@ -1564,7 +1874,9 @@ var LANG_CONFIGS = {
   ".kt": { outline: ["function_declaration", "class_declaration", "object_declaration"], skip: ["import_header"], recurse: ["class_body"] },
   ".swift": { outline: ["function_declaration", "class_declaration", "struct_declaration", "protocol_declaration"], skip: ["import_declaration"], recurse: ["class_body"] },
   ".sh": { outline: ["function_definition"], skip: [], recurse: [] },
-  ".bash": { outline: ["function_definition"], skip: [], recurse: [] }
+  ".bash": { outline: ["function_definition"], skip: [], recurse: [] },
+  ".md": { outline: [], skip: [], recurse: [] },
+  ".mdx": { outline: [], skip: [], recurse: [] }
 };
 function extractOutline(rootNode, config, sourceLines) {
   const entries = [];
@@ -1609,6 +1921,59 @@ function extractOutline(rootNode, config, sourceLines) {
   walk(rootNode, 0);
   return { entries, skippedRanges };
 }
+function fallbackOutline(sourceLines) {
+  const entries = [];
+  for (let index = 0; index < sourceLines.length; index++) {
+    const line = sourceLines[index];
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(
+      /^(?:export\s+)?(?:async\s+)?function\s+[\w$]+|^(?:export\s+)?(?:const|let|var)\s+[\w$]+\s*=|^(?:export\s+)?class\s+[\w$]+|^(?:export\s+)?interface\s+[\w$]+|^(?:export\s+)?type\s+[\w$]+\s*=|^(?:export\s+)?enum\s+[\w$]+|^(?:export\s+default\s+)?[\w$]+\s*=>/
+    );
+    if (!match) continue;
+    entries.push({
+      start: index + 1,
+      end: index + 1,
+      depth: 0,
+      text: trimmed.slice(0, 120),
+      name: trimmed.match(/([\w$]+)/)?.[1] || null
+    });
+  }
+  return entries;
+}
+function markdownOutline(sourceLines) {
+  const entries = [];
+  let activeFence = null;
+  for (let index = 0; index < sourceLines.length; index++) {
+    const line = sourceLines[index];
+    const fenceMatch = line.match(/^\s{0,3}(```+|~~~+).*$/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1][0];
+      const length = fenceMatch[1].length;
+      if (!activeFence) {
+        activeFence = { marker, length };
+        continue;
+      }
+      if (activeFence.marker === marker && length >= activeFence.length) {
+        activeFence = null;
+        continue;
+      }
+    }
+    if (activeFence) continue;
+    const match = line.match(/^\s{0,3}(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (!match) continue;
+    const level = match[1].length;
+    const title = match[2].trim();
+    entries.push({
+      start: index + 1,
+      end: index + 1,
+      depth: level - 1,
+      text: title.slice(0, 120),
+      name: title.split(/\s+/)[0] || null
+    });
+  }
+  return entries;
+}
 async function outlineFromContent(content, ext) {
   const config = LANG_CONFIGS[ext];
   const grammar = grammarForExtension(ext);
@@ -1625,8 +1990,9 @@ async function outlineFromContent(content, ext) {
   const tree = parser.parse(content);
   return extractOutline(tree.rootNode, config, sourceLines);
 }
-function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile) {
+function formatOutline(entries, skippedRanges, sourceLineCount, snapshot, db, relFile, note = "") {
   const lines = [];
+  if (note) lines.push(note, "");
   if (skippedRanges.length > 0) {
     const first = skippedRanges[0].start;
     const last = skippedRanges[skippedRanges.length - 1].end;
@@ -1637,7 +2003,9 @@ function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile) {
     const indent = "  ".repeat(e.depth);
     const anno = db ? symbolAnnotation(db, relFile, e.name) : null;
     const suffix = anno ? `  ${anno}` : "";
-    lines.push(`${indent}${e.start}-${e.end}: ${e.text}${suffix}`);
+    const tag = snapshot && snapshot.lineHashes[e.start - 1] ? lineTag(snapshot.lineHashes[e.start - 1]) : null;
+    const prefix = tag ? `${tag}.` : "";
+    lines.push(`${indent}${prefix}${e.start}-${e.end}: ${e.text}${suffix}`);
   }
   lines.push("");
   lines.push(`(${entries.length} symbols, ${sourceLineCount} source lines)`);
@@ -1650,61 +2018,136 @@ async function fileOutline(filePath) {
   if (!LANG_CONFIGS[ext]) {
     return `Outline unavailable for ${ext} files. Use read_file directly for non-code files (markdown, config, text). Supported code extensions: ${supportedExtensions().join(", ")}`;
   }
-  const content = readUtf8Normalized(real);
-  const result = await outlineFromContent(content, ext);
+  const snapshot = readSnapshot(real);
+  const isMarkdown = ext === ".md" || ext === ".mdx";
+  const result = isMarkdown ? null : await outlineFromContent(snapshot.content, ext);
+  let entries;
+  let skippedRanges = [];
+  let note = "";
+  if (result && result.entries.length > 0) {
+    entries = result.entries;
+    skippedRanges = result.skippedRanges;
+  } else if (isMarkdown) {
+    entries = markdownOutline(snapshot.lines);
+  } else {
+    entries = fallbackOutline(snapshot.lines);
+    if (entries.length > 0) note = "Fallback outline: heuristic symbols shown because parser returned no structural entries.";
+  }
   const db = getGraphDB(real);
   const relFile = db ? getRelativePath(real) : null;
   return `File: ${filePath}
 
-${formatOutline(result.entries, result.skippedRanges, content.split("\n").length, db, relFile)}`;
+${formatOutline(entries, skippedRanges, snapshot.lines.length, snapshot, db, relFile, note)}`;
 }
 
 // lib/verify.mjs
+function parseChecksumEntry(raw) {
+  try {
+    return { ok: true, raw, parsed: parseChecksum(raw) };
+  } catch (error) {
+    return {
+      ok: false,
+      raw,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function classifyChecksum(currentSnapshot, entry) {
+  if (!entry.ok) {
+    return {
+      status: "INVALID",
+      checksum: entry.raw,
+      span: null,
+      currentChecksum: null,
+      reason: `invalid checksum format: ${entry.error}`
+    };
+  }
+  const { start, end } = entry.parsed;
+  if (start < 1 || end < start) {
+    return {
+      status: "INVALID",
+      checksum: entry.raw,
+      span: `${start}-${end}`,
+      currentChecksum: null,
+      reason: `invalid range ${start}-${end}`
+    };
+  }
+  if (end > currentSnapshot.lines.length) {
+    return {
+      status: "INVALID",
+      checksum: entry.raw,
+      span: `${start}-${end}`,
+      currentChecksum: null,
+      reason: `range ${start}-${end} exceeds file length ${currentSnapshot.lines.length}`
+    };
+  }
+  const currentChecksum = buildRangeChecksum(currentSnapshot, start, end);
+  if (currentChecksum === entry.raw) {
+    return {
+      status: "VALID",
+      checksum: entry.raw,
+      span: `${start}-${end}`,
+      currentChecksum,
+      reason: null
+    };
+  }
+  return {
+    status: "STALE",
+    checksum: entry.raw,
+    span: `${start}-${end}`,
+    currentChecksum,
+    reason: `content changed since the checksum was captured. Recovery: read_file ranges=["${start}-${end}"] to get fresh content.`
+  };
+}
+function summarizeStatuses(entries) {
+  return entries.reduce((acc, entry) => {
+    const key = entry.status.toLowerCase();
+    acc[key] += 1;
+    return acc;
+  }, { valid: 0, stale: 0, invalid: 0 });
+}
+function renderEntry(entry) {
+  const base = `checksum: ${entry.checksum}`;
+  if (entry.status === "VALID") {
+    return `${entry.status} ${entry.span} ${base}`;
+  }
+  if (entry.status === "STALE") {
+    return `${entry.status} ${entry.span} ${base} current=${entry.currentChecksum} | re-read to refresh`;
+  }
+  return `${entry.status}${entry.span ? ` ${entry.span}` : ""} ${base} reason=${entry.reason}`;
+}
 function verifyChecksums(filePath, checksums, opts = {}) {
   filePath = normalizePath(filePath);
   const real = validatePath(filePath);
-  const current = readSnapshot(real);
+  const currentSnapshot = readSnapshot(real);
   const baseSnapshot = opts.baseRevision ? getSnapshotByRevision(opts.baseRevision) : null;
-  const results = [];
-  let allValid = true;
-  for (const cs of checksums) {
-    const parsed = parseChecksum(cs);
-    if (parsed.start < 1 || parsed.end > current.lines.length) {
-      results.push(`${cs}: INVALID (range ${parsed.start}-${parsed.end} exceeds file length ${current.lines.length})`);
-      allValid = false;
-      continue;
-    }
-    const actual = buildRangeChecksum(current, parsed.start, parsed.end);
-    const currentHex = actual.split(":")[1];
-    if (currentHex === parsed.hex) {
-      results.push(`${cs}: valid`);
+  const hasBaseSnapshot = !!(baseSnapshot && baseSnapshot.path === real);
+  const parsedEntries = (checksums || []).map(parseChecksumEntry);
+  const results = parsedEntries.map((entry) => classifyChecksum(currentSnapshot, entry));
+  const summary = summarizeStatuses(results);
+  const status = summary.invalid > 0 ? "INVALID" : summary.stale > 0 ? "STALE" : "OK";
+  const lines = [
+    `status: ${status}`,
+    `revision: ${currentSnapshot.revision}`,
+    `file: ${currentSnapshot.fileChecksum}`,
+    `summary: valid=${summary.valid} stale=${summary.stale} invalid=${summary.invalid}`
+  ];
+  if (opts.baseRevision) {
+    lines.push(`base_revision: ${opts.baseRevision}`);
+    if (hasBaseSnapshot) {
+      lines.push(`changed_ranges: ${describeChangedRanges(computeChangedRanges(baseSnapshot.lines, currentSnapshot.lines))}`);
     } else {
-      const staleBits = [`${cs}: STALE \u2192 current: ${actual}`];
-      if (baseSnapshot?.path === real) {
-        const changedRanges = computeChangedRanges(baseSnapshot.lines, current.lines);
-        staleBits.push(`revision: ${current.revision}`);
-        staleBits.push(`changed_ranges: ${describeChangedRanges(changedRanges)}`);
-      } else if (opts.baseRevision) {
-        staleBits.push(`revision: ${current.revision}`);
-        staleBits.push(`changed_ranges: unavailable (base revision evicted)`);
-      }
-      results.push(staleBits.join("\n"));
-      allValid = false;
+      lines.push("base_revision_status: evicted");
     }
   }
-  if (allValid && checksums.length > 0) {
-    let msg = `All ${checksums.length} checksum(s) valid for ${filePath}`;
-    msg += `
-revision: ${current.revision}`;
-    msg += `
-file: ${current.fileChecksum}`;
-    return msg;
+  if (results.length > 0) {
+    lines.push("", ...results.map(renderEntry));
   }
-  return results.join("\n");
+  return lines.join("\n");
 }
 
 // lib/tree.mjs
-import { readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync6, existsSync as existsSync4 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync2, statSync as statSync6, existsSync as existsSync4 } 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([
@@ -1725,7 +2168,7 @@ function loadGitignore(rootDir) {
   const gi = join4(rootDir, ".gitignore");
   if (!existsSync4(gi)) return null;
   try {
-    const content = readFileSync3(gi, "utf-8");
+    const content = readFileSync2(gi, "utf-8");
     return ignore().add(content);
   } catch {
     return null;
@@ -1971,7 +2414,7 @@ function fileInfo(filePath) {
 }
 
 // lib/setup.mjs
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync, copyFileSync } from "node:fs";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync, copyFileSync } from "node:fs";
 import { resolve as resolve6, dirname as dirname3, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -1999,7 +2442,7 @@ var CLAUDE_HOOKS = {
 };
 function readJson(filePath) {
   if (!existsSync5(filePath)) return null;
-  return JSON.parse(readFileSync4(filePath, "utf-8"));
+  return JSON.parse(readFileSync3(filePath, "utf-8"));
 }
 function writeJson(filePath, data) {
   mkdirSync(dirname3(filePath), { recursive: true });
@@ -2078,7 +2521,7 @@ function installOutputStyle() {
   const source = resolve6(dirname3(fileURLToPath(import.meta.url)), "..", "output-style.md");
   const target = resolve6(homedir(), ".claude", "output-styles", "hex-line.md");
   mkdirSync(dirname3(target), { recursive: true });
-  writeFileSync2(target, readFileSync4(source, "utf-8"), "utf-8");
+  writeFileSync2(target, readFileSync3(source, "utf-8"), "utf-8");
   const userSettings = resolve6(homedir(), ".claude/settings.json");
   const config = readJson(userSettings) || {};
   const prev = config.outputStyle;
@@ -2275,7 +2718,7 @@ Summary: ${summary}`);
 }
 
 // lib/bulk-replace.mjs
-import { writeFileSync as writeFileSync3, readdirSync as readdirSync3 } from "node:fs";
+import { writeFileSync as writeFileSync3, readdirSync as readdirSync3, renameSync, unlinkSync } from "node:fs";
 import { resolve as resolve7, relative as relative3, join as join6 } from "node:path";
 var ignoreMod;
 try {
@@ -2348,7 +2791,17 @@ function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
         continue;
       }
       if (!dryRun) {
-        writeFileSync3(file, content, "utf-8");
+        const tempPath = `${file}.hexline-tmp-${process.pid}`;
+        try {
+          writeFileSync3(tempPath, content, "utf-8");
+          renameSync(tempPath, file);
+        } catch (error) {
+          try {
+            unlinkSync(tempPath);
+          } catch {
+          }
+          throw error;
+        }
       }
       const relPath = relative3(abs, file).replace(/\\/g, "/");
       totalReplacements += replacementCount;
@@ -2384,7 +2837,7 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
 }
 
 // server.mjs
-var version = true ? "1.4.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.6.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version
@@ -2392,43 +2845,43 @@ var { server, StdioServerTransport } = await createServerRuntime({
 var replacementPairsSchema = z2.array(
   z2.object({ old: z2.string().min(1), new: z2.string() })
 ).min(1);
-function coerceEdit(e) {
-  if (!e || typeof e !== "object" || Array.isArray(e)) return e;
-  if (e.set_line || e.replace_lines || e.insert_after || e.replace_between || e.replace) return e;
-  if (e.anchor && !e.start_anchor && !e.end_anchor && !e.boundary_mode && !e.range_checksum) {
-    const raw = e.new_text ?? e.updated_lines ?? e.content ?? e.line;
-    if (raw !== void 0) {
-      const text = Array.isArray(raw) ? raw.join("\n") : raw;
-      return { set_line: { anchor: e.anchor, new_text: text } };
-    }
-  }
-  if (e.start_anchor && e.end_anchor && e.boundary_mode && e.new_text !== void 0) {
-    return { replace_between: { start_anchor: e.start_anchor, end_anchor: e.end_anchor, new_text: e.new_text, boundary_mode: e.boundary_mode } };
-  }
-  if (e.start_anchor && e.end_anchor && e.new_text !== void 0) {
-    return { replace_lines: { start_anchor: e.start_anchor, end_anchor: e.end_anchor, new_text: e.new_text, ...e.range_checksum ? { range_checksum: e.range_checksum } : {} } };
+var readRangeSchema = z2.union([
+  z2.string(),
+  z2.object({
+    start: flexNum().optional(),
+    end: flexNum().optional()
+  })
+]);
+function parseReadRanges(rawRanges) {
+  if (!rawRanges) return void 0;
+  const parsed = Array.isArray(rawRanges) ? rawRanges : JSON.parse(rawRanges);
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error("ranges must be a non-empty array");
   }
-  return e;
+  return parsed;
 }
 server.registerTool("read_file", {
   title: "Read File",
-  description: "Read a file with hash-annotated lines, range checksums, and current revision. Use offset/limit for targeted reads; use outline first for large code files.",
+  description: "Read file with hash-annotated lines, checksums, and revision metadata. Default: edit-ready output. Use plain:true for non-edit workflows.",
   inputSchema: z2.object({
     path: z2.string().optional().describe("File or directory path"),
     paths: z2.array(z2.string()).optional().describe("Array of file paths to read (batch mode)"),
     offset: flexNum().describe("Start line (1-indexed, default: 1)"),
     limit: flexNum().describe("Max lines (default: 2000, 0 = all)"),
+    ranges: z2.union([z2.string(), z2.array(readRangeSchema)]).optional().describe('Line ranges, e.g. ["10-25", {"start":40,"end":55}]'),
+    include_graph: flexBool().describe("Include graph annotations"),
     plain: flexBool().describe("Omit hashes (lineNum|content)")
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
 }, async (rawParams) => {
-  const { path: p, paths: multi, offset, limit, plain } = coerceParams(rawParams);
+  const { path: p, paths: multi, offset, limit, ranges: rawRanges, include_graph, plain } = coerceParams(rawParams);
   try {
+    const ranges = parseReadRanges(rawRanges);
     if (multi && multi.length > 0 && !p) {
       const results = [];
       for (const fp of multi) {
         try {
-          results.push(readFile2(fp, { offset, limit, plain }));
+          results.push(readFile2(fp, { offset, limit, ranges, includeGraph: include_graph, plain }));
         } catch (e) {
           results.push(`File: ${fp}
 
@@ -2438,18 +2891,18 @@ ERROR: ${e.message}`);
       return { content: [{ type: "text", text: results.join("\n\n---\n\n") }] };
     }
     if (!p) throw new Error("Either 'path' or 'paths' is required");
-    return { content: [{ type: "text", text: readFile2(p, { offset, limit, plain }) }] };
+    return { content: [{ type: "text", text: readFile2(p, { offset, limit, ranges, includeGraph: include_graph, plain }) }] };
   } catch (e) {
     return { content: [{ type: "text", text: e.message }], isError: true };
   }
 });
 server.registerTool("edit_file", {
   title: "Edit File",
-  description: "Apply revision-aware partial edits to one file. Prefer one batched call per file. Supports set_line, replace_lines, insert_after, and replace_between. For text rename/refactor use bulk_replace.",
+  description: "Apply verified partial edits to one file.",
   inputSchema: z2.object({
     path: z2.string().describe("File to edit"),
     edits: z2.union([z2.string(), z2.array(z2.any())]).describe(
-      'JSON array. Types: set_line, replace_lines, insert_after, replace_between.\n[{"set_line":{"anchor":"ab.12","new_text":"x"}}]\n[{"replace_lines":{"start_anchor":"ab.10","end_anchor":"cd.15","new_text":"x","range_checksum":"10-15:a1b2"}}]\n[{"replace_between":{"start_anchor":"ab.10","end_anchor":"cd.40","new_text":"x","boundary_mode":"inclusive"}}]\n[{"insert_after":{"anchor":"ab.20","text":"x"}}]'
+      'JSON array of canonical edits.\n[{"set_line":{"anchor":"ab.12","new_text":"x"}}]\n[{"replace_lines":{"start_anchor":"ab.10","end_anchor":"cd.15","new_text":"x","range_checksum":"10-15:a1b2"}}]\n[{"insert_after":{"anchor":"ab.20","text":"x"}}]\n[{"replace_between":{"start_anchor":"ab.10","end_anchor":"cd.40","new_text":"x","boundary_mode":"inclusive"}}]'
     ),
     dry_run: flexBool().describe("Preview changes without writing"),
     restore_indent: flexBool().describe("Auto-fix indentation to match anchor (default: false)"),
@@ -2467,11 +2920,10 @@ server.registerTool("edit_file", {
       throw new Error('edits: invalid JSON. Expected: [{"set_line":{"anchor":"xx.N","new_text":"..."}}]');
     }
     if (!Array.isArray(parsed) || !parsed.length) throw new Error("Edits: non-empty JSON array required");
-    const normalized = parsed.map(coerceEdit);
     return {
       content: [{
         type: "text",
-        text: editFile(p, normalized, {
+        text: editFile(p, parsed, {
           dryRun: dry_run,
           restoreIndent: restore_indent,
           baseRevision: base_revision,
@@ -2504,7 +2956,7 @@ server.registerTool("write_file", {
 });
 server.registerTool("grep_search", {
   title: "Search Files",
-  description: "Search file contents with ripgrep. Returns hash-annotated matches with checksums. Modes: content (default), files, count. Use checksums with set_line/replace_lines. Prefer over shell grep/rg.",
+  description: "Search file contents with ripgrep. Default: edit-ready blocks with hashes and checksums. Use output:'files' or 'count' for non-edit workflows. With graph DB: results ranked by importance.",
   inputSchema: z2.object({
     pattern: z2.string().describe("Search pattern (regex by default, literal if literal:true)"),
     path: z2.string().optional().describe("Search dir/file (default: cwd)"),
@@ -2565,7 +3017,7 @@ server.registerTool("grep_search", {
 });
 server.registerTool("outline", {
   title: "File Outline",
-  description: "AST-based structural outline: functions, classes, interfaces with line ranges. Use before reading large code files. Not for .md/.json/.yaml.",
+  description: "AST-based structural outline with hash anchors for direct edit_file usage. Supports code files (JS/TS/Python/Go/Rust/Java/C/C++/C#/Ruby/PHP/Kotlin/Swift/Bash) and markdown headings (.md/.mdx, fence-aware).",
   inputSchema: z2.object({
     path: z2.string().describe("Source file path")
   }),
@@ -2581,19 +3033,20 @@ server.registerTool("outline", {
 });
 server.registerTool("verify", {
   title: "Verify Checksums",
-  description: "Check whether held checksums and optional base_revision are still current, without rereading the file.",
+  description: "Verify held checksums without rereading the file.",
   inputSchema: z2.object({
     path: z2.string().describe("File path"),
-    checksums: z2.string().describe('JSON array of checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
+    checksums: z2.array(z2.string()).describe('Checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
     base_revision: z2.string().optional().describe("Optional prior revision to compare against latest state.")
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
 }, async (rawParams) => {
   const { path: p, checksums, base_revision } = coerceParams(rawParams);
   try {
-    const parsed = JSON.parse(checksums);
-    if (!Array.isArray(parsed)) throw new Error("checksums must be a JSON array of strings");
-    return { content: [{ type: "text", text: verifyChecksums(p, parsed, { baseRevision: base_revision }) }] };
+    if (!Array.isArray(checksums) || checksums.length === 0) {
+      throw new Error("checksums must be a non-empty array of strings");
+    }
+    return { content: [{ type: "text", text: verifyChecksums(p, checksums, { baseRevision: base_revision }) }] };
   } catch (e) {
     return { content: [{ type: "text", text: e.message }], isError: true };
   }
@@ -2667,7 +3120,7 @@ server.registerTool("changes", {
 });
 server.registerTool("bulk_replace", {
   title: "Bulk Replace",
-  description: "Search-and-replace across multiple files. Finds files by glob, applies ordered text replacements. Default format is compact (summary only); use format:'full' for capped diffs. Use dry_run:true to preview. For single-file rename, set glob to the filename.",
+  description: "Search-and-replace across multiple files with compact or full diff output.",
   inputSchema: z2.object({
     replacements: z2.union([z2.string(), replacementPairsSchema]).describe('JSON array of {old, new} pairs: [{"old":"foo","new":"bar"}]'),
     glob: z2.string().optional().describe('File glob (default: "**/*.{md,mjs,json,yml,ts,js}")'),