@jerryan/pi-hashline-edit 0.7.3 → 0.8.1

package/src/hashline.ts

@@ -1,1071 +1,699 @@
-/**
- * Hashline engine — hash-anchored line editing.
- *
- * Originally vendored & adapted from oh-my-pi (MIT, github.com/can1357/oh-my-pi).
- * Hash algorithm replaced with inline FNV-1a; lineIndex always incorporated.
- */
-
-import { throwIfAborted } from "./runtime";
-
-// --- Types ---
-
-export type Anchor = { line: number; hash: string; textHint?: string };
-export type HashlineEdit =
-  | { op: "replace"; pos: Anchor; end?: Anchor; lines: string[] }
-  | { op: "append"; pos?: Anchor; lines: string[] }
-  | { op: "prepend"; pos?: Anchor; lines: string[] }
-  | { op: "replace_text"; oldText: string; newText: string };
-
-interface HashMismatch {
-  line: number;
-  expected: string;
-  actual: string;
-}
-
-interface NoopEdit {
-  editIndex: number;
-  loc: string;
-  currentContent: string;
-}
-
-// --- Hash computation ---
-
-const HEX = "0123456789ABCDEF";
-const HASH_ALPHABET_RE = /^[0-9A-F]+$/;
-
-const DICT = Array.from({ length: 256 }, (_, i) => {
-  const h = i >>> 4;
-  const l = i & 0x0f;
-  return `${HEX[h]}${HEX[l]}`;
-});
-
-export const ANCHOR_SEP = "#";
-export const CONTENT_SEP = "│";
-
-// FNV-1a 32-bit constants
-const FNV_OFFSET = 0x811c9dc5;
-const FNV_PRIME = 0x01000193;
-
-/**
- * Patterns used to detect (and reject) hashline display prefixes inside edit
- * payloads. The runtime no longer strips them — the model must send literal
- * file content. Matching any of these triggers `[E_INVALID_PATCH]`.
- */
-const HASHLINE_PREFIX_RE = new RegExp(
-  `^\\s*(?:>>>|>>)?\\s*(?:\\d+\\s*${ANCHOR_SEP}\\s*|${ANCHOR_SEP}\\s*)?[0-9A-F]{2}${CONTENT_SEP}`);
-const HASHLINE_PREFIX_PLUS_RE = new RegExp(
-  `^\\+\\s*(?:\\d+\\s*${ANCHOR_SEP}\\s*|${ANCHOR_SEP}\\s*)?[0-9A-F]{2}${CONTENT_SEP}`);
-const DIFF_MINUS_RE = /^-\s*\d+\s{4}/;
-
-export function computeLineHash(idx: number, line: string): string {
-  line = line.replace(/\r/g, "").trimEnd();
-  // FNV-1a with lineIndex incorporated unconditionally
-  let hash = (FNV_OFFSET ^ idx) >>> 0;
-  for (let i = 0; i < line.length; i++) {
-    hash = Math.imul(hash ^ line.charCodeAt(i), FNV_PRIME);
-  }
-  return DICT[hash & 0xff];
-}
-
-/** Shared fuzzy-match Unicode replacement regexes (also used by edit-diff.ts). */
-export const FUZZY_SINGLE_QUOTES_RE = /[\u2018\u2019\u201A\u201B]/g;
-export const FUZZY_DOUBLE_QUOTES_RE = /[\u201C\u201D\u201E\u201F]/g;
-export const FUZZY_HYPHENS_RE = /[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g;
-export const FUZZY_UNICODE_SPACES_RE = /[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g;
-
-function normalizeFuzzyLine(text: string): string {
-  return text
-    .trimEnd()
-    .replace(FUZZY_SINGLE_QUOTES_RE, "'")
-    .replace(FUZZY_DOUBLE_QUOTES_RE, '"')
-    .replace(FUZZY_HYPHENS_RE, "-")
-    .replace(FUZZY_UNICODE_SPACES_RE, " ");
-}
-
-function isFuzzyEquivalentLine(expected: string, actual: string): boolean {
-  return normalizeFuzzyLine(expected) === normalizeFuzzyLine(actual);
-}
-
-// ─── Parsing ────────────────────────────────────────────────────────────
-
-function diagnoseLineRef(ref: string): string {
-  const trimmed = ref.trim();
-  const core = ref.replace(/^\s*[>+-]*\s*/, "").trim();
-
-  if (!core.length) {
-    return `[E_BAD_REF] Invalid line reference "${ref}". Expected "LINE${ANCHOR_SEP}HASH" (e.g. "5${ANCHOR_SEP}MQ").`;
-  }
-  if (/^\d+\s*$/.test(core)) {
-    return `[E_BAD_REF] Invalid line reference "${ref}": missing hash, use "LINE${ANCHOR_SEP}HASH" from read output (e.g. "5${ANCHOR_SEP}MQ").`;
-  }
-  if (new RegExp(`^\d+\s*[:${CONTENT_SEP}]`).test(core)) {
-    return `[E_BAD_REF] Invalid line reference "${ref}": wrong separator, use "LINE${ANCHOR_SEP}HASH" instead of "LINE:..." or "LINE${CONTENT_SEP}...".`;
-  }
-
-  const hashMatch = core.match(new RegExp(`^(\d+)\s*${ANCHOR_SEP}\s*([^\s${CONTENT_SEP}]+)(?:\s*${CONTENT_SEP}.*)?$`));
-  if (hashMatch) {
-    const line = Number.parseInt(hashMatch[1]!, 10);
-    const hash = hashMatch[2]!;
-    if (line < 1) {
-      return `[E_BAD_REF] Line number must be >= 1, got ${line} in "${ref}".`;
-    }
-    if (hash.length !== 2) {
-      return `[E_BAD_REF] Invalid line reference "${ref}": hash must be exactly 2 characters from 0-9 A-F.`;
-    }
-    if (!HASH_ALPHABET_RE.test(hash)) {
-      return `[E_BAD_REF] Invalid line reference "${ref}": hash uses invalid characters, hashes use alphabet 0-9 A-F only.`;
-    }
-  }
-
-  const missingHashMatch = core.match(new RegExp(`^(\d+)\s*${ANCHOR_SEP}\s*$`));
-  if (missingHashMatch) {
-    return `[E_BAD_REF] Invalid line reference "${ref}": missing hash after "${ANCHOR_SEP}", use "LINE${ANCHOR_SEP}HASH" from read output.`;
-  }
-
-  if (new RegExp(`^0+\s*${ANCHOR_SEP}`).test(core)) {
-    return `[E_BAD_REF] Line number must be >= 1, got 0 in "${ref}".`;
-  }
-
-  return `[E_BAD_REF] Invalid line reference "${trimmed || ref}". Expected "LINE${ANCHOR_SEP}HASH" (e.g. "5${ANCHOR_SEP}MQ").`;
-}
-
-export function parseLineRef(ref: string): { line: number; hash: string } {
-  // Match LINE#HASH format, tolerating:
-  //  - leading ">+" and whitespace (from mismatch/diff display)
-  //  - optional trailing display suffix (":..." content)
-  const parsed = parseAnchorRef(ref);
-  return { line: parsed.line, hash: parsed.hash };
-}
-
-function parseAnchorRef(ref: string): Anchor {
-  const core = ref.replace(/^\s*[>+-]*\s*/, "").trimEnd();
-  const match = core.match(new RegExp(`^([0-9]+)\s*${ANCHOR_SEP}\s*([^\s${CONTENT_SEP}]+)(?:\s*${CONTENT_SEP}(.*))?$`, 's'));
-  if (!match) {
-    throw new Error(diagnoseLineRef(ref));
-  }
-
-  const line = Number.parseInt(match[1]!, 10);
-  if (line < 1) {
-    throw new Error(`[E_BAD_REF] Line number must be >= 1, got ${line} in "${ref}".`);
-  }
-
-  const hash = match[2]!;
-  if (hash.length !== 2) {
-    throw new Error(`[E_BAD_REF] Invalid line reference "${ref}": hash must be exactly 2 characters from 0-9 A-F.`);
-  }
-
-  if (!HASH_ALPHABET_RE.test(hash)) {
-    throw new Error(
-      `[E_BAD_REF] Invalid line reference "${ref}": hash uses invalid characters, hashes use alphabet 0-9 A-F only.`,
-    );
-  }
-
-  const textHint = match[3];
-  return {
-    line,
-    hash,
-    ...(textHint !== undefined ? { textHint } : {}),
-  };
-}
-
-// ─── Mismatch formatting ────────────────────────────────────────────────
-
-function formatMismatchError(
-  mismatches: HashMismatch[],
-  fileLines: string[],
-  retryLines: ReadonlySet<number> = new Set<number>(),
-): string {
-  const retryLineSet = new Set<number>(retryLines);
-  for (const m of mismatches) {
-    retryLineSet.add(m.line);
-  }
-
-  // De-duplicate: same line + same expected hash = same anchor
-  const seenKeys = new Set<string>();
-  const uniqueMismatches = mismatches.filter((m) => {
-    const key = `${m.line}:${m.expected}`;
-    if (seenKeys.has(key)) return false;
-    seenKeys.add(key);
-    return true;
-  });
-
-  const displayLines = new Set<number>();
-  for (const m of uniqueMismatches) {
-    for (
-      let i = Math.max(1, m.line - 2);
-      i <= Math.min(fileLines.length, m.line + 2);
-      i++
-    ) {
-      displayLines.add(i);
-    }
-  }
-  for (const line of retryLineSet) {
-    displayLines.add(line);
-  }
-
-  const sorted = [...displayLines].sort((a, b) => a - b);
-  const maxDisplayLine = sorted[sorted.length - 1] ?? 1;
-  const lineNumberWidth = String(maxDisplayLine).length;
-  const anchorList = uniqueMismatches.map((m) => `${m.line}${ANCHOR_SEP}${m.expected}`).join(", ");
-  const out: string[] = [
-    `[E_STALE_ANCHOR] ${uniqueMismatches.length} stale anchor${uniqueMismatches.length > 1 ? "s" : ""}: ${anchorList}. Retry with the >>> LINE${ANCHOR_SEP}HASH lines below; keep both endpoints for range replaces.`,
-    "",
-  ];
-
-  let prev = -1;
-  for (const num of sorted) {
-    if (prev !== -1 && num > prev + 1) out.push("    ...");
-    prev = num;
-    const content = fileLines[num - 1];
-    const hash = computeLineHash(num, content);
-    const prefix = `${String(num).padStart(lineNumberWidth, " ")}${ANCHOR_SEP}${hash}`;
-    out.push(
-      retryLineSet.has(num)
-        ? `>>> ${prefix}${CONTENT_SEP}${content}`
-        : `    ${prefix}${CONTENT_SEP}${content}`,
-    );
-  }
-
-  return out.join("\n");
-}
-
-// ─── Content preprocessing ─────────────────────────────────────────────────────
-
-/**
- * Reject hashline display prefixes in edit payloads. Strict semantics: the
- * model must send literal file content for `lines`, not the rendered read /
- * diff form. Silent stripping is no longer performed — see AGENTS.md.
- */
-function assertNoDisplayPrefixes(lines: string[]): void {
-  for (const line of lines) {
-    if (!line.length) continue;
-    if (
-      HASHLINE_PREFIX_RE.test(line) ||
-      HASHLINE_PREFIX_PLUS_RE.test(line) ||
-      DIFF_MINUS_RE.test(line)
-    ) {
-      throw new Error(
-        `[E_INVALID_PATCH] "lines" must contain literal file content, not rendered "LINE${ANCHOR_SEP}HASH${CONTENT_SEP}" or diff "+/-" prefixes. Offending line: ${JSON.stringify(line)}`,
-      );
-    }
-  }
-}
-
-/**
- * Parse replacement text into lines.
- *
- * String input is normalized to LF and drops exactly one trailing newline,
- * matching read-preview style content. Array input is preserved verbatim so
- * explicitly provided blank lines remain intact. Display prefixes are
- * rejected by `assertNoDisplayPrefixes`, never silently stripped.
- */
-export function hashlineParseText(edit: string[] | string | null): string[] {
-  if (edit === null) return [];
-  const lines = typeof edit === "string"
-    ? (edit.endsWith("\n") ? edit.slice(0, -1) : edit).replaceAll("\r", "").split("\n")
-    : edit;
-  assertNoDisplayPrefixes(lines);
-  return lines;
-}
-
-/**
- * Map flat tool-schema edits into typed internal representations.
- *
- * Strict: provided anchors must parse successfully. Missing anchors are
- * fine for append (→ EOF) and prepend (→ BOF), but a malformed anchor
- * that was explicitly supplied is always an error.
- *
- * - replace + pos only → single-line replace
- * - replace + pos + end → range replace
- * - append + pos → append after that anchor
- * - prepend + pos → prepend before that anchor
- * - replace_text + oldText/newText → exact unique text replace
- * - no anchors → file-level append/prepend (only for those ops)
- *
- * Unknown or missing ops are rejected explicitly.
- */
-export function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
-  const result: HashlineEdit[] = [];
-  for (const edit of edits) {
-    const op = edit.op;
-    if (
-      op !== "replace" &&
-      op !== "append" &&
-      op !== "prepend" &&
-      op !== "replace_text"
-    ) {
-      throw new Error(
-        `[E_BAD_OP] Unknown edit op "${op}". Expected "replace", "append", "prepend", or "replace_text".`,
-      );
-    }
-
-    switch (op) {
-      case "replace": {
-        if (!edit.pos) {
-          throw new Error('[E_BAD_OP] Replace requires a "pos" anchor.');
-        }
-
-        result.push({
-          op: "replace",
-          pos: parseAnchorRef(edit.pos),
-          ...(edit.end ? { end: parseAnchorRef(edit.end) } : {}),
-          lines: hashlineParseText(edit.lines ?? null),
-        });
-        break;
-      }
-      case "append": {
-        if (edit.end !== undefined) {
-          throw new Error('[E_BAD_OP] Append does not support "end". Use "pos" or omit it for EOF.');
-        }
-
-        result.push({
-          op: "append",
-          ...(edit.pos ? { pos: parseAnchorRef(edit.pos) } : {}),
-          lines: hashlineParseText(edit.lines ?? null),
-        });
-        break;
-      }
-      case "prepend": {
-        if (edit.end !== undefined) {
-          throw new Error('[E_BAD_OP] Prepend does not support "end". Use "pos" or omit it for BOF.');
-        }
-
-        result.push({
-          op: "prepend",
-          ...(edit.pos ? { pos: parseAnchorRef(edit.pos) } : {}),
-          lines: hashlineParseText(edit.lines ?? null),
-        });
-        break;
-      }
-      case "replace_text": {
-        const oldText = normalizeExactText(edit.oldText);
-        const newText = normalizeExactText(edit.newText);
-        if (oldText === undefined || newText === undefined) {
-          throw new Error('[E_BAD_OP] replace_text requires string "oldText" and "newText" fields.');
-        }
-
-        result.push({
-          op: "replace_text",
-          oldText,
-          newText,
-        });
-        break;
-      }
-    }
-  }
-  return result;
-}
-
-// ─── Main edit engine ───────────────────────────────────────────────────
-
-/** Schema-level edit as received from the tool layer (pos/end are tag strings, lines may be string|null). */
-export type HashlineToolEdit = {
-  op: string;
-  pos?: string;
-  end?: string;
-  lines?: string[] | string | null;
-  oldText?: string;
-  newText?: string;
-};
-
-function normalizeExactText(text: string | undefined): string | undefined {
-  if (typeof text !== "string") {
-    return undefined;
-  }
-
-  return text.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
-}
-
-function maybeWarnSuspiciousUnicodeEscapePlaceholder(
-  edits: HashlineEdit[],
-  warnings: string[],
-): void {
-  for (const edit of edits) {
-    if (edit.op === "replace_text") {
-      continue;
-    }
-    if (edit.lines.some((line) => /\\uDDDD/i.test(line))) {
-      warnings.push(
-        "Detected literal \\uDDDD in edit content; no autocorrection applied. Verify whether this should be a real Unicode escape or plain text.",
-      );
-    }
-  }
-}
-
-type ResolvedEditSpan = {
-  kind: "replace" | "insert";
-  index: number;
-  label: string;
-  start: number;
-  end: number;
-  replacement: string;
-  boundary?: number;
-  insertMode?: "append-empty-origin" | "prepend-empty-origin";
-};
-
-type LineIndex = {
-  fileLines: string[];
-  lineStarts: number[];
-  hasTerminalNewline: boolean;
-};
-
-function buildLineIndex(content: string): LineIndex {
-  const fileLines = content.split("\n");
-  const lineStarts: number[] = [];
-  let offset = 0;
-
-  for (let index = 0; index < fileLines.length; index++) {
-    lineStarts.push(offset);
-    offset += fileLines[index]!.length;
-    if (index < fileLines.length - 1) {
-      offset += 1;
-    }
-  }
-
-  return {
-    fileLines,
-    lineStarts,
-    hasTerminalNewline: content.endsWith("\n"),
-  };
-}
-
-function previewText(text: string): string {
-  const compact = text.replaceAll("\n", "\\n");
-  return compact.length > 32 ? `${compact.slice(0, 29)}...` : compact;
-}
-
-function describeEdit(edit: HashlineEdit): string {
-  switch (edit.op) {
-    case "replace":
-      return edit.end
-        ? `replace ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}-${edit.end.line}${ANCHOR_SEP}${edit.end.hash}`
-        : `replace ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`;
-    case "append":
-      return edit.pos
-        ? `append after ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`
-        : "append at EOF";
-    case "prepend":
-      return edit.pos
-        ? `prepend before ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`
-        : "prepend at BOF";
-    case "replace_text":
-      return `replace_text \"${previewText(edit.oldText)}\"`;
-  }
-}
-
-function throwEditConflict(
-  left: { index: number; label: string },
-  right: { index: number; label: string },
-  reason: string,
-): never {
-  throw new Error(
-    `[E_EDIT_CONFLICT] Conflicting edits in a single request: edit ${left.index} (${left.label}) and edit ${right.index} (${right.label}) ${reason}. Merge them into one non-overlapping change or split the request.`,
-  );
-}
-
-function cloneHashlineEdit(edit: HashlineEdit): HashlineEdit {
-  switch (edit.op) {
-    case "replace":
-      return {
-        op: "replace",
-        pos: { ...edit.pos },
-        ...(edit.end ? { end: { ...edit.end } } : {}),
-        lines: [...edit.lines],
-      };
-    case "append":
-      return {
-        op: "append",
-        ...(edit.pos ? { pos: { ...edit.pos } } : {}),
-        lines: [...edit.lines],
-      };
-    case "prepend":
-      return {
-        op: "prepend",
-        ...(edit.pos ? { pos: { ...edit.pos } } : {}),
-        lines: [...edit.lines],
-      };
-    case "replace_text":
-      return {
-        op: "replace_text",
-        oldText: edit.oldText,
-        newText: edit.newText,
-      };
-  }
-}
-
-function computeInsertionBoundary(
-  edit: Extract<HashlineEdit, { op: "append" | "prepend" }>,
-  lineIndex: LineIndex,
-): number {
-  switch (edit.op) {
-    case "append": {
-      const fileLineCount = lineIndex.fileLines.length;
-      const eofBoundary = lineIndex.hasTerminalNewline && fileLineCount > 0
-        ? fileLineCount - 1
-        : fileLineCount;
-      return edit.pos
-        ? lineIndex.hasTerminalNewline && edit.pos.line === fileLineCount
-          ? eofBoundary
-          : edit.pos.line
-        : eofBoundary;
-    }
-    case "prepend":
-      return edit.pos ? edit.pos.line - 1 : 0;
-  }
-}
-
-function findExactUniqueTextMatch(
-  content: string,
-  oldText: string,
-): { start: number; end: number } {
-  if (oldText.length === 0) {
-    throw new Error("[E_BAD_OP] replace_text requires non-empty oldText.");
-  }
-
-  const matches: number[] = [];
-  let from = 0;
-  while (from <= content.length - oldText.length) {
-    const index = content.indexOf(oldText, from);
-    if (index === -1) {
-      break;
-    }
-    matches.push(index);
-    from = index + 1;
-  }
-
-  for (let index = 1; index < matches.length; index++) {
-    if (matches[index]! - matches[index - 1]! < oldText.length) {
-      throw new Error(
-        "[E_MULTI_MATCH] replace_text found overlapping exact matches; re-read and use hashline edits.",
-      );
-    }
-  }
-
-  if (matches.length === 0) {
-    throw new Error("[E_NO_MATCH] replace_text found no exact unique match in the current file.");
-  }
-
-  if (matches.length > 1) {
-    throw new Error(
-      "[E_MULTI_MATCH] replace_text found multiple exact matches in the current file. Re-read and use hashline edits.",
-    );
-  }
-
-  const start = matches[0]!;
-  return {
-    start,
-    end: start + oldText.length,
-  };
-}
-
-function resolveEditToSpan(
-  edit: HashlineEdit,
-  index: number,
-  content: string,
-  lineIndex: LineIndex,
-  noopEdits: NoopEdit[],
-): ResolvedEditSpan | null {
-  const { fileLines, lineStarts, hasTerminalNewline } = lineIndex;
-
-  switch (edit.op) {
-    case "replace": {
-      const startLine = edit.pos.line;
-      const endLine = edit.end?.line ?? edit.pos.line;
-      const originalLines = fileLines.slice(startLine - 1, endLine);
-      if (
-        originalLines.length === edit.lines.length &&
-        originalLines.every((line, lineIndex) => line === edit.lines[lineIndex])
-      ) {
-        noopEdits.push({
-          editIndex: index,
-          loc: `${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`,
-          currentContent: originalLines.join("\n"),
-        });
-        return null;
-      }
-
-      if (edit.lines.length > 0) {
-        return {
-          kind: "replace",
-          index,
-          label: describeEdit(edit),
-          start: lineStarts[startLine - 1]!,
-          end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
-          replacement: edit.lines.join("\n"),
-        };
-      }
-
-      if (startLine === 1 && endLine === fileLines.length) {
-        return {
-          kind: "replace",
-          index,
-          label: describeEdit(edit),
-          start: 0,
-          end: content.length,
-          replacement: "",
-        };
-      }
-
-      if (endLine < fileLines.length) {
-        return {
-          kind: "replace",
-          index,
-          label: describeEdit(edit),
-          start: lineStarts[startLine - 1]!,
-          end: lineStarts[endLine]!,
-          replacement: "",
-        };
-      }
-
-      return {
-        kind: "replace",
-        index,
-        label: describeEdit(edit),
-        start: Math.max(0, lineStarts[startLine - 1]! - 1),
-        end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
-        replacement: "",
-      };
-    }
-    case "append": {
-      if (edit.lines.length === 0) {
-        noopEdits.push({
-          editIndex: index,
-          loc: edit.pos ? `${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}` : "EOF",
-          currentContent: edit.pos ? fileLines[edit.pos.line - 1] ?? "" : "",
-        });
-        return null;
-      }
-
-      const insertedText = edit.lines.join("\n");
-      if (content.length === 0) {
-        return {
-          kind: "insert",
-          index,
-          label: describeEdit(edit),
-          start: 0,
-          end: 0,
-          replacement: insertedText,
-          boundary: computeInsertionBoundary(edit, lineIndex),
-          insertMode: "append-empty-origin",
-        };
-      }
-
-      if (!edit.pos) {
-        return {
-          kind: "insert",
-          index,
-          label: describeEdit(edit),
-          start: content.length,
-          end: content.length,
-          replacement: hasTerminalNewline ? `${insertedText}\n` : `\n${insertedText}`,
-          boundary: computeInsertionBoundary(edit, lineIndex),
-        };
-      }
-
-      const isSentinelAppend = hasTerminalNewline && edit.pos.line === fileLines.length;
-      return {
-        kind: "insert",
-        index,
-        label: describeEdit(edit),
-        start: isSentinelAppend
-          ? content.length
-          : lineStarts[edit.pos.line - 1]! + fileLines[edit.pos.line - 1]!.length,
-        end: isSentinelAppend
-          ? content.length
-          : lineStarts[edit.pos.line - 1]! + fileLines[edit.pos.line - 1]!.length,
-        replacement: isSentinelAppend ? `${insertedText}\n` : `\n${insertedText}`,
-        boundary: computeInsertionBoundary(edit, lineIndex),
-      };
-    }
-    case "prepend": {
-      if (edit.lines.length === 0) {
-        noopEdits.push({
-          editIndex: index,
-          loc: edit.pos ? `${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}` : "BOF",
-          currentContent: edit.pos ? fileLines[edit.pos.line - 1] ?? "" : "",
-        });
-        return null;
-      }
-
-      const insertedText = edit.lines.join("\n");
-      const start = edit.pos ? lineStarts[edit.pos.line - 1]! : 0;
-      return {
-        kind: "insert",
-        index,
-        label: describeEdit(edit),
-        start,
-        end: start,
-        replacement: content.length === 0 ? insertedText : `${insertedText}\n`,
-        boundary: computeInsertionBoundary(edit, lineIndex),
-        ...(content.length === 0 ? { insertMode: "prepend-empty-origin" as const } : {}),
-      };
-    }
-    case "replace_text": {
-      const match = findExactUniqueTextMatch(content, edit.oldText);
-      if (edit.oldText === edit.newText) {
-        noopEdits.push({
-          editIndex: index,
-          loc: `replace_text \"${previewText(edit.oldText)}\"`,
-          currentContent: edit.oldText,
-        });
-        return null;
-      }
-
-      return {
-        kind: "replace",
-        index,
-        label: describeEdit(edit),
-        start: match.start,
-        end: match.end,
-        replacement: edit.newText,
-      };
-    }
-  }
-}
-
-function assertNoConflictingSpans(spans: ResolvedEditSpan[]): void {
-  for (let leftIndex = 0; leftIndex < spans.length; leftIndex++) {
-    const left = spans[leftIndex]!;
-    for (let rightIndex = leftIndex + 1; rightIndex < spans.length; rightIndex++) {
-      const right = spans[rightIndex]!;
-
-      if (left.kind === "insert" && right.kind === "insert") {
-        if (left.boundary === right.boundary) {
-          throwEditConflict(left, right, "target the same insertion boundary");
-        }
-        continue;
-      }
-
-      if (left.kind === "replace" && right.kind === "replace") {
-        if (left.start < right.end && right.start < left.end) {
-          throwEditConflict(left, right, "overlap on the same original line range");
-        }
-        continue;
-      }
-
-      const replaceSpan = left.kind === "replace" ? left : right;
-      const insertSpan = left.kind === "insert" ? left : right;
-      if (insertSpan.start >= replaceSpan.start && insertSpan.start < replaceSpan.end) {
-        throwEditConflict(
-          left,
-          right,
-          "cannot be applied together because one inserts inside a replaced original range",
-        );
-      }
-    }
-  }
-}
-
-export function applyHashlineEdits(
-  content: string,
-  edits: HashlineEdit[],
-  signal?: AbortSignal,
-): {
-  content: string;
-  firstChangedLine: number | undefined;
-  lastChangedLine: number | undefined;
-  warnings?: string[];
-  noopEdits?: NoopEdit[];
-} {
-  throwIfAborted(signal);
-  if (!edits.length) return { content, firstChangedLine: undefined, lastChangedLine: undefined };
-
-  const workingEdits = edits.map(cloneHashlineEdit);
-  const lineIndex = buildLineIndex(content);
-  const noopEdits: NoopEdit[] = [];
-  const warnings: string[] = [];
-
-  const mismatches: HashMismatch[] = [];
-  const retryLines = new Set<number>();
-  const acceptedFuzzyRefs = new Set<string>();
-  function validate(ref: Anchor): boolean {
-    if (ref.line < 1 || ref.line > lineIndex.fileLines.length) {
-      throw new Error(`[E_RANGE_OOB] Line ${ref.line} does not exist (file has ${lineIndex.fileLines.length} lines)`);
-    }
-    const line = lineIndex.fileLines[ref.line - 1]!;
-    const actual = computeLineHash(ref.line, line);
-    if (actual === ref.hash) return true;
-    if (ref.textHint !== undefined) {
-      const hintedHash = computeLineHash(ref.line, ref.textHint);
-      if (hintedHash === ref.hash && isFuzzyEquivalentLine(ref.textHint, line)) {
-        const key = `${ref.line}:${ref.hash}:${ref.textHint}`;
-        if (!acceptedFuzzyRefs.has(key)) {
-          acceptedFuzzyRefs.add(key);
-          warnings.push(
-            `Accepted fuzzy anchor validation at line ${ref.line}: exact hash mismatched, but the copied line content still matched after whitespace/Unicode normalization.`,
-          );
-        }
-        return true;
-      }
-    }
-    mismatches.push({ line: ref.line, expected: ref.hash, actual });
-    retryLines.add(ref.line);
-    return false;
-  }
-
-  for (const edit of workingEdits) {
-    throwIfAborted(signal);
-    switch (edit.op) {
-      case "replace": {
-        if (edit.end) {
-          if (edit.pos.line > edit.end.line) {
-            throw new Error(
-              `[E_BAD_RANGE] Range start line ${edit.pos.line} must be <= end line ${edit.end.line}`,
-            );
-          }
-          const startOk = validate(edit.pos);
-          const endOk = validate(edit.end);
-          if (!startOk && endOk) {
-            retryLines.add(edit.end.line);
-          }
-          if (startOk && !endOk) {
-            retryLines.add(edit.pos.line);
-          }
-          if (!startOk || !endOk) continue;
-        } else if (!validate(edit.pos)) {
-          continue;
-        }
-        const startLine = edit.pos.line;
-        const endLine = edit.end?.line ?? edit.pos.line;
-
-        // Check both boundaries for duplication
-        const checkBoundary = (candidate: string | undefined, boundary: string | undefined, label: string) => {
-          if (!candidate || !boundary) return;
-          const c = candidate.trim();
-          const b = boundary.trim();
-          if (c && /[\p{L}\p{N}]/u.test(c) && c === b) {
-            warnings.push(
-              `Potential boundary duplication ${label} ${describeEdit(edit)}: the replacement ${label === "after" ? "ends" : "starts"} with a line that matches the ${label === "after" ? "next surviving" : "preceding"} line after trim.`,
-            );
-          }
-        };
-        checkBoundary(edit.lines.at(-1), lineIndex.fileLines[endLine], "after");
-        if (startLine > 1) checkBoundary(edit.lines[0], lineIndex.fileLines[startLine - 2], "before");
-        break;
-      }
-      case "append": {
-        if (edit.pos && !validate(edit.pos)) continue;
-        if (edit.lines.length === 0) {
-          throw new Error(
-            "[E_BAD_OP] Append with empty lines payload. Provide content to insert or remove the edit.",
-          );
-        }
-        break;
-      }
-      case "prepend": {
-        if (edit.pos && !validate(edit.pos)) continue;
-        if (edit.lines.length === 0) {
-          throw new Error(
-            "[E_BAD_OP] Prepend with empty lines payload. Provide content to insert or remove the edit.",
-          );
-        }
-        break;
-      }
-      case "replace_text":
-        break;
-    }
-  }
-  if (mismatches.length) {
-    throw new Error(formatMismatchError(mismatches, lineIndex.fileLines, retryLines));
-  }
-
-  maybeWarnSuspiciousUnicodeEscapePlaceholder(workingEdits, warnings);
-
-  const seenSpanKeys = new Set<string>();
-  const resolvedSpans: ResolvedEditSpan[] = [];
-  for (const [index, edit] of workingEdits.entries()) {
-    throwIfAborted(signal);
-    const span = resolveEditToSpan(edit, index, content, lineIndex, noopEdits);
-    if (!span) {
-      continue;
-    }
-
-    const spanKey = span.kind === "insert"
-      ? `insert:${span.boundary}:${span.replacement}`
-      : `replace:${span.start}:${span.end}:${span.replacement}`;
-    if (seenSpanKeys.has(spanKey)) {
-      continue;
-    }
-    seenSpanKeys.add(spanKey);
-    resolvedSpans.push(span);
-  }
-
-  assertNoConflictingSpans(resolvedSpans);
-
-  const orderedSpans = [...resolvedSpans].sort((left, right) => {
-    if (right.end !== left.end) {
-      return right.end - left.end;
-    }
-    if (left.kind !== right.kind) {
-      return left.kind === "replace" ? -1 : 1;
-    }
-    if (left.kind === "insert" && right.kind === "insert") {
-      return (right.boundary ?? -1) - (left.boundary ?? -1) || left.index - right.index;
-    }
-    return left.index - right.index;
-  });
-
-  let result = content;
-  for (const span of orderedSpans) {
-    throwIfAborted(signal);
-    const replacement = span.insertMode === "append-empty-origin"
-      ? result.length === 0
-        ? span.replacement
-        : `\n${span.replacement}`
-      : span.insertMode === "prepend-empty-origin"
-        ? result.length === 0
-          ? span.replacement
-          : `${span.replacement}\n`
-        : span.replacement;
-    result = result.slice(0, span.start) + replacement + result.slice(span.end);
-  }
-
-  const changedRange = computeChangedLineRange(content, result);
-  return {
-    content: result,
-    firstChangedLine: changedRange?.firstChangedLine,
-    lastChangedLine: changedRange?.lastChangedLine,
-    ...(warnings.length ? { warnings } : {}),
-    ...(noopEdits.length ? { noopEdits } : {}),
-  };
-}
-
-// ─── Affected-line computation (for returning anchors after edit) ───────
-
-const ANCHOR_CONTEXT_LINES = 2;
-const ANCHOR_MAX_OUTPUT_LINES = 12;
-
-/**
- * Compute the post-edit line range covering changed lines plus context.
- * Uses `firstChangedLine` and `lastChangedLine` from the edit result for
- * precise bounds. Returns null if the range (with context) exceeds the
- * output budget, signalling that the LLM should re-read instead.
- */
-export function computeAffectedLineRange(params: {
-  firstChangedLine: number | undefined;
-  lastChangedLine: number | undefined;
-  resultLineCount: number;
-  contextLines?: number;
-  maxOutputLines?: number;
-}): { start: number; end: number } | null {
-  const {
-    firstChangedLine,
-    lastChangedLine,
-    resultLineCount,
-    contextLines = ANCHOR_CONTEXT_LINES,
-    maxOutputLines = ANCHOR_MAX_OUTPUT_LINES,
-  } = params;
-
-  if (firstChangedLine === undefined || lastChangedLine === undefined) {
-    return null;
-  }
-
-  // Empty file after edit: no meaningful anchor block.
-  if (resultLineCount === 0) {
-    return null;
-  }
-
-  const start = Math.max(1, firstChangedLine - contextLines);
-  const end = Math.min(resultLineCount, lastChangedLine + contextLines);
-
-  // Guard against inverted range (can happen when context pushes end below start).
-  if (end < start) {
-    return null;
-  }
-
-  if (end - start + 1 > maxOutputLines) {
-    return null;
-  }
-
-  return { start, end };
-}
-
-export function formatHashlineRegion(
-  lines: string[],
-  startLine: number,
-): string {
-  const lineNumberWidth = String(
-    startLine + Math.max(0, lines.length - 1),
-  ).length;
-  return lines
-    .map((line, index) => {
-      const lineNumber = startLine + index;
-      const paddedLineNumber = String(lineNumber).padStart(lineNumberWidth, " ");
-      return `${paddedLineNumber}${ANCHOR_SEP}${computeLineHash(lineNumber, line)}${CONTENT_SEP}${line}`;
-    })
-    .join("\n");
-}
-
-// ─── Legacy edit line range computation ─────────────────────────────
-
-/**
- * Compute first/last changed line numbers for legacy (oldText/newText) edits.
- * Uses character-level diff to locate the changed span, then maps to line
- * numbers in the result document so downstream anchor chaining works.
- */
-function computeChangedLineRange(
-  original: string,
-  result: string,
-): { firstChangedLine: number; lastChangedLine: number } | null {
-  if (original === result) return null;
-
-  function countVisibleLines(text: string): number {
-    if (text.length === 0) {
-      return 0;
-    }
-    const lines = text.split("\n");
-    return text.endsWith("\n") ? lines.length - 1 : lines.length;
-  }
-
-  if (original.length === 0) {
-    return {
-      firstChangedLine: 1,
-      lastChangedLine: countVisibleLines(result),
-    };
-  }
-
-  if (result.startsWith(original) && original.endsWith("\n")) {
-    return {
-      firstChangedLine: countVisibleLines(original) + 1,
-      lastChangedLine: countVisibleLines(result),
-    };
-  }
-
-  let firstDiff = 0;
-  const minLen = Math.min(original.length, result.length);
-  while (firstDiff < minLen && original[firstDiff] === result[firstDiff]) {
-    firstDiff++;
-  }
-  if (firstDiff === minLen && original.length === result.length) return null;
-
-  let lastOrig = original.length - 1;
-  let lastRes = result.length - 1;
-  while (
-    lastOrig >= firstDiff &&
-    lastRes >= firstDiff &&
-    original[lastOrig] === result[lastRes]
-  ) {
-    lastOrig--;
-    lastRes--;
-  }
-
-  function indexToLine(charIdx: number, text: string): number {
-    let line = 1;
-    for (let i = 0; i < charIdx && i < text.length; i++) {
-      if (text[i] === "\n") line++;
-    }
-    return line;
-  }
-
-  const firstChangedLine = indexToLine(firstDiff + 1, result);
-  let lastChangedLine: number;
-  if (lastRes < firstDiff) {
-    lastChangedLine = result.length === 0 ? 1 : countVisibleLines(result);
-  } else if (firstDiff === 0 && original.length > 0 && result.endsWith(original)) {
-    lastChangedLine = firstChangedLine;
-  } else {
-    lastChangedLine = indexToLine(lastRes + 1, result);
-  }
-
-  return { firstChangedLine, lastChangedLine };
-}
+/**
+ * Hashline engine — hash-anchored line editing.
+ *
+ * Originally vendored & adapted from oh-my-pi (MIT, github.com/can1357/oh-my-pi).
+ * Hash algorithm: inline FNV-1a with surrounding-line context.
+ */
+
+import { throwIfAborted } from "./runtime";
+
+// --- Types ---
+
+export type Anchor = { line: number; hash: string; textHint?: string };
+export type HashlineEdit = {
+  op: "replace";
+  pos: Anchor;
+  end?: Anchor;
+  lines: string[];
+};
+
+interface HashMismatch {
+  line: number;
+  expected: string;
+  actual: string;
+}
+
+interface NoopEdit {
+  editIndex: number;
+  loc: string;
+  currentContent: string;
+}
+
+// --- Hash computation ---
+
+const HEX = "0123456789ABCDEF";
+const HASH_ALPHABET_RE = /^[0-9A-F]+$/;
+
+const DICT = Array.from({ length: 256 }, (_, i) => {
+  const h = i >>> 4;
+  const l = i & 0x0f;
+  return `${HEX[h]}${HEX[l]}`;
+});
+
+export const ANCHOR_SEP = "#";
+export const CONTENT_SEP = "│";
+
+// FNV-1a 32-bit constants
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+
+function normalizeLine(line: string): string {
+  return line.replace(/\r/g, "").trimEnd();
+}
+
+/**
+ * Compute a context hash for line at `index` (0-based) within `fileLines`.
+ * The hash incorporates the line itself plus its immediate neighbors
+ * (previous and next), so distant edits do not invalidate anchors.
+ * Missing neighbors (file boundaries) contribute an empty string.
+ */
+export function computeLineHash(fileLines: string[], index: number): string {
+  const prev = index > 0 ? normalizeLine(fileLines[index - 1]!) : "";
+  const curr = normalizeLine(fileLines[index]!);
+  const next = index < fileLines.length - 1 ? normalizeLine(fileLines[index + 1]!) : "";
+
+  let hash = FNV_OFFSET;
+  for (let i = 0; i < prev.length; i++) {
+    hash = Math.imul(hash ^ prev.charCodeAt(i), FNV_PRIME);
+  }
+  hash = Math.imul(hash ^ 0, FNV_PRIME); // \0 delimiter
+  for (let i = 0; i < curr.length; i++) {
+    hash = Math.imul(hash ^ curr.charCodeAt(i), FNV_PRIME);
+  }
+  hash = Math.imul(hash ^ 0, FNV_PRIME); // \0 delimiter
+  for (let i = 0; i < next.length; i++) {
+    hash = Math.imul(hash ^ next.charCodeAt(i), FNV_PRIME);
+  }
+  return DICT[hash & 0xff];
+}
+
+/**
+ * Patterns used to detect (and reject) hashline display prefixes inside edit
+ * payloads. The runtime no longer strips them — the model must send literal
+ * file content. Matching any of these triggers `[E_INVALID_PATCH]`.
+ */
+const HASHLINE_PREFIX_RE = new RegExp(
+  `^\\s*(?:>>>|>>)?\\s*(?:\\d+\\s*${ANCHOR_SEP}\\s*|${ANCHOR_SEP}\\s*)?[0-9A-F]{2}${CONTENT_SEP}`);
+const HASHLINE_PREFIX_PLUS_RE = new RegExp(
+  `^\\+\\s*(?:\\d+\\s*${ANCHOR_SEP}\\s*|${ANCHOR_SEP}\\s*)?[0-9A-F]{2}${CONTENT_SEP}`);
+const DIFF_MINUS_RE = /^-\s*\d+\s{4}/;
+
+// ─── Parsing ────────────────────────────────────────────────────────────
+
+function diagnoseLineRef(ref: string): string {
+  const trimmed = ref.trim();
+  const core = ref.replace(/^\s*[>+-]*\s*/, "").trim();
+
+  if (!core.length) {
+    return `[E_BAD_REF] Invalid line reference "${ref}". Expected "LINE${ANCHOR_SEP}HASH" (e.g. "5${ANCHOR_SEP}MQ").`;
+  }
+  if (/^\d+\s*$/.test(core)) {
+    return `[E_BAD_REF] Invalid line reference "${ref}": missing hash, use "LINE${ANCHOR_SEP}HASH" from read output (e.g. "5${ANCHOR_SEP}MQ").`;
+  }
+  if (new RegExp(`^\d+\s*[:${CONTENT_SEP}]`).test(core)) {
+    return `[E_BAD_REF] Invalid line reference "${ref}": wrong separator, use "LINE${ANCHOR_SEP}HASH" instead of "LINE:..." or "LINE${CONTENT_SEP}...".`;
+  }
+
+  const hashMatch = core.match(new RegExp(`^(\d+)\s*${ANCHOR_SEP}\s*([^\s${CONTENT_SEP}]+)(?:\s*${CONTENT_SEP}.*)?$`));
+  if (hashMatch) {
+    const line = Number.parseInt(hashMatch[1]!, 10);
+    const hash = hashMatch[2]!;
+    if (line < 1) {
+      return `[E_BAD_REF] Line number must be >= 1, got ${line} in "${ref}".`;
+    }
+    if (hash.length !== 2) {
+      return `[E_BAD_REF] Invalid line reference "${ref}": hash must be exactly 2 characters from 0-9 A-F.`;
+    }
+    if (!HASH_ALPHABET_RE.test(hash)) {
+      return `[E_BAD_REF] Invalid line reference "${ref}": hash uses invalid characters, hashes use alphabet 0-9 A-F only.`;
+    }
+  }
+
+  const missingHashMatch = core.match(new RegExp(`^(\d+)\s*${ANCHOR_SEP}\s*$`));
+  if (missingHashMatch) {
+    return `[E_BAD_REF] Invalid line reference "${ref}": missing hash after "${ANCHOR_SEP}", use "LINE${ANCHOR_SEP}HASH" from read output.`;
+  }
+
+  if (new RegExp(`^0+\s*${ANCHOR_SEP}`).test(core)) {
+    return `[E_BAD_REF] Line number must be >= 1, got 0 in "${ref}".`;
+  }
+
+  return `[E_BAD_REF] Invalid line reference "${trimmed || ref}". Expected "LINE${ANCHOR_SEP}HASH" (e.g. "5${ANCHOR_SEP}MQ").`;
+}
+
+export function parseLineRef(ref: string): { line: number; hash: string } {
+  // Match LINE#HASH format, tolerating:
+  //  - leading ">+" and whitespace (from mismatch/diff display)
+  //  - optional trailing display suffix (":..." content)
+  const parsed = parseAnchorRef(ref);
+  return { line: parsed.line, hash: parsed.hash };
+}
+
+function parseAnchorRef(ref: string): Anchor {
+  const core = ref.replace(/^\s*[>+-]*\s*/, "").trimEnd();
+  const match = core.match(new RegExp(`^([0-9]+)\\s*${ANCHOR_SEP}\\s*([^\\s${CONTENT_SEP}]+)(?:\\s*${CONTENT_SEP}(.*))?$`, "s"));
+  if (!match) {
+    throw new Error(diagnoseLineRef(ref));
+  }
+
+  const line = Number.parseInt(match[1]!, 10);
+  if (line < 1) {
+    throw new Error(`[E_BAD_REF] Line number must be >= 1, got ${line} in "${ref}".`);
+  }
+
+  const hash = match[2]!;
+  if (hash.length !== 2) {
+    throw new Error(`[E_BAD_REF] Invalid line reference "${ref}": hash must be exactly 2 characters from 0-9 A-F.`);
+  }
+
+  if (!HASH_ALPHABET_RE.test(hash)) {
+    throw new Error(
+      `[E_BAD_REF] Invalid line reference "${ref}": hash uses invalid characters, hashes use alphabet 0-9 A-F only.`,
+    );
+  }
+
+  const textHint = match[3];
+  return {
+    line,
+    hash,
+    ...(textHint !== undefined ? { textHint } : {}),
+  };
+}
+
+// ─── Mismatch formatting ────────────────────────────────────────────────
+
+function formatMismatchError(
+  mismatches: HashMismatch[],
+  fileLines: string[],
+  retryLines: ReadonlySet<number> = new Set<number>(),
+): string {
+  const retryLineSet = new Set<number>(retryLines);
+  for (const m of mismatches) {
+    retryLineSet.add(m.line);
+  }
+
+  // De-duplicate: same line + same expected hash = same anchor
+  const seenKeys = new Set<string>();
+  const uniqueMismatches = mismatches.filter((m) => {
+    const key = `${m.line}:${m.expected}`;
+    if (seenKeys.has(key)) return false;
+    seenKeys.add(key);
+    return true;
+  });
+
+  const displayLines = new Set<number>();
+  for (const m of uniqueMismatches) {
+    for (
+      let i = Math.max(1, m.line - 2);
+      i <= Math.min(fileLines.length, m.line + 2);
+      i++
+    ) {
+      displayLines.add(i);
+    }
+  }
+  for (const line of retryLineSet) {
+    displayLines.add(line);
+  }
+
+  const sorted = [...displayLines].sort((a, b) => a - b);
+  const maxDisplayLine = sorted[sorted.length - 1] ?? 1;
+  const lineNumberWidth = String(maxDisplayLine).length;
+  const anchorList = uniqueMismatches.map((m) => `${m.line}${ANCHOR_SEP}${m.expected}`).join(", ");
+  const out: string[] = [
+    `[E_STALE_ANCHOR] ${uniqueMismatches.length} stale anchor${uniqueMismatches.length > 1 ? "s" : ""}: ${anchorList}. Retry with the >>> LINE${ANCHOR_SEP}HASH lines below; keep both endpoints for range replaces.`,
+    "",
+  ];
+
+  let prev = -1;
+  for (const num of sorted) {
+    if (prev !== -1 && num > prev + 1) out.push("    ...");
+    prev = num;
+    const content = fileLines[num - 1];
+    const hash = computeLineHash(fileLines, num - 1);
+    const prefix = `${String(num).padStart(lineNumberWidth, " ")}${ANCHOR_SEP}${hash}`;
+    out.push(
+      retryLineSet.has(num)
+        ? `>>> ${prefix}${CONTENT_SEP}${content}`
+        : `    ${prefix}${CONTENT_SEP}${content}`,
+    );
+  }
+
+  return out.join("\n");
+}
+
+// ─── Content preprocessing ─────────────────────────────────────────────────────
+
+/**
+ * Reject hashline display prefixes in edit payloads. Strict semantics: the
+ * model must send literal file content for `lines`, not the rendered read /
+ * diff form. Silent stripping is no longer performed — see AGENTS.md.
+ */
+function assertNoDisplayPrefixes(lines: string[]): void {
+  for (const line of lines) {
+    if (!line.length) continue;
+    if (
+      HASHLINE_PREFIX_RE.test(line) ||
+      HASHLINE_PREFIX_PLUS_RE.test(line) ||
+      DIFF_MINUS_RE.test(line)
+    ) {
+      throw new Error(
+        `[E_INVALID_PATCH] "lines" must contain literal file content, not rendered "LINE${ANCHOR_SEP}HASH${CONTENT_SEP}" or diff "+/-" prefixes. Offending line: ${JSON.stringify(line)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Parse replacement text into lines.
+ *
+ * String input is normalized to LF and drops exactly one trailing newline,
+ * matching read-preview style content. Array input is preserved verbatim so
+ * explicitly provided blank lines remain intact. Display prefixes are
+ * rejected by `assertNoDisplayPrefixes`, never silently stripped.
+ */
+export function hashlineParseText(edit: string[] | string | null): string[] {
+  if (edit === null) return [];
+  const lines = typeof edit === "string"
+    ? (edit.endsWith("\n") ? edit.slice(0, -1) : edit).replaceAll("\r", "").split("\n")
+    : edit;
+  assertNoDisplayPrefixes(lines);
+  return lines;
+}
+
+/**
+ * Map flat tool-schema edits into typed internal representations.
+ *
+ * Strict: provided anchors must parse successfully.
+ */
+export function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
+  return edits.map((edit) => ({
+    op: "replace",
+    pos: parseAnchorRef(edit.pos),
+    ...(edit.end ? { end: parseAnchorRef(edit.end) } : {}),
+    lines: hashlineParseText(edit.lines ?? null),
+  }));
+}
+
+// ─── Main edit engine ───────────────────────────────────────────────────
+
+/** Schema-level edit as received from the tool layer (pos/end are tag strings, lines may be string|null). */
+export type HashlineToolEdit = {
+  op: "replace";
+  pos: string;
+  end?: string;
+  lines?: string[] | string | null;
+};
+
+function maybeWarnSuspiciousUnicodeEscapePlaceholder(
+  edits: HashlineEdit[],
+  warnings: string[],
+): void {
+  for (const edit of edits) {
+    if (edit.lines.some((line) => /\\uDDDD/i.test(line))) {
+      warnings.push(
+        "Detected literal \\uDDDD in edit content; no autocorrection applied. Verify whether this should be a real Unicode escape or plain text.",
+      );
+    }
+  }
+}
+
+type ResolvedEditSpan = {
+  index: number;
+  label: string;
+  start: number;
+  end: number;
+  replacement: string;
+};
+
+type LineIndex = {
+  fileLines: string[];
+  lineStarts: number[];
+};
+
+function buildLineIndex(content: string): LineIndex {
+  const fileLines = content.split("\n");
+  const lineStarts: number[] = [];
+  let offset = 0;
+
+  for (let index = 0; index < fileLines.length; index++) {
+    lineStarts.push(offset);
+    offset += fileLines[index]!.length;
+    if (index < fileLines.length - 1) {
+      offset += 1;
+    }
+  }
+
+  return { fileLines, lineStarts };
+}
+
+function previewText(text: string): string {
+  const compact = text.replaceAll("\n", "\\n");
+  return compact.length > 32 ? `${compact.slice(0, 29)}...` : compact;
+}
+
+function describeEdit(edit: HashlineEdit): string {
+  return edit.end
+    ? `replace ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}-${edit.end.line}${ANCHOR_SEP}${edit.end.hash}`
+    : `replace ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`;
+}
+
+function throwEditConflict(
+  left: { index: number; label: string },
+  right: { index: number; label: string },
+  reason: string,
+): never {
+  throw new Error(
+    `[E_EDIT_CONFLICT] Conflicting edits in a single request: edit ${left.index} (${left.label}) and edit ${right.index} (${right.label}) ${reason}. Merge them into one non-overlapping change or split the request.`,
+  );
+}
+
+function cloneHashlineEdit(edit: HashlineEdit): HashlineEdit {
+  return {
+    op: "replace",
+    pos: { ...edit.pos },
+    ...(edit.end ? { end: { ...edit.end } } : {}),
+    lines: [...edit.lines],
+  };
+}
+
+function resolveEditToSpan(
+  edit: HashlineEdit,
+  index: number,
+  content: string,
+  lineIndex: LineIndex,
+  noopEdits: NoopEdit[],
+): ResolvedEditSpan | null {
+  const { fileLines, lineStarts } = lineIndex;
+
+  const startLine = edit.pos.line;
+  const endLine = edit.end?.line ?? edit.pos.line;
+  const originalLines = fileLines.slice(startLine - 1, endLine);
+  if (
+    originalLines.length === edit.lines.length &&
+    originalLines.every((line, lineIndex) => line === edit.lines[lineIndex])
+  ) {
+    noopEdits.push({
+      editIndex: index,
+      loc: `${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`,
+      currentContent: originalLines.join("\n"),
+    });
+    return null;
+  }
+
+  if (edit.lines.length > 0) {
+    return {
+      index,
+      label: describeEdit(edit),
+      start: lineStarts[startLine - 1]!,
+      end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
+      replacement: edit.lines.join("\n"),
+    };
+  }
+
+  if (startLine === 1 && endLine === fileLines.length) {
+    return {
+      index,
+      label: describeEdit(edit),
+      start: 0,
+      end: content.length,
+      replacement: "",
+    };
+  }
+
+  if (endLine < fileLines.length) {
+    return {
+      index,
+      label: describeEdit(edit),
+      start: lineStarts[startLine - 1]!,
+      end: lineStarts[endLine]!,
+      replacement: "",
+    };
+  }
+
+  return {
+    index,
+    label: describeEdit(edit),
+    start: Math.max(0, lineStarts[startLine - 1]! - 1),
+    end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
+    replacement: "",
+  };
+}
+
+function assertNoConflictingSpans(spans: ResolvedEditSpan[]): void {
+  for (let leftIndex = 0; leftIndex < spans.length; leftIndex++) {
+    const left = spans[leftIndex]!;
+    for (let rightIndex = leftIndex + 1; rightIndex < spans.length; rightIndex++) {
+      const right = spans[rightIndex]!;
+      if (left.start < right.end && right.start < left.end) {
+        throwEditConflict(left, right, "overlap on the same original line range");
+      }
+    }
+  }
+}
+
+export function applyHashlineEdits(
+  content: string,
+  edits: HashlineEdit[],
+  signal?: AbortSignal,
+): {
+  content: string;
+  firstChangedLine: number | undefined;
+  lastChangedLine: number | undefined;
+  warnings?: string[];
+  noopEdits?: NoopEdit[];
+} {
+  throwIfAborted(signal);
+  if (!edits.length) return { content, firstChangedLine: undefined, lastChangedLine: undefined };
+
+  const workingEdits = edits.map(cloneHashlineEdit);
+  const lineIndex = buildLineIndex(content);
+  const noopEdits: NoopEdit[] = [];
+  const warnings: string[] = [];
+
+  const mismatches: HashMismatch[] = [];
+  const retryLines = new Set<number>();
+  function validate(ref: Anchor): boolean {
+    if (ref.line < 1 || ref.line > lineIndex.fileLines.length) {
+      throw new Error(`[E_RANGE_OOB] Line ${ref.line} does not exist (file has ${lineIndex.fileLines.length} lines)`);
+    }
+    const actual = computeLineHash(lineIndex.fileLines, ref.line - 1);
+    if (actual === ref.hash) return true;
+    mismatches.push({ line: ref.line, expected: ref.hash, actual });
+    retryLines.add(ref.line);
+    return false;
+  }
+
+  for (const edit of workingEdits) {
+    throwIfAborted(signal);
+    if (edit.end) {
+      if (edit.pos.line > edit.end.line) {
+        throw new Error(
+          `[E_BAD_RANGE] Range start line ${edit.pos.line} must be <= end line ${edit.end.line}`,
+        );
+      }
+      const startOk = validate(edit.pos);
+      const endOk = validate(edit.end);
+      if (!startOk && endOk) {
+        retryLines.add(edit.end.line);
+      }
+      if (startOk && !endOk) {
+        retryLines.add(edit.pos.line);
+      }
+      if (!startOk || !endOk) continue;
+    } else if (!validate(edit.pos)) {
+      continue;
+    }
+    const startLine = edit.pos.line;
+    const endLine = edit.end?.line ?? edit.pos.line;
+
+    // Check both boundaries for duplication
+    const checkBoundary = (candidate: string | undefined, boundary: string | undefined, label: string) => {
+      if (!candidate || !boundary) return;
+      const c = candidate.trim();
+      const b = boundary.trim();
+      if (c && /[\p{L}\p{N}]/u.test(c) && c === b) {
+        warnings.push(
+          `Potential boundary duplication ${label} ${describeEdit(edit)}: the replacement ${label === "after" ? "ends" : "starts"} with a line that matches the ${label === "after" ? "next surviving" : "preceding"} line after trim.`,
+        );
+      }
+    };
+    checkBoundary(edit.lines.at(-1), lineIndex.fileLines[endLine], "after");
+    if (startLine > 1) checkBoundary(edit.lines[0], lineIndex.fileLines[startLine - 2], "before");
+  }
+  if (mismatches.length) {
+    throw new Error(formatMismatchError(mismatches, lineIndex.fileLines, retryLines));
+  }
+
+  maybeWarnSuspiciousUnicodeEscapePlaceholder(workingEdits, warnings);
+
+  const seenSpanKeys = new Set<string>();
+  const resolvedSpans: ResolvedEditSpan[] = [];
+  for (const [index, edit] of workingEdits.entries()) {
+    throwIfAborted(signal);
+    const span = resolveEditToSpan(edit, index, content, lineIndex, noopEdits);
+    if (!span) {
+      continue;
+    }
+
+    const spanKey = `replace:${span.start}:${span.end}:${span.replacement}`;
+    if (seenSpanKeys.has(spanKey)) {
+      continue;
+    }
+    seenSpanKeys.add(spanKey);
+    resolvedSpans.push(span);
+  }
+
+  assertNoConflictingSpans(resolvedSpans);
+
+  const orderedSpans = [...resolvedSpans].sort((left, right) => {
+    if (right.end !== left.end) {
+      return right.end - left.end;
+    }
+    return left.index - right.index;
+  });
+
+  let result = content;
+  for (const span of orderedSpans) {
+    throwIfAborted(signal);
+    result = result.slice(0, span.start) + span.replacement + result.slice(span.end);
+  }
+
+  const changedRange = computeChangedLineRange(content, result);
+  return {
+    content: result,
+    firstChangedLine: changedRange?.firstChangedLine,
+    lastChangedLine: changedRange?.lastChangedLine,
+    ...(warnings.length ? { warnings } : {}),
+    ...(noopEdits.length ? { noopEdits } : {}),
+  };
+}
+
+// ─── Affected-line computation (for returning anchors after edit) ───────
+
+const ANCHOR_CONTEXT_LINES = 2;
+const ANCHOR_MAX_OUTPUT_LINES = 12;
+
+/**
+ * Compute the post-edit line range covering changed lines plus context.
+ * Uses `firstChangedLine` and `lastChangedLine` from the edit result for
+ * precise bounds. Returns null if the range (with context) exceeds the
+ * output budget, signalling that the LLM should re-read instead.
+ */
+export function computeAffectedLineRange(params: {
+  firstChangedLine: number | undefined;
+  lastChangedLine: number | undefined;
+  resultLineCount: number;
+  contextLines?: number;
+  maxOutputLines?: number;
+}): { start: number; end: number } | null {
+  const {
+    firstChangedLine,
+    lastChangedLine,
+    resultLineCount,
+    contextLines = ANCHOR_CONTEXT_LINES,
+    maxOutputLines = ANCHOR_MAX_OUTPUT_LINES,
+  } = params;
+
+  if (firstChangedLine === undefined || lastChangedLine === undefined) {
+    return null;
+  }
+
+  // Empty file after edit: no meaningful anchor block.
+  if (resultLineCount === 0) {
+    return null;
+  }
+
+  const start = Math.max(1, firstChangedLine - contextLines);
+  const end = Math.min(resultLineCount, lastChangedLine + contextLines);
+
+  // Guard against inverted range (can happen when context pushes end below start).
+  if (end < start) {
+    return null;
+  }
+
+  if (end - start + 1 > maxOutputLines) {
+    return null;
+  }
+
+  return { start, end };
+}
+
+export function formatHashlineRegion(
+  fileLines: string[],
+  startLine: number,
+  endLine: number,
+): string {
+  const lineNumberWidth = String(endLine).length;
+  return fileLines
+    .slice(startLine - 1, endLine)
+    .map((line, index) => {
+      const lineNumber = startLine + index;
+      const paddedLineNumber = String(lineNumber).padStart(lineNumberWidth, " ");
+      return `${paddedLineNumber}${ANCHOR_SEP}${computeLineHash(fileLines, startLine - 1 + index)}${CONTENT_SEP}${line}`;
+    })
+    .join("\n");
+}
+
+// ─── Edit line range computation ────────────────────────────────────────
+
+/**
+ * Compute first/last changed line numbers from the edit result.
+ * Uses character-level diff to locate the changed span, then maps to line
+ * numbers in the result document so downstream anchor chaining works.
+ */
+function computeChangedLineRange(
+  original: string,
+  result: string,
+): { firstChangedLine: number; lastChangedLine: number } | null {
+  if (original === result) return null;
+
+  function countVisibleLines(text: string): number {
+    if (text.length === 0) {
+      return 0;
+    }
+    const lines = text.split("\n");
+    return text.endsWith("\n") ? lines.length - 1 : lines.length;
+  }
+
+  if (original.length === 0) {
+    return {
+      firstChangedLine: 1,
+      lastChangedLine: countVisibleLines(result),
+    };
+  }
+
+  if (result.startsWith(original) && original.endsWith("\n")) {
+    return {
+      firstChangedLine: countVisibleLines(original) + 1,
+      lastChangedLine: countVisibleLines(result),
+    };
+  }
+
+  let firstDiff = 0;
+  const minLen = Math.min(original.length, result.length);
+  while (firstDiff < minLen && original[firstDiff] === result[firstDiff]) {
+    firstDiff++;
+  }
+  if (firstDiff === minLen && original.length === result.length) return null;
+
+  let lastOrig = original.length - 1;
+  let lastRes = result.length - 1;
+  while (
+    lastOrig >= firstDiff &&
+    lastRes >= firstDiff &&
+    original[lastOrig] === result[lastRes]
+  ) {
+    lastOrig--;
+    lastRes--;
+  }
+
+  function indexToLine(charIdx: number, text: string): number {
+    let line = 1;
+    for (let i = 0; i < charIdx && i < text.length; i++) {
+      if (text[i] === "\n") line++;
+    }
+    return line;
+  }
+
+  const firstChangedLine = indexToLine(firstDiff + 1, result);
+  let lastChangedLine: number;
+  if (lastRes < firstDiff) {
+    lastChangedLine = result.length === 0 ? 1 : countVisibleLines(result);
+  } else if (firstDiff === 0 && original.length > 0 && result.endsWith(original)) {
+    lastChangedLine = firstChangedLine;
+  } else {
+    lastChangedLine = indexToLine(lastRes + 1, result);
+  }
+
+  return { firstChangedLine, lastChangedLine };
+}