pi-hashline-edit-pro 4.2.3 → 4.2.4

package/README.md

@@ -97,7 +97,9 @@ An edit that produces identical content reports `No changes made` and leaves the
 
 After a successful edit, the diff is capped at 50KB. A row over 50KB is shown as a marker that keeps the row's anchor, and only the rows shown in the capped diff are recorded as served. The same caps apply to the `insert` and `undo_last_change` diffs, to the interactive previews, and to `details.patch`.
 
-Multiple `replace` and `insert` calls on the same file in one message are grouped per file into one batch that validates every call against the pre-batch state and then applies them together on the batch's last call: earlier calls reply `In batch` (`In batch N` when several files batch) and the batch's last call shows the combined diff, with one undo reverting the whole batch. Batched calls must target disjoint ranges; overlapping ranges, or any failing call, aborts the whole batch. Calls with stale anchors join their file's batch through a `requirePath` path hint or a valid co-anchor and abort it instead of applying partially; a same-turn sibling whose anchors resolve nowhere still aborts the batch when no other file is being edited. An error that aborts a batch ends with `Aborts batch N.`, while the abort itself reads `[E_OP_ABORTED] Batch N aborted.` Anchor capacity is preflighted before writing; if anchor finalization fails after the write, the error states the file was written with one undo available. Verify each batch diff before the next turn's edits on that file.
+Multiple `replace` and `insert` calls on the same file in one assistant message are grouped per file into one batch. The batch unit is the message, not the turn: calls from separate messages in the same turn run solo, one after another. A solo edit commits before its result returns; a batch validates every call against the pre-batch state and commits once, during the batch's last call: earlier calls reply `In batch` (`In batch N` when several files batch) and the batch's last call shows the combined diff, with one undo reverting the whole batch. Nothing commits at turn end.
+Tools in one message run concurrently, so a `read` or shell `cat` issued alongside an edit can observe the pre-commit state; verify in the next message with the post-edit diff or a fresh `read`.
+Batched calls must target disjoint ranges; overlapping ranges, or any failing call, aborts the whole batch unwritten. A resolvable failure aborts its batch-mates, while an anchor that resolves nowhere cannot join a batch: same-message [resolvable-fail + resolvable-valid] on one file fails fast with `[E_OP_ABORTED]`, but the same pair split across messages runs as two solos (fail, then apply). Calls with stale anchors join their file's batch through a `requirePath` path hint or a valid co-anchor and abort it instead of applying partially; a same-message sibling whose anchors resolve nowhere still aborts the batch when no other file is being edited. An error that aborts a batch ends with `Aborts batch N.`, while the abort itself reads `[E_OP_ABORTED] Batch N aborted.` Anchor capacity is preflighted before writing; if anchor finalization fails after the write, the error states the file was written with one undo available. Verify each batch diff before the next turn's edits on that file.
 
 ### insert
 
@@ -139,7 +141,7 @@ Output is capped at `limit` matched lines, 2000 rows, and 50KB of text, whicheve
 
 `undo_last_change` reverts the most recent successful `replace` or `insert` on a file, restoring the exact previous content, BOM and line endings included, plus the previous anchors.
 
-- History is per-file and single-level: only the most recent `replace` or `insert` can be reverted. A same-turn batch of `replace`/`insert` calls on one file counts as one entry: one undo reverts the whole batch.
+- History is per-file and single-level: only the most recent `replace` or `insert` can be reverted. A same-message batch of `replace`/`insert` calls on one file counts as one entry: one undo reverts the whole batch.
 - History is persisted and survives session restarts. A failed `write` does not clear it.
 - Every applied `replace` or `insert` is undoable; the undo record is saved before the edit is written.
 - A successful `write` clears the history for that file.
@@ -151,7 +153,7 @@ Output is capped at `limit` matched lines, 2000 rows, and 50KB of text, whicheve
 
 Auto-read is enabled by default. After a successful `write`, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block, so you get fresh `anchor│content` anchors without a separate `read` call.
 
-After `replace`, `insert`, and `undo_last_change`, the result shows the post-edit diff. Inside a same-turn batch, only the batch's last call shows the combined diff, headed by a `batch:` line (`batch N:` when several files batch); earlier calls reply `In batch` (`In batch N` when several files batch). The `+anchor│` and ` anchor│` rows carry the current anchors, so follow-up edits can anchor on the diff directly. The `-anchor│` rows show removed lines with their old anchors, which are stale after the edit. When the context line next to a change is blank or whitespace-only, one more context line is shown in that direction, so the change stays anchored to visible content. Call `read` when you want the full file's anchors.
+After `replace`, `insert`, and `undo_last_change`, the result shows the post-edit diff. Inside a same-message batch, only the batch's last call shows the combined diff, headed by a `batch:` line (`batch N:` when several files batch); earlier calls reply `In batch` (`In batch N` when several files batch). The `+anchor│` and ` anchor│` rows carry the current anchors, so follow-up edits can anchor on the diff directly. The `-anchor│` rows show removed lines with their old anchors, which are stale after the edit. When the context line next to a change is blank or whitespace-only, one more context line is shown in that direction, so the change stays anchored to visible content. Call `read` when you want the full file's anchors.
 
 Auto-read keeps the same 50KB and 2000-line budget as `read`. Change it in `/hashline-config`; both settings persist across sessions. The post-edit diff shows 1 surrounding line by default; change Diff context in `/hashline-config` (0-10, needs Auto-read) to show more or fewer.
 
@@ -211,7 +213,7 @@ On POSIX systems, the state directory is restricted to mode `0700` and the SQLit
 
 ## Error and warning codes
 
-Codes starting with `E_` are errors (the operation failed); codes starting with `W_` are warnings (the operation succeeded with a notice).
+Codes starting with `E_` are errors: nothing was written — except `File was written; anchor finalization failed`, which means the file was written and one undo reverts it. Codes starting with `W_` are warnings: the call succeeded with an auto-fix notice; check `classification` (`applied` vs `noop`) in `details.metrics` to tell whether bytes changed.
 
 | Code | Meaning |
 | --- | --- |
@@ -237,7 +239,7 @@ Codes starting with `E_` are errors (the operation failed); codes starting with
 | `[E_WRITE_HASH_ECHO]` | A `write` `content` line begins with the exact `anchor│` served for this file at the same line. The write is refused, file byte-identical; retry with bare content (remove the copied anchors). |
 | `[E_PATH_CHANGED]` | A write target changed identity after it was read; the write was refused to avoid following a swapped symlink or overwriting a replacement file. |
 | `[E_BATCH_OVERLAP]` | Batched `replace`/`insert` calls target overlapping ranges; the whole batch was refused. Retry with disjoint ranges. |
-| `[E_OP_ABORTED]` | An edit aborted (a same-turn batch member failed, or the file changed or was deleted after the edit started). Fix the sibling failure and retry the batch, otherwise call `read` for fresh anchors and retry. |
+| `[E_OP_ABORTED]` | An edit aborted (a same-message batch member failed, or the file changed or was deleted after the edit started). Nothing was written. Fix the sibling failure and retry the batch, otherwise call `read` for fresh anchors and retry. |
 | `[E_UNSAFE_REGEX]` | A grep regex can trigger excessive backtracking; simplify it or search with `literal: true`. |
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "4.2.3",
+  "version": "4.2.4",
   "type": "module",
   "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 4-char tokenizer-friendly anchor that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",

package/src/anchor-registry.ts

@@ -1,7 +1,7 @@
-import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "fs/promises";
-import { appendFileSync, chmodSync } from "fs";
-import { join } from "path";
-import { createHash } from "crypto";
+import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { appendFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
 import { sessionClaimsDir } from "./paths";
 import { contentChecksum } from "./hashline/hasher";
 import { ANCHOR_COUNT, anchorAt } from "./hashline/alphabet";

package/src/batch.ts

@@ -1,6 +1,6 @@
-import { readFile } from "fs/promises";
-import { constants } from "fs";
-import { relative } from "path";
+import { readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { relative } from "node:path";
 import { readConfig, getDiffContextLines } from "./config";
 import { resolveEditTarget, throwIfStrictInput, tryResolveEditTarget } from "./edit-common";
 import { readNormFile, safeSnapId } from "./file-reader";
@@ -656,6 +656,7 @@ async function finishBatch(member: PlannedMember, signal?: AbortSignal): Promise
       },
       boundaryDedupAbove: [],
       boundaryDedupBelow: [],
+      spans,
     },
     batchVerb(runtime),
     await getDiffContextLines(),

package/src/commit.ts

@@ -1,4 +1,4 @@
-import { readFile } from "fs/promises";
+import { readFile } from "node:fs/promises";
 import type { PipelineResult } from "./replace";
 import { abortIf, errCode, splitLines } from "./utils";
 import { DEDUP_ANCHOR } from "./constants";
@@ -149,6 +149,7 @@ export async function commitEdit(pipe: PipelineResult, meta: CommitMeta): Promis
     editMeta,
     boundaryDedupAbove: pipe.boundaryDedupAbove,
     boundaryDedupBelow: pipe.boundaryDedupBelow,
+    ...(span ? { spans: [{ start: span[0], end: span[1], replacementCount }] } : {}),
   };
   const changed = buildChanged(successInput, meta.verb, await getDiffContextLines());
   if (changed.details.diff) {

package/src/config.ts

@@ -1,5 +1,5 @@
-import { mkdir, readFile, rename, rm, stat } from "fs/promises";
-import { dirname } from "path";
+import { mkdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { dirname } from "node:path";
 import { configPath } from "./paths";
 import { errCode, isRec } from "./utils";
 import { writeAtomic } from "./fs-write";

package/src/file-kind.ts

@@ -1,4 +1,4 @@
-import { open as fsOpen, stat as fsStat } from "fs/promises";
+import { open as fsOpen, stat as fsStat } from "node:fs/promises";
 import { fileTypeFromBuffer } from "file-type";
 import { SNIFF_BYTES, MAX_BYTES } from "./constants";
 import { assertLineLimit, lineLimitMoreThanMessage } from "./utils";

package/src/file-reader.ts

@@ -1,6 +1,6 @@
-import { constants } from "fs";
-import { stat } from "fs/promises";
-import { relative } from "path";
+import { constants } from "node:fs";
+import { stat } from "node:fs/promises";
+import { relative } from "node:path";
 import { lineHashes } from "./hashline";
 import { loadFileKindAndText, type LFile } from "./file-kind";
 import { resolveTarget, type FileIdentity } from "./fs-write";

package/src/fs-write.ts

@@ -1,5 +1,5 @@
-import { randomUUID } from "crypto";
-import { constants } from "fs";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
 import {
 	lstat,
 	mkdir,
@@ -10,8 +10,8 @@ import {
 	rm,
 	stat,
 	writeFile,
-} from "fs/promises";
-import { dirname, join, parse, resolve, sep } from "path";
+} from "node:fs/promises";
+import { dirname, join, parse, resolve, sep } from "node:path";
 import { toCwd } from "./paths";
 import { errCode } from "./utils";
 

package/src/grep.ts

@@ -1,10 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatSize, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { stat } from "fs/promises";
-import { dirname, isAbsolute, join, relative, win32 } from "path";
-import { spawn, spawnSync } from "child_process";
-import { createInterface } from "readline";
+import { stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, win32 } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
 import { tryReadNormFile } from "./file-reader";
 import { MAX_HASH_LINES, fmtRow, HASH_LEN, HASH_SEP } from "./hashline";
 import { ANCHOR_POOL_EXHAUSTED_PREFIX, MAX_GREP_LINE_BYTES } from "./constants";
@@ -292,8 +292,8 @@ async function resolveRgPath(): Promise<string> {
     if (!r.error && r.status === 0) { cachedRgPath = "rg"; return "rg"; }
   } catch {}
   try {
-    const { homedir } = await import("os");
-    const { existsSync } = await import("fs");
+    const { homedir } = await import("node:os");
+    const { existsSync } = await import("node:fs");
     const home = process.env.HOME ?? homedir();
     const base = process.env.PI_CODING_AGENT_DIR ?? join(home, ".pi", "agent");
     const bin = join(base, "bin", process.platform === "win32" ? "rg.exe" : "rg");
@@ -303,10 +303,10 @@ async function resolveRgPath(): Promise<string> {
     }
   } catch {}
   try {
-    const { createRequire } = await import("module");
+    const { createRequire } = await import("node:module");
     const require = createRequire(import.meta.url);
     const pkgPath = require.resolve("@earendil-works/pi-coding-agent/package.json");
-    const { dirname } = await import("path");
+    const { dirname } = await import("node:path");
     const piDir = dirname(pkgPath);
     const toolsManagerPath = join(piDir, "dist/utils/tools-manager.js");
     const mod = await import("file://" + toolsManagerPath);

package/src/hash-store.ts

@@ -1,6 +1,6 @@
-import { randomUUID } from "crypto";
-import { existsSync } from "fs";
-import { chmod, readFile, rename, mkdir, stat } from "fs/promises";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { chmod, readFile, rename, mkdir, stat } from "node:fs/promises";
 import { hashStorePath, hashStoreDir, legacyHashStorePath } from "./paths";
 import { errCode, isRec, splitLines } from "./utils";
 import { initHasher, contentChecksum } from "./hashline/hasher";
@@ -39,48 +39,10 @@ interface RawDb {
   close(): void;
   readonly isOpen: boolean;
 }
-export type SqliteEngine = "node:sqlite" | "bun:sqlite";
-
-interface BunDbLike {
-  exec(sql: string): void;
-  prepare(sql: string): {
-    get(...params: SqlParams): unknown;
-    all(...params: SqlParams): unknown[];
-    run(...params: SqlParams): unknown;
-  };
-  close(): void;
-}
-
-let openDbFn: (path: string) => RawDb;
-let sqliteEngine: SqliteEngine;
-
-if (typeof process !== "undefined" && (process.versions as Record<string, string | undefined>).bun) {
-  const specifier = "bun:sqlite";
-  const mod = await import(specifier) as { Database: new (path: string) => BunDbLike };
-  sqliteEngine = "bun:sqlite";
-  openDbFn = (path) => {
-    const db = new mod.Database(path);
-    db.exec(`PRAGMA busy_timeout = ${HASH_STORE_BUSY_TIMEOUT}`);
-    let closed = false;
-    return {
-      exec: (sql) => db.exec(sql),
-      prepare: (sql) => {
-        const stmt = db.prepare(sql);
-        return {
-          get: (...p) => stmt.get(...p) ?? undefined,
-          all: (...p) => stmt.all(...p),
-          run: (...p) => stmt.run(...p),
-        };
-      },
-      close: () => { if (!closed) { closed = true; db.close(); } },
-      get isOpen() { return !closed; },
-    };
-  };
-} else {
-  const { DatabaseSync } = await import("node:sqlite");
-  sqliteEngine = "node:sqlite";
-  openDbFn = (path) => new DatabaseSync(path, { timeout: HASH_STORE_BUSY_TIMEOUT }) as unknown as RawDb;
-}
+export type SqliteEngine = "node:sqlite";
+const sqliteEngine: SqliteEngine = "node:sqlite";
+const { DatabaseSync } = await import("node:sqlite");
+const openDbFn = (path: string): RawDb => new DatabaseSync(path, { timeout: HASH_STORE_BUSY_TIMEOUT }) as unknown as RawDb;
 
 interface Prepared {
   get: (...params: SqlParams) => Record<string, unknown> | undefined;

package/src/insert.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { constants } from "fs";
+import { constants } from "node:fs";
 import { execPipeline, type ReqParams, type ReplaceDetails, previewFromPipe, previewError } from "./replace";
 import { commitEdit } from "./commit";
 import { batchMemberFor, ensureBatchBase, executeBatchMember, noteBatchFailure, suffixPoisonCause } from "./batch";

package/src/paths.ts

@@ -1,5 +1,5 @@
-import { homedir } from "os";
-import { isAbsolute, resolve as resolvePath, join, dirname } from "path";
+import { homedir } from "node:os";
+import { isAbsolute, resolve as resolvePath, join, dirname } from "node:path";
 
 
 function homeBase(): string {

package/src/prompts.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "fs";
+import { readFileSync } from "node:fs";
 
 export function loadP(relativePath: string): string {
   return readFileSync(new URL(relativePath, import.meta.url), "utf-8").trim();

package/src/replace-diff.ts

@@ -18,6 +18,19 @@ import {
 
 export { detectEnding, toLF, restoreEndings, stripBOM, type LineEnding };
 
+export interface DiffSpan {
+  start: number;
+  end: number;
+  replacementCount: number;
+}
+
+interface PlacedSpan {
+  oldStart: number;
+  oldEnd: number;
+  newStart: number;
+  newEnd: number;
+}
+
 function fmtDiffLine(
   prefix: " " | "+" | "-",
   line: string,
@@ -43,6 +56,282 @@ export interface DiffLimits {
   unlimited?: boolean;
 }
 
+export function spansFromHashes(oldHashes: string[], newHashes: string[]): DiffSpan[] {
+  const parts = Diff.diffArrays(oldHashes, newHashes) as unknown as Array<{ added?: boolean; removed?: boolean; count?: number; value?: string[] }>;
+  const spans: DiffSpan[] = [];
+  let oldIdx = 0;
+  let i = 0;
+  while (i < parts.length) {
+    const part = parts[i]!;
+    const isChange = part.added === true || part.removed === true;
+    if (!isChange) {
+      const count = part.count ?? part.value?.length ?? 0;
+      oldIdx += count;
+      i += 1;
+      continue;
+    }
+    const runStart = oldIdx;
+    let removedTotal = 0;
+    let addedTotal = 0;
+    while (i < parts.length) {
+      const runPart = parts[i]!;
+      const runChange = runPart.added === true || runPart.removed === true;
+      if (!runChange) break;
+      const count = runPart.count ?? runPart.value?.length ?? 0;
+      if (runPart.removed === true && runPart.added !== true) {
+        removedTotal += count;
+        oldIdx += count;
+      } else if (runPart.added === true && runPart.removed !== true) {
+        addedTotal += count;
+      } else {
+        removedTotal += count;
+        addedTotal += count;
+        oldIdx += count;
+      }
+      i += 1;
+    }
+    spans.push({
+      start: runStart,
+      end: runStart + removedTotal - 1,
+      replacementCount: addedTotal,
+    });
+  }
+  return spans;
+}
+
+const ANCHORED_DIFF_ROW_RE = /^([+ -])([A-Za-z0-9]{4})│/;
+
+export function disambiguateDuplicateAnchors(diff: string): string {
+  if (!diff.includes("│")) return diff;
+  const live = new Set<string>();
+  const lines = diff.split("\n");
+  for (const line of lines) {
+    const match = ANCHORED_DIFF_ROW_RE.exec(line);
+    if (!match) continue;
+    const prefix = match[1]!;
+    const anchor = match[2]!;
+    if (prefix === "+" || prefix === " ") live.add(anchor);
+  }
+  if (live.size === 0) return diff;
+  let changed = false;
+  const out = lines.map((line) => {
+    const match = ANCHORED_DIFF_ROW_RE.exec(line);
+    if (!match || match[1] !== "-") return line;
+    if (!live.has(match[2]!)) return line;
+    changed = true;
+    return `-    │${line.slice(match[0].length)}`;
+  });
+  return changed ? out.join("\n") : diff;
+}
+
+function placeSpans(
+  oldLen: number,
+  newLen: number,
+  spans: DiffSpan[],
+): PlacedSpan[] | undefined {
+  const sorted = [...spans].sort((a, b) => a.start - b.start || a.end - b.end);
+  for (const span of sorted) {
+    if (!Number.isInteger(span.start) || !Number.isInteger(span.end) || !Number.isInteger(span.replacementCount)) return undefined;
+    if (span.replacementCount < 0) return undefined;
+    if (span.start > span.end) {
+      if (span.end !== span.start - 1) return undefined;
+      if (span.start < 0 || span.start > oldLen) return undefined;
+    } else {
+      if (span.start < 0 || span.end >= oldLen) return undefined;
+    }
+  }
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i]!.start <= sorted[i - 1]!.end) return undefined;
+  }
+  const placed: PlacedSpan[] = [];
+  let offset = 0;
+  let removedSum = 0;
+  let addedSum = 0;
+  for (const span of sorted) {
+    const spanLen = Math.max(0, span.end - span.start + 1);
+    const newStart = span.start + offset;
+    const newEnd = newStart + span.replacementCount - 1;
+    if (newStart < 0 || newStart > newLen) return undefined;
+    if (span.replacementCount === 0) {
+      if (newEnd !== newStart - 1) return undefined;
+    } else if (newEnd >= newLen) return undefined;
+    placed.push({ oldStart: span.start, oldEnd: span.end, newStart, newEnd });
+    offset += span.replacementCount - spanLen;
+    removedSum += spanLen;
+    addedSum += span.replacementCount;
+  }
+  if (oldLen - removedSum + addedSum !== newLen) return undefined;
+  return placed;
+}
+
+function trimPlacedSpans(
+  placed: PlacedSpan[],
+  oldLines: string[],
+  newLines: string[],
+): PlacedSpan[] {
+  const out: PlacedSpan[] = [];
+  for (const span of placed) {
+    let oldStart = span.oldStart;
+    let oldEnd = span.oldEnd;
+    let newStart = span.newStart;
+    let newEnd = span.newEnd;
+    while (oldStart <= oldEnd && newStart <= newEnd && oldLines[oldStart] === newLines[newStart]) {
+      oldStart += 1;
+      newStart += 1;
+    }
+    while (oldStart <= oldEnd && newStart <= newEnd && oldLines[oldEnd] === newLines[newEnd]) {
+      oldEnd -= 1;
+      newEnd -= 1;
+    }
+    if (oldStart > oldEnd && newStart > newEnd) continue;
+    out.push({ oldStart, oldEnd, newStart, newEnd });
+  }
+  return out;
+}
+
+function genSpanDiff(
+  oldContent: string,
+  newContent: string,
+  contextLines: number,
+  newHashes: string[],
+  oldHashes: string[],
+  maxLineBytes: number,
+  maxBytes: number,
+  spans: DiffSpan[],
+): { diff: string; firstChangedLine: number | undefined; lineNumbers: (number | undefined)[] } | undefined {
+  const oldLines = splitLines(oldContent);
+  const newLines = splitLines(newContent);
+  if (oldHashes.length !== oldLines.length || newHashes.length !== newLines.length) return undefined;
+  const placed = placeSpans(oldLines.length, newLines.length, spans);
+  if (!placed) return undefined;
+  const trimmed = trimPlacedSpans(placed, oldLines, newLines);
+  const ordered = [...trimmed].sort((a, b) => a.oldStart - b.oldStart || a.newStart - b.newStart);
+  let oldPos = 0;
+  let newPos = 0;
+  for (const span of ordered) {
+    if (span.oldStart < oldPos || span.newStart < newPos) return undefined;
+    const gapOld = span.oldStart - oldPos;
+    const gapNew = span.newStart - newPos;
+    if (gapOld !== gapNew || gapOld < 0) return undefined;
+    oldPos = span.oldEnd + 1;
+    newPos = span.newEnd + 1;
+  }
+  if (oldLines.length - ordered.reduce((sum, span) => sum + Math.max(0, span.oldEnd - span.oldStart + 1), 0) + ordered.reduce((sum, span) => sum + Math.max(0, span.newEnd - span.newStart + 1), 0) !== newLines.length) {
+    return undefined;
+  }
+  const output: string[] = [];
+  const lineNumbers: (number | undefined)[] = [];
+  let firstChangedLine: number | undefined;
+  let outBytes = 0;
+  let stopped = false;
+  let diffTruncated = false;
+  const emitPlain = (line: string, num?: number): void => {
+    if (stopped) return;
+    const lineBytes = Buffer.byteLength(line, "utf-8") + 1;
+    if (outBytes + lineBytes > maxBytes) {
+      stopped = true;
+      diffTruncated = true;
+      return;
+    }
+    outBytes += lineBytes;
+    output.push(line);
+    lineNumbers.push(num);
+  };
+  const emitRow = (prefix: " " | "+" | "-", line: string, hash: string | undefined, num?: number): void => {
+    if (stopped) return;
+    const full = fmtDiffLine(prefix, line, hash);
+    const rowBytes = Buffer.byteLength(full, "utf-8");
+    if (rowBytes > maxLineBytes) {
+      const marker = `[Row is ${formatSize(rowBytes)}, exceeds ${formatSize(maxLineBytes)}; content not shown. Use read to see the full line.]`;
+      emitPlain(fmtDiffLine(prefix, marker, hash), num);
+      return;
+    }
+    if (outBytes + rowBytes + 1 > maxBytes) {
+      stopped = true;
+      diffTruncated = true;
+      return;
+    }
+    outBytes += rowBytes + 1;
+    output.push(full);
+    lineNumbers.push(num);
+  };
+  const emitGap = (gapStartNew: number, gapLen: number, position: "leading" | "middle" | "trailing"): void => {
+    if (stopped || gapLen <= 0) return;
+    if (position === "leading") {
+      let count = contextLines;
+      if (contextLines > 0 && gapLen > count && isBlankLine(newLines[gapStartNew + gapLen - 1]!)) count += 1;
+      count = Math.min(count, gapLen);
+      const skipStart = gapLen - count;
+      if (skipStart > 0) emitPlain(" ...", undefined);
+      for (let k = gapLen - count; k < gapLen && !stopped; k++) {
+        const newIdx = gapStartNew + k;
+        emitRow(" ", newLines[newIdx]!, newHashes[newIdx], newIdx + 1);
+      }
+      return;
+    }
+    if (position === "trailing") {
+      let count = contextLines;
+      if (contextLines > 0 && gapLen > count && isBlankLine(newLines[gapStartNew]!)) count += 1;
+      count = Math.min(count, gapLen);
+      for (let k = 0; k < count && !stopped; k++) {
+        const newIdx = gapStartNew + k;
+        emitRow(" ", newLines[newIdx]!, newHashes[newIdx], newIdx + 1);
+      }
+      if (gapLen > count) emitPlain(" ...", undefined);
+      return;
+    }
+    let headCount = contextLines;
+    let tailCount = contextLines;
+    if (contextLines > 0 && gapLen - headCount > tailCount && isBlankLine(newLines[gapStartNew + headCount - 1]!)) headCount += 1;
+    if (contextLines > 0 && gapLen - tailCount > headCount && isBlankLine(newLines[gapStartNew + gapLen - tailCount]!)) tailCount += 1;
+    const middleLen = gapLen - headCount - tailCount;
+    if (middleLen <= 0) {
+      for (let k = 0; k < gapLen && !stopped; k++) {
+        const newIdx = gapStartNew + k;
+        emitRow(" ", newLines[newIdx]!, newHashes[newIdx], newIdx + 1);
+      }
+      return;
+    }
+    for (let k = 0; k < headCount && !stopped; k++) {
+      const newIdx = gapStartNew + k;
+      emitRow(" ", newLines[newIdx]!, newHashes[newIdx], newIdx + 1);
+    }
+    if (!stopped) emitPlain(" ...", undefined);
+    for (let k = gapLen - tailCount; k < gapLen && !stopped; k++) {
+      const newIdx = gapStartNew + k;
+      emitRow(" ", newLines[newIdx]!, newHashes[newIdx], newIdx + 1);
+    }
+  };
+  oldPos = 0;
+  newPos = 0;
+  for (let spanIdx = 0; spanIdx < ordered.length && !stopped; spanIdx++) {
+    const span = ordered[spanIdx]!;
+    const gapLen = span.oldStart - oldPos;
+    emitGap(newPos, gapLen, spanIdx === 0 ? "leading" : "middle");
+    if (stopped) break;
+    if (firstChangedLine === undefined) firstChangedLine = span.newStart + 1;
+    for (let oldIdx = span.oldStart; oldIdx <= span.oldEnd && !stopped; oldIdx++) {
+      emitRow("-", oldLines[oldIdx]!, oldHashes[oldIdx], oldIdx + 1);
+    }
+    for (let newIdx = span.newStart; newIdx <= span.newEnd && !stopped; newIdx++) {
+      emitRow("+", newLines[newIdx]!, newHashes[newIdx], newIdx + 1);
+    }
+    oldPos = span.oldEnd + 1;
+    newPos = span.newEnd + 1;
+  }
+  if (!stopped) {
+    const trailingLen = oldLines.length - oldPos;
+    emitGap(newPos, trailingLen, "trailing");
+  }
+  if (diffTruncated) {
+    output.push(" ...");
+    lineNumbers.push(undefined);
+    output.push(`[diff truncated at ${formatSize(maxBytes)}; use read to see the rest.]`);
+    lineNumbers.push(undefined);
+  }
+  return { diff: output.join("\n"), firstChangedLine, lineNumbers };
+}
+
 export function genDiff(
   oldContent: string,
   newContent: string,
@@ -50,9 +339,17 @@ export function genDiff(
   newContentHashes?: string[],
   oldContentHashes?: string[],
   limits?: DiffLimits,
+  spans?: DiffSpan[],
 ): { diff: string; firstChangedLine: number | undefined; lineNumbers: (number|undefined)[] } {
   const maxLineBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxLineBytes ?? DEFAULT_MAX_BYTES);
   const maxBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxBytes ?? DEFAULT_MAX_BYTES);
+  if (spans && newContentHashes && oldContentHashes) {
+    const anchored = genSpanDiff(oldContent, newContent, contextLines, newContentHashes, oldContentHashes, maxLineBytes, maxBytes, spans);
+    if (anchored) {
+      const diff = disambiguateDuplicateAnchors(anchored.diff);
+      return { diff, firstChangedLine: anchored.firstChangedLine, lineNumbers: anchored.lineNumbers };
+    }
+  }
   if (!limits?.unlimited && Buffer.byteLength(oldContent, "utf-8") + Buffer.byteLength(newContent, "utf-8") > MAX_DIFF_INPUT_BYTES) {
     const guardedRange = changedRange(oldContent, newContent);
     const guardNote = `[diff truncated at ${formatSize(maxBytes)}; use read to see the rest.]`;
@@ -105,7 +402,7 @@ export function genDiff(
     guardedNumbers.push(undefined);
     guarded.push(guardNote);
     guardedNumbers.push(undefined);
-    return { diff: guarded.join("\n"), firstChangedLine: first, lineNumbers: guardedNumbers };
+    return { diff: disambiguateDuplicateAnchors(guarded.join("\n")), firstChangedLine: first, lineNumbers: guardedNumbers };
   }
   const effectiveNewHashes = newContentHashes ?? _lineHashesPure(newContent);
 
@@ -118,9 +415,9 @@ export function genDiff(
   let outBytes = 0;
   let stopped = false;
   let diffTruncated = false;
-	const lineNumbers: (number|undefined)[] = [];
+  const lineNumbers: (number|undefined)[] = [];
 
-	const emitPlain = (line: string, num?: number): void => {
+  const emitPlain = (line: string, num?: number): void => {
     if (stopped) return;
     const lineBytes = Buffer.byteLength(line, "utf-8") + 1;
     if (outBytes + lineBytes > maxBytes) {
@@ -133,7 +430,7 @@ export function genDiff(
     lineNumbers.push(num);
   };
 
-	const emitRow = (prefix: " " | "+" | "-", line: string, hash: string | undefined, num?: number): void => {
+  const emitRow = (prefix: " " | "+" | "-", line: string, hash: string | undefined, num?: number): void => {
     if (stopped) return;
     const full = fmtDiffLine(prefix, line, hash);
     const rowBytes = Buffer.byteLength(full, "utf-8");
@@ -270,7 +567,8 @@ export function genDiff(
     lineNumbers.push(undefined);
   }
 
-  return { diff: output.join("\n"), firstChangedLine, lineNumbers };
+  const diff = newContentHashes && oldContentHashes ? disambiguateDuplicateAnchors(output.join("\n")) : output.join("\n");
+  return { diff, firstChangedLine, lineNumbers };
 }
 
 export function genPatch(
@@ -279,10 +577,10 @@ export function genPatch(
   newContent: string,
   limits?: DiffLimits,
 ): { patch: string; truncated: boolean } {
-	const patchOpts: Record<string, unknown> = { context: 4 };
-	const ho = (Diff as unknown as Record<string, unknown>).FILE_HEADERS_ONLY;
-	if (ho !== undefined) patchOpts.headerOptions = ho;
-	const full = (Diff.createTwoFilesPatch(path, path, oldContent, newContent, undefined, undefined, patchOpts as never) as unknown as string) ?? "";
+  const patchOpts: Record<string, unknown> = { context: 4 };
+  const ho = (Diff as unknown as Record<string, unknown>).FILE_HEADERS_ONLY;
+  if (ho !== undefined) patchOpts.headerOptions = ho;
+  const full = (Diff.createTwoFilesPatch(path, path, oldContent, newContent, undefined, undefined, patchOpts as never) as unknown as string) ?? "";
   const maxLineBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxLineBytes ?? DEFAULT_MAX_BYTES);
   const maxBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxBytes ?? DEFAULT_MAX_BYTES);
   const out: string[] = [];

package/src/replace-response.ts

@@ -2,7 +2,7 @@ import { formatSize, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
 import type { NEdit } from "./hashline";
 import { HASH_SEP } from "./hashline";
 import type { ReplaceDetails } from "./replace";
-import { genDiff, genPatch } from "./replace-diff";
+import { genDiff, genPatch, type DiffSpan } from "./replace-diff";
 import { visLines, clipLine } from "./utils";
 import { DEDUP_ANCHOR } from "./constants";
 
@@ -51,6 +51,7 @@ export interface SuccessInput {
   editMeta: RMeta;
   boundaryDedupAbove?: string[];
   boundaryDedupBelow?: string[];
+  spans?: DiffSpan[];
 }
 
 
@@ -171,9 +172,9 @@ export function withDedupRows(diff: string, lineNumbers: (number | undefined)[],
 }
 
 export function buildChanged(input: SuccessInput, verb = "replaced", diffContextLines = 1): TResult {
-  const { path, result, warnings, snapshotId, originalNormalized, originalHashes, editMeta, resultHashes, boundaryDedupAbove, boundaryDedupBelow } = input;
+  const { path, result, warnings, snapshotId, originalNormalized, originalHashes, editMeta, resultHashes, boundaryDedupAbove, boundaryDedupBelow, spans } = input;
   const resultLines = visLines(result);
-  const baseDiff = genDiff(originalNormalized, result, diffContextLines, resultHashes, originalHashes);
+  const baseDiff = genDiff(originalNormalized, result, diffContextLines, resultHashes, originalHashes, undefined, spans);
   const diffResult = withDedupRows(baseDiff.diff, baseDiff.lineNumbers, boundaryDedupAbove, boundaryDedupBelow);
   const addedLines = editMeta.addedLines;
   const removedLines = editMeta.removedLines;

package/src/replace-undo.ts

@@ -1,5 +1,5 @@
-import { constants } from "fs";
-import { open } from "fs/promises";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -10,7 +10,7 @@ import { hashSource } from "./hashline";
 import { markServed as markServedScoped, freeAnchors, adoptAnchors } from "./anchor-registry";
 import { resolveInCwd, writeAtomic, type FileIdentity } from "./fs-write";
 import { toLF, stripBOM, restoreEndings, type LineEnding } from "./normalize";
-import { genDiff, genPatch } from "./replace-diff";
+import { genDiff, genPatch, spansFromHashes } from "./replace-diff";
 import { getDiffContextLines } from "./config";
 import { cntDiff, errCode, makePrepareArguments, splitLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
@@ -179,7 +179,8 @@ export function regUndo(pi: ExtensionAPI): void {
         const linesAddedByReplace = cntDiff(diffResult.diff, "+");
         const linesRemovedByReplace = cntDiff(diffResult.diff, "-");
         const restoredRange = changedRange(currentNormalized, undo.content);
-        const undoDiffResult = genDiff(currentNormalized, undo.content, await getDiffContextLines(), undo.hashes, currentHashes);
+        const undoSpans = spansFromHashes(currentHashes, undo.hashes);
+        const undoDiffResult = genDiff(currentNormalized, undo.content, await getDiffContextLines(), undo.hashes, currentHashes, undefined, undoSpans);
         const undoDiff = undoDiffResult.diff;
 
         try {

package/src/replace.ts

@@ -2,15 +2,16 @@ import type {
   ExtensionAPI,
   ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { constants } from "fs";
-import { relative } from "path";
+import { constants } from "node:fs";
+import { relative } from "node:path";
 import {
   genDiff,
+  type DiffSpan,
   type LineEnding,
 } from "./replace-diff";
 import { readNormFile, type NormFile } from "./file-reader";
 import { editToolSchema, buildEditToolSchema, type ReqParams, assertReq, normReq } from "./payload-contract";
-import { decodeStringArray } from "./utils";
+import { decodeStringArray, splitLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { type FileIdentity } from "./fs-write";
 import { applyEdit,
@@ -72,6 +73,7 @@ export interface PipelineResult {
   boundaryDedupAbove: string[];
   boundaryDedupBelow: string[];
   identity: FileIdentity;
+  spans?: DiffSpan[];
 }
 
 
@@ -187,6 +189,9 @@ export async function execPipeline(
   const sortedFixes = [...(anchorResult.autoFixes ?? [])].sort((a, b) => a.removedLineIndex - b.removedLineIndex);
   const aboveFixes = sortedFixes.filter((fix) => fix.kind === "leading" || fix.kind === "last-new-before");
   const belowFixes = sortedFixes.filter((fix) => fix.kind === "trailing" || fix.kind === "first-new-after");
+  const pipeSpan = isNoop ? undefined : hashSpan(originalHashes, edit.hash_bounds[0].hash, edit.hash_bounds[1].hash);
+  const pipeResultCount = splitLines(result).length;
+  const pipeSpans = pipeSpan ? [{ start: pipeSpan[0], end: pipeSpan[1], replacementCount: pipeResultCount - (originalHashes.length - (pipeSpan[1] - pipeSpan[0] + 1)) }] : undefined;
   return {
     path: displayPath,
     originalNormalized,
@@ -208,6 +213,7 @@ export async function execPipeline(
     boundaryDedupAbove: aboveFixes.map((fix) => fix.removedLine),
     boundaryDedupBelow: belowFixes.map((fix) => fix.removedLine),
     identity,
+    ...(pipeSpans ? { spans: pipeSpans } : {}),
   };
 }
 
@@ -218,7 +224,7 @@ export function previewFromPipe(pipe: PipelineResult): RPreview {
       path: pipe.path,
     };
   }
-  const base = genDiff(pipe.originalNormalized, pipe.result, 4, pipe.resultHashes, pipe.originalHashes);
+  const base = genDiff(pipe.originalNormalized, pipe.result, 4, pipe.resultHashes, pipe.originalHashes, undefined, pipe.spans);
   return { diff: withDedupRows(base.diff, base.lineNumbers, pipe.boundaryDedupAbove, pipe.boundaryDedupBelow).diff, path: pipe.path };
 }
 export function previewError(error: unknown): RPreview {

package/src/validation.ts

@@ -1,5 +1,5 @@
-import { constants } from "fs";
-import { access as fsAccess } from "fs/promises";
+import { constants } from "node:fs";
+import { access as fsAccess } from "node:fs/promises";
 import type { LFile } from "./file-kind";
 import type { FileIdentity } from "./fs-write";
 import { errCode } from "./utils";