pi-hashline-edit-pro 2.4.1 → 2.5.1

package/README.md

@@ -63,8 +63,8 @@ Lines up to 200KB are shown in full. Larger lines are replaced by a marker with
 
 Edge cases:
 
-- Images (JPEG, PNG, GIF, WebP) come back as visual attachments.
-- Binary files and directories are rejected with a descriptive error.
+- Images (JPEG, PNG, GIF, WebP, BMP) come back as visual attachments. Other image formats (for example AVIF, HEIC/HEIF, TIFF, ICO, JPEG 2000, JPEG XL, PSD, APNG) are rejected as binary, since the built-in renderer cannot attach them.
+- Binary files and directories are rejected with a descriptive error. A magic-signature match is ignored when the sampled bytes contain no NUL bytes and decode as UTF-8, so a text file whose first bytes happen to match a binary or image signature (for example starting with `BM` or `8BPS`) is still read as text.
 - UTF-16 and UTF-32 text (detected via BOM) is rejected, since editing it would corrupt the file.
 - Empty files come back as a single empty-line hash (`HASH│`); use `replace` on that hash to insert content.
 - BOMs are stripped for display. Non-UTF-8 bytes are shown as `U+FFFD`; editing such a file rewrites it as UTF-8, with a warning.
@@ -96,6 +96,7 @@ Notes:
 - The request is checked before any file I/O, so a bad request never touches the file.
 - Common copy-paste slips are fixed automatically and reported: a leftover `HASH│` prefix in `replacement_text` or `remove_from`/`remove_to`, diff-preview rows pasted into the replacement, a reversed range, or a boundary line pasted twice. New lines that re-include a block adjacent to the range are stripped automatically when that block is unique in the file — the whole run is stripped as one unit (including repeated structural lines like `}`), so re-including an unchanged block next to the range never duplicates it. A missing `path` is resolved from the anchors when they uniquely identify a file in the hash store (reported as a warning); when the anchors match multiple known files the request is rejected with the candidate paths named. `file_path` works as an alias for `path` in all three tools.
 - An edit that produces identical content reports `No changes made` and leaves the anchors alone.
+- Every line in the removed range must match what was last shown to you. The extension records the `HASH│content` rows it serves — `read` output, the auto-read block after `write`, the `+HASH│`/` HASH│` rows of post-edit diffs (replace and undo), the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale/ambiguous-anchor feedback — and verifies the whole range against that record before writing. If an interior line changed on disk since it was shown (external editor, formatter-on-save, code generation) or was never shown, the edit is refused with `[E_RANGE_STALE]` and the current range is returned with fresh anchors, so the retry needs no `read`. Edits outside the served record are only possible for files that were never read (for example right after a `write` with auto-read disabled); once the file has been served, every replaced line must have been shown.
 - After a successful edit you get the post-edit diff with fresh anchors, so you can keep editing without re-reading.
 - Do not issue multiple replace calls on the same file in one message; parallel edits split attention across the post-edit diffs and removed lines are easy to miss. Verify each diff before the next edit on that file.
 
@@ -113,7 +114,6 @@ Notes:
 
 Enabled by default. After a successful `write` that changes the file, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block to the result, so you get fresh `HASH│content` anchors without a separate `read` call.
 
-- After `replace` and `undo_last_replace`, the result shows the post-edit diff. The `+HASH│` and ` HASH│` rows carry the current hashes, so follow-up edits can anchor on the diff directly. Call `read` when you want the full file's anchors.
 - After `replace` and `undo_last_replace`, the result shows the post-edit diff. The `+HASH│` and ` HASH│` rows carry the current hashes, so follow-up edits can anchor on the diff directly. The `-HASH│` rows show removed lines with their old hashes, so you can see exactly which anchors were deleted (those hashes are stale after the edit). Call `read` when you want the full file's anchors.
 - Auto-read keeps a 50KB display budget. Lines over 50KB are skipped with a marker instead of their content (use `read` for lines up to 200KB).
 - Toggle at runtime with `/toggle-auto-read`; the setting persists across sessions.
@@ -142,6 +142,8 @@ Unique anchors by construction. If a line's base hash collides with an already-a
 
 Hashes live in a persistent per-file store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) that keeps the hashes of unchanged lines across edits. When a range is replaced, the runtime maps the old content onto the new content and copies hashes for lines that survived; only genuinely new lines get fresh hashes.
 
+The store also keeps a per-file record of the hashes the model was last served (`read` rows, auto-read blocks, post-edit diff rows). `replace` verifies every line of the resolved range against that record before writing; a line whose hash was never served means it either changed on disk after it was shown or was never shown, and the edit is refused with `[E_RANGE_STALE]`. A `write` clears the record, so edits after a write are verified against whatever the next `read` or auto-read block serves.
+
 Two guarantees make this safe even with duplicated content:
 
 - An edited range never borrows a hash from a line outside it. Lines outside the replaced range keep their hashes unconditionally, even when their content is byte-identical to lines inside the range.
@@ -166,11 +168,13 @@ A no-op replace never changes the file, so anchors remain valid. On first run af
 | `[E_NOT_TEXT]` | The path is a directory, binary file, image, or UTF-16/UTF-32 encoded text; hashline editing only supports text files. |
 | `[E_UNDO_STALE]` | `undo_last_replace` refused: the file was modified or deleted after the last replace. |
 | `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted to the hash store; the `replace` was refused and the file was left unchanged. |
+| `[E_RANGE_STALE]` | A line in the replaced range no longer matches what was last shown (the file changed on disk, or the line was never shown). The edit was refused; the current range is returned with fresh anchors. |
 | `[E_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit. |
 
 ## Troubleshooting
 
 - Stale anchors. `[E_STALE_ANCHOR]` or `[E_AMBIGUOUS_ANCHOR]` mean the file changed since the anchors were read. Call `read` for fresh anchors and retry.
+- Range changed on disk. `[E_RANGE_STALE]` means a line inside the replaced range changed after it was last shown to you (or was never shown). Nothing was modified; the error carries the current range with fresh anchors, so retry with those without a `read`.
 - Reset the hash store. Anchors live in `~/.config/pi-hashline-edit-pro/hash-store.sqlite` (with `-wal`/`-shm` sidecars). Quit pi, delete those three files, and the store is rebuilt on the next session. Anchor history is lost, but no project files are touched.
 - Corrupt store. If the store fails its health check it is renamed to `hash-store.sqlite.corrupt-<timestamp>` and rebuilt automatically.
 - Config directory moved. On non-Windows platforms, if `XDG_CONFIG_HOME` is set, the config directory (and the hash store inside it) lives at `$XDG_CONFIG_HOME/pi-hashline-edit-pro` instead of `~/.config/pi-hashline-edit-pro`. An existing store is not migrated automatically. To keep anchor and undo history, move the old `hash-store.sqlite` files (plus `-wal`/`-shm` sidecars) into the new directory before the first run.

package/index.ts

@@ -13,6 +13,7 @@ import {
   toggleAutoRead,
 } from "./src/config";
 import { loadHashStore, pruneMissing } from "./src/hash-store";
+import { recordServed, clearServed } from "./src/served";
 import { readNormFile } from "./src/file-reader";
 import { loadFileKindAndText } from "./src/file-kind";
 import { toCwd } from "./src/paths";
@@ -61,7 +62,10 @@ export default function (pi: ExtensionAPI): void {
       const writtenPath = (event.input as Record<string, unknown>)?.path;
       if (typeof writtenPath === "string") {
         try {
-          await clearUndo(await resolveTarget(toCwd(writtenPath, ctx.cwd)));
+          const target = await resolveTarget(toCwd(writtenPath, ctx.cwd));
+          await clearUndo(target);
+          const store = await loadHashStore();
+          clearServed(store, target);
         } catch (error) {
           console.error("Failed to clear undo after write:", error);
         }
@@ -84,6 +88,12 @@ export default function (pi: ExtensionAPI): void {
           DEFAULT_MAX_BYTES,
           AUTO_READ_MAX,
         );
+        try {
+          const store = await loadHashStore();
+          recordServed(store, absolutePath, preview.servedHashes);
+        } catch (error) {
+          console.error("Failed to record served state from auto-read:", error);
+        }
         return {
           content: [
             ...(event.content ?? []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "2.4.1",
+  "version": "2.5.1",
   "type": "module",
   "description": "Hash-anchored read/replace/undo tools for pi-coding-agent. Every line gets a unique 3-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",

package/prompts/replace-guidelines.md

@@ -5,4 +5,5 @@
 - `replace`: when copying a line from read output, remove its HASH│ prefix and keep the leading whitespace exactly as shown.
 - `replace`: every `\n` in replacement_text separates lines, so a trailing `\n` adds a final empty line. Mirror the removed lines exactly: a range that ends on a blank line must end replacement_text with `\n` (e.g. `"code\n"`), and a replacement whose last line is not blank must not end with `\n`. To add a blank line after a line, end replacement_text with an explicit empty line after it (e.g. `"X\n"` adds a blank after X). A replacement that is only blank lines is written as one `\n` per blank line.
 - `replace`: when auto-read shows the post-edit diff, its rows are the fresh anchors for the new file — `+HASH│` and ` HASH│` rows carry current hashes and unchanged lines keep their previous hashes, so you can anchor follow-up edits on the diff without re-reading.
+- `replace`: `[E_RANGE_STALE]` means a line inside the replaced range changed on disk after it was last shown (or was never shown). Nothing was modified; the error lists the current range as `HASH│content` rows, so retry with those anchors and no `read`.
 - `replace`: do not issue multiple replace calls on the same file in one message. Issue the next edit only after verifying the previous diff.

package/src/constants.ts

@@ -2,6 +2,7 @@ export const AUTO_READ_MAX = 2000;
 export const SNIFF_BYTES = 8192;
 export const MAX_BYTES = 100 * 1024 * 1024;
 export const MAX_READ_LINE_BYTES = 200 * 1024;
+export const MAX_RANGE_STALE_LINES = 100;
 
 export const HASH_STORE_BUSY_TIMEOUT = 1000;
 export const HASH_STORE_VERSION = 5;

package/src/file-kind.ts

@@ -3,9 +3,10 @@ import { fileTypeFromBuffer } from "file-type";
 import { SNIFF_BYTES, MAX_BYTES } from "./constants";
 
 const IMG_TYPES = new Set<string>([
+  "image/bmp",
+  "image/gif",
   "image/jpeg",
   "image/png",
-  "image/gif",
   "image/webp",
 ]);
 
@@ -39,6 +40,16 @@ function isTextType(mimeType: string): boolean {
   return mimeType.startsWith("text/") || TEXT_TYPES.has(mimeType);
 }
 
+function looksLikeText(sample: Uint8Array): boolean {
+  if (sample.includes(0)) return false;
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(sample);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export type LFile =
   | { kind: "directory" }
   | { kind: "image"; mimeType: string }
@@ -96,7 +107,8 @@ export async function loadFileKindAndText(
     const detectedMimeType = (await fileTypeFromBuffer(sample))?.mime;
     if (
       detectedMimeType !== undefined &&
-      !isTextType(detectedMimeType)
+      !isTextType(detectedMimeType) &&
+      !looksLikeText(sample)
     ) {
       if (IMG_TYPES.has(detectedMimeType)) {
         return { kind: "image", mimeType: detectedMimeType };

package/src/hash-store.ts

@@ -2,7 +2,7 @@ import { existsSync } from "fs";
 import { readFile, rename, mkdir, stat } from "fs/promises";
 import { DatabaseSync } from "node:sqlite";
 import { hashStorePath, hashStoreDir, legacyHashStorePath } from "./paths";
-import { errCode, splitLines } from "./utils";
+import { errCode, isRec, splitLines } from "./utils";
 import { initHasher, contentChecksum } from "./hashline/hasher";
 import { HASH_RE } from "./hashline/alphabet";
 import { HASH_STORE_VERSION, HASH_STORE_BUSY_TIMEOUT } from "./constants";
@@ -17,6 +17,9 @@ interface Prepared {
   undoUpsert: (...params: SqlParams) => void;
   undoGet: (...params: SqlParams) => Record<string, unknown> | undefined;
   undoDelete: (...params: SqlParams) => void;
+  servedGet: (...params: SqlParams) => Record<string, unknown> | undefined;
+  servedUpsert: (...params: SqlParams) => void;
+  servedDelete: (...params: SqlParams) => void;
 }
 
 export interface HashStore {
@@ -37,11 +40,12 @@ interface LegacySnapshot {
   hashes: string[];
 }
 
-function isValidHashList(value: unknown): value is string[] {
+export function isValidHashList(value: unknown): value is string[] {
   if (!Array.isArray(value)) return false;
   for (const hash of value) {
     if (typeof hash !== "string" || !HASH_RE.test(hash)) return false;
   }
+  if (new Set(value).size !== value.length) return false;
   return true;
 }
 
@@ -104,6 +108,13 @@ function openDbWithBusyRetry(storePath: string): { db: DatabaseSync; stmts: Prep
 let cachedDb: { path: string; db: DatabaseSync; stmts: Prepared } | null = null;
 let opening: { path: string; promise: Promise<HashStore> } | null = null;
 let exitHandlerRegistered = false;
+interface SnapshotCacheEntry {
+  checksum: string;
+  lineCount: number;
+  hashes: string[];
+}
+const snapshotCache = new Map<string, SnapshotCacheEntry>();
+export const SNAPSHOT_CACHE_LIMIT = 256;
 function openDb(storePath: string): { db: DatabaseSync; stmts: Prepared } {
   const db = new DatabaseSync(storePath, {
     timeout: HASH_STORE_BUSY_TIMEOUT,
@@ -149,6 +160,13 @@ function buildStore(
       "updated_at INTEGER NOT NULL" +
     ")"
   );
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS served (" +
+      "path TEXT PRIMARY KEY, " +
+      "hashes TEXT NOT NULL, " +
+      "updated_at INTEGER NOT NULL" +
+    ")"
+  );
   const versionRow = db.prepare("SELECT value FROM meta WHERE key = 'version'").get() as { value?: string } | undefined;
   if (versionRow && versionRow.value !== String(HASH_STORE_VERSION)) {
     db.exec("DELETE FROM snapshots");
@@ -159,7 +177,7 @@ function buildStore(
     "ON CONFLICT(key) DO UPDATE SET value = excluded.value"
   ).run(String(HASH_STORE_VERSION));
   const getStmt = db.prepare("SELECT hashes FROM snapshots WHERE path = ? AND checksum = ? AND line_count = ?");
-  const allStmt = db.prepare("SELECT path FROM snapshots UNION SELECT path FROM undo");
+  const allStmt = db.prepare("SELECT path FROM snapshots UNION SELECT path FROM undo UNION SELECT path FROM served");
   const allHashesStmt = db.prepare("SELECT path, hashes FROM snapshots");
   const delStmt = db.prepare("DELETE FROM snapshots WHERE path = ?");
   const upsertStmt = db.prepare(
@@ -174,6 +192,12 @@ function buildStore(
     "SELECT content, bom, ending, hashes, result_content FROM undo WHERE path = ?"
   );
   const undoDelStmt = db.prepare("DELETE FROM undo WHERE path = ?");
+  const servedGetStmt = db.prepare("SELECT hashes FROM served WHERE path = ?");
+  const servedUpsertStmt = db.prepare(
+    "INSERT INTO served (path, hashes, updated_at) VALUES (?, ?, ?) " +
+    "ON CONFLICT(path) DO UPDATE SET hashes = excluded.hashes, updated_at = excluded.updated_at"
+  );
+  const servedDelStmt = db.prepare("DELETE FROM served WHERE path = ?");
   const stmts: Prepared = {
     get: (...params) => getStmt.get(...params) as Record<string, unknown> | undefined,
     allPaths: (...params) => allStmt.all(...params) as Record<string, unknown>[],
@@ -183,6 +207,9 @@ function buildStore(
     undoUpsert: (...params) => { withBusyRetry(() => { undoUpsertStmt.run(...params); }); },
     undoGet: (...params) => undoGetStmt.get(...params) as Record<string, unknown> | undefined,
     undoDelete: (...params) => { withBusyRetry(() => { undoDelStmt.run(...params); }); },
+    servedGet: (...params) => servedGetStmt.get(...params) as Record<string, unknown> | undefined,
+    servedUpsert: (...params) => { withBusyRetry(() => { servedUpsertStmt.run(...params); }); },
+    servedDelete: (...params) => { withBusyRetry(() => { servedDelStmt.run(...params); }); },
   };
   return { db, stmts };
 }
@@ -282,6 +309,7 @@ export function shutdownHashStore(): void {
     shutdownDb(cachedDb.db);
     cachedDb = null;
   }
+  snapshotCache.clear();
 }
 
 function withStore(fn: () => void): void {
@@ -325,11 +353,17 @@ async function migrateLegacy(db: DatabaseSync): Promise<void> {
 
   const rows: [string, string, number, string, number][] = [];
   for (const [key, value] of Object.entries(raw)) {
-    if (!isValidSnapshot(value)) continue;
-    if (new Set(value.hashes).size !== value.hashes.length) {
-      console.warn(`Skipped legacy snapshot with duplicate hashes for ${key}; it will be re-hashed on next read.`);
+    if (
+      isRec(value) &&
+      Array.isArray(value.hashes) &&
+      new Set(value.hashes).size !== value.hashes.length
+    ) {
+      console.warn(
+        `Skipped legacy snapshot with duplicate hashes for ${key}; it will be re-hashed on next read.`,
+      );
       continue;
     }
+    if (!isValidSnapshot(value)) continue;
     rows.push([
       key,
       contentChecksum(value.content),
@@ -359,6 +393,15 @@ async function migrateLegacy(db: DatabaseSync): Promise<void> {
   }
 }
 
+function cacheSnapshot(path: string, checksum: string, lineCount: number, hashes: string[]): void {
+  snapshotCache.delete(path);
+  snapshotCache.set(path, { checksum, lineCount, hashes: hashes.slice() });
+  if (snapshotCache.size > SNAPSHOT_CACHE_LIMIT) {
+    const oldest = snapshotCache.keys().next().value;
+    if (oldest !== undefined) snapshotCache.delete(oldest);
+  }
+}
+
 export function getSnapshot(
   store: HashStore,
   path: string,
@@ -367,17 +410,29 @@ export function getSnapshot(
 ): string[] | undefined {
   const checksum = contentChecksum(content);
   const lineCount = splitLines(content).length;
+  const cached = snapshotCache.get(path);
+  if (cached && cached.checksum === checksum && cached.lineCount === lineCount) {
+    snapshotCache.delete(path);
+    snapshotCache.set(path, cached);
+    return cached.hashes.slice();
+  }
   const row = store.stmts.get(path, checksum, lineCount);
   if (!row) return undefined;
+  let parsed: unknown;
   try {
-    const parsed = JSON.parse(row.hashes as string);
-    if (isValidHashList(parsed)) return parsed;
-    if (deleteCorrupt) store.stmts.deleteOne(path);
-    return undefined;
+    parsed = JSON.parse(row.hashes as string);
   } catch {
     if (deleteCorrupt) store.stmts.deleteOne(path);
+    snapshotCache.delete(path);
     return undefined;
   }
+  if (isValidHashList(parsed)) {
+    cacheSnapshot(path, checksum, lineCount, parsed);
+    return parsed;
+  }
+  if (deleteCorrupt) store.stmts.deleteOne(path);
+  snapshotCache.delete(path);
+  return undefined;
 }
 
 export function upsertSnapshot(
@@ -388,6 +443,7 @@ export function upsertSnapshot(
   hashes: string[],
 ): void {
   store.stmts.upsert(path, checksum, lineCount, JSON.stringify(hashes), Date.now());
+  cacheSnapshot(path, checksum, lineCount, hashes);
 }
 
 export function upsertUndo(store: HashStore, path: string, entry: UndoRecord): void {
@@ -458,7 +514,9 @@ export async function pruneMissing(store: HashStore): Promise<void> {
   withStore(() => {
     for (const path of missing) {
       store.stmts.deleteOne(path);
+      snapshotCache.delete(path);
       store.stmts.undoDelete(path);
+      store.stmts.servedDelete(path);
     }
   });
 }

package/src/hashline/apply.ts

@@ -6,7 +6,9 @@ import {
 	stripDiffPrefixes,
 	swapReversedRanges,
 	warnUnicodeEsc,
-	fmtMismatch,
+	fmtMismatchWithHashes,
+	AnchorMismatchError,
+	assertRangeServed,
 	type RHEdit,
 	type NEdit,
 	type HEdit,
@@ -144,6 +146,7 @@ export function applyEdit(
 	signal?: AbortSignal,
 	precomputedHashes?: string[],
 	filePath?: string,
+	servedHashes?: ReadonlySet<string>,
 	): {
 	content: string;
 	firstChangedLine: number | undefined;
@@ -172,9 +175,13 @@ export function applyEdit(
 		signal,
 	);
 	if (mismatches.length || !initialResolved) {
-		throw new Error(
-			fmtMismatch(mismatches, lineIndex.fileLines, fileHashes, filePath),
+		const feedback = fmtMismatchWithHashes(
+			mismatches,
+			lineIndex.fileLines,
+			fileHashes,
+			filePath,
 		);
+		throw new AnchorMismatchError(feedback.text, feedback.hashes);
 	}
 
 	warnUnicodeEsc(prefixFixed, warnings);
@@ -211,13 +218,22 @@ export function applyEdit(
 			signal,
 		);
 		if (correctedResult.mismatches.length || !correctedResult.resolved) {
-			throw new Error(
-				fmtMismatch(correctedResult.mismatches, lineIndex.fileLines, fileHashes, filePath),
+			const feedback = fmtMismatchWithHashes(
+				correctedResult.mismatches,
+				lineIndex.fileLines,
+				fileHashes,
+				filePath,
 			);
+			throw new AnchorMismatchError(feedback.text, feedback.hashes);
 		}
 		resolved = correctedResult.resolved;
 	}
 
+	if (servedHashes) {
+		abortIf(signal);
+		assertRangeServed(resolved, lineIndex.fileLines, fileHashes, servedHashes, filePath);
+	}
+
 	const spanResult = resToSpan(resolved, content, lineIndex);
 	if (spanResult.kind === "noop") {
 		return {

package/src/hashline/index.ts

@@ -36,6 +36,9 @@ export {
 	swapReversedRanges,
 	fmtMismatch,
 	findNewEdge,
+	assertRangeServed,
+	RangeStaleError,
+	AnchorMismatchError,
 } from "./resolve";
 
 export {

package/src/hashline/resolve.ts

@@ -1,7 +1,7 @@
 import { abortIf, rejectUnknownFields, firstNonEmptyIndex, lastNonEmptyIndex, clipLine } from "../utils";
-import { HASH_CLASS, HL_BARE_PREFIX_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE, canon } from "./hash";
+import { HASH_CLASS, HASH_SEP, HL_BARE_PREFIX_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE, canon } from "./hash";
 import { parseHashRef, parseText, type Anchor } from "./parse";
-import { NEW_CONTENT_NOT_STRING_MSG } from "../constants";
+import { NEW_CONTENT_NOT_STRING_MSG, MAX_RANGE_STALE_LINES } from "../constants";
 
 export type RAnchor = {
 	line: number;
@@ -74,15 +74,16 @@ function assertAligned(
 	}
 }
 
-export function fmtMismatch(
+export function fmtMismatchWithHashes(
   mismatches: HMismatch[],
   fileLines: string[],
   fileHashes: string[],
   filePath?: string,
-): string {
+): { text: string; hashes: string[] } {
   assertAligned(fileLines, fileHashes, "fmtMismatch");
 
   const out: string[] = [];
+  const hashes: string[] = [];
   const notFound = mismatches.filter((m) => m.kind === "not_found");
   const ambiguous = mismatches.filter((m) => m.kind === "ambiguous");
 
@@ -98,6 +99,7 @@ export function fmtMismatch(
       const to = Math.min(fileLines.length, ctx.line + 1);
       const rows: string[] = [];
       for (let ln = from; ln <= to; ln++) {
+        hashes.push(fileHashes[ln - 1]!);
         rows.push(`    ${ln}: ${fileHashes[ln - 1]}│${clipLine(fileLines[ln - 1] ?? "")}`);
       }
       out.push("");
@@ -115,6 +117,7 @@ export function fmtMismatch(
         (m.candidates?.length ?? 0) > sample.length
           ? `, ... (+${(m.candidates?.length ?? 0) - sample.length} more)`
           : "";
+      for (const line of sample) hashes.push(fileHashes[line - 1]!);
       const lines = sample
         .map((line) => {
           const content = clipLine(fileLines[line - 1] ?? "");
@@ -127,7 +130,16 @@ export function fmtMismatch(
     }
   }
 
-  return out.join("\n");
+  return { text: out.join("\n"), hashes };
+}
+
+export function fmtMismatch(
+  mismatches: HMismatch[],
+  fileLines: string[],
+  fileHashes: string[],
+  filePath?: string,
+): string {
+  return fmtMismatchWithHashes(mismatches, fileLines, fileHashes, filePath).text;
 }
 
 const ITEM_KS = new Set(["replacement_text", "remove_from", "remove_to"]);
@@ -476,4 +488,64 @@ export function valEdit(
 	};
 }
 
+export class RangeStaleError extends Error {
+  readonly firstMismatchLine: number;
+  readonly rangeHashes: string[];
+  constructor(message: string, firstMismatchLine: number, rangeHashes: string[]) {
+    super(message);
+    this.name = "RangeStaleError";
+    this.firstMismatchLine = firstMismatchLine;
+    this.rangeHashes = rangeHashes;
+  }
+}
+
+export class AnchorMismatchError extends Error {
+  readonly feedbackHashes: string[];
+  constructor(message: string, feedbackHashes: string[]) {
+    super(message);
+    this.name = "AnchorMismatchError";
+    this.feedbackHashes = feedbackHashes;
+  }
+}
+
+export function assertRangeServed(
+  resolved: RHEdit,
+  fileLines: string[],
+  fileHashes: string[],
+  served: ReadonlySet<string>,
+  filePath?: string,
+): void {
+  assertAligned(fileLines, fileHashes, "assertRangeServed");
+  const startLine = resolved.hash_bounds[0].line;
+  const endLine = resolved.hash_bounds[1].line;
+  const mismatchLines: number[] = [];
+  for (let line = startLine; line <= endLine; line++) {
+    if (!served.has(fileHashes[line - 1]!)) mismatchLines.push(line);
+  }
+  if (mismatchLines.length === 0) return;
+
+  const rangeLength = endLine - startLine + 1;
+  const shownLength = Math.min(rangeLength, MAX_RANGE_STALE_LINES);
+  const rows: string[] = [];
+  const shownHashes: string[] = [];
+  for (let line = startLine; line < startLine + shownLength; line++) {
+    const hash = fileHashes[line - 1]!;
+    shownHashes.push(hash);
+    rows.push(`${hash}${HASH_SEP}${fileLines[line - 1]}`);
+  }
+  const location = filePath ? ` in ${filePath}` : "";
+  const first = mismatchLines[0]!;
+  const mismatchText =
+    mismatchLines.length === 1
+      ? `Line ${first} of the replaced range (lines ${startLine}-${endLine})${location} does not match`
+      : `${mismatchLines.length} of ${rangeLength} line(s) in the replaced range (lines ${startLine}-${endLine})${location} do not match`;
+  const capHint =
+    rangeLength > shownLength
+      ? `\n\n[The range has ${rangeLength} lines; showing the first ${shownLength}. Call read() with offset=${startLine + shownLength} to see the rest.]`
+      : "";
+  const message =
+    `[E_RANGE_STALE] ${mismatchText} what was previously shown: the file changed on disk after the anchors were read, or the line(s) were never shown. Nothing was modified. Current range with fresh anchors:\n\n${rows.join("\n")}${capHint}`;
+  throw new RangeStaleError(message, first, shownHashes);
+}
+
 export { warnUnicodeEsc };

package/src/read.ts

@@ -12,9 +12,10 @@ import { loadFileKindAndText } from "./file-kind";
 import { readNormFile } from "./file-reader";
 import { lineHashes, fmtRegion, HASH_SEP, MAX_HASH_LINES } from "./hashline";
 import { toCwd } from "./paths";
-import { abortIf, isRec, normalizeFilePath } from "./utils";
+import { abortIf, isRec, normalizeFilePath, visLines } from "./utils";
 import { fileSnap } from "./file-reader";
-import { visLines } from "./utils";
+import { loadHashStore } from "./hash-store";
+import { recordServed } from "./served";
 import { loadP, loadGuide } from "./prompts";
 import { valAccess } from "./validation";
 
@@ -59,7 +60,7 @@ export async function fmtReadPreview(
 	path?: string,
 	maxLineBytes = MAX_READ_LINE_BYTES,
 	maxTruncLines = DEFAULT_MAX_LINES,
-): Promise<{ text: string; truncation?: TruncationResult; nextOffset?: number }> {
+): Promise<{ text: string; truncation?: TruncationResult; nextOffset?: number; servedHashes: string[] }> {
 	const allLines = visLines(text);
 	const totalLines = allLines.length;
 	const startLine = normPosInt(options.offset, "offset") ?? 1;
@@ -69,15 +70,18 @@ export async function fmtReadPreview(
       const emptyLineHash = allHashes[0] ?? "";
       return {
 				text: `${emptyLineHash}${HASH_SEP}\n[File is empty. Use replace to insert content.]`,
+				servedHashes: emptyLineHash ? [emptyLineHash] : [],
 			};
 		}
 		return {
 			text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use replace to insert content.`,
+			servedHashes: [],
 		};
 	}
 	if (startLine > totalLines) {
 		return {
 			text: `Offset ${startLine} is beyond end of file (${totalLines} lines total). Use offset=1 to read from the start, or offset=${totalLines} to read the last line.`,
+			servedHashes: [],
 		};
 	}
 
@@ -104,6 +108,11 @@ export async function fmtReadPreview(
 		const skippedTruncation = truncateHead(rows.join("\n"), { maxBytes, maxLines: maxTruncLines });
 		const shownRowCount = skippedTruncation.content === "" ? 0 : skippedTruncation.content.split("\n").length;
 		const lastShownLine = shownRowCount > 0 ? startLine + shownRowCount - 1 : startLine - 1;
+		const oversizedIndexes = new Set(rowSizes.map((row, index) => row.bytes > maxBytes ? index : -1).filter((index) => index >= 0));
+		const servedHashes: string[] = [];
+		for (let index = 0; index < Math.min(shownRowCount, rows.length); index++) {
+			if (!oversizedIndexes.has(index)) servedHashes.push(selectedHashes[index]!);
+		}
 		const lineLabel = oversized.length === 1 ? `Line ${oversized[0]!.lineNumber}` : `Lines ${oversized.map((row) => row.lineNumber).join(", ")}`;
 		const verb = oversized.length === 1 ? "exceeds" : "exceed";
 		const addresses = oversized.map((row) => `${row.lineNumber}p`).join(";");
@@ -120,6 +129,7 @@ export async function fmtReadPreview(
 			text: preview,
 			truncation: skippedTruncation.truncated ? skippedTruncation : undefined,
 			...(nextOffset !== undefined ? { nextOffset } : {}),
+			servedHashes,
 		};
 	}
 
@@ -127,6 +137,8 @@ export async function fmtReadPreview(
 
 	let preview = truncation.content;
 	let nextOffset: number | undefined;
+	const shownCount = truncation.content === "" ? 0 : truncation.content.split("\n").length;
+	const servedHashes = selectedHashes.slice(0, shownCount);
 	if (truncation.truncated) {
 		const endLineDisplay = startLine + truncation.outputLines - 1;
 		nextOffset = endLineDisplay + 1;
@@ -144,6 +156,7 @@ export async function fmtReadPreview(
 		text: preview,
 		truncation: truncation.truncated ? truncation : undefined,
 		...(nextOffset !== undefined ? { nextOffset } : {}),
+		servedHashes,
 	};
 }
 
@@ -198,7 +211,7 @@ export function regRead(pi: ExtensionAPI): void {
 				) => ReturnType<typeof builtinRead.execute>;
 				return executeBuiltinRead(_toolCallId, params, signal, _onUpdate, ctx);
 			}
-      const { normalized, fileHashes, hadUtf8DecodeErrors } = await readNormFile(
+      const { normalized, fileHashes, hadUtf8DecodeErrors, absolutePath: resolvedPath } = await readNormFile(
         rawPath, ctx.cwd, { signal, preloadedFile: file, maxLines: MAX_HASH_LINES },
       );
 			const preview = await fmtReadPreview(
@@ -208,8 +221,14 @@ export function regRead(pi: ExtensionAPI): void {
 					limit: params.limit,
 				},
 				fileHashes,
-				absolutePath,
+				resolvedPath,
 			);
+			try {
+				const store = await loadHashStore();
+				recordServed(store, resolvedPath, preview.servedHashes);
+			} catch (error) {
+				console.error("Failed to record served state from read:", error);
+			}
 			let snapshotId: string | undefined;
 			try {
 				snapshotId = (await fileSnap(absolutePath)).snapshotId;

package/src/replace-diff.ts

@@ -96,6 +96,7 @@ export function genDiff(
       let linesToShow: (string | symbol)[] = displayLines;
       let skipStart = 0;
       let skipMiddle = 0;
+      let skipTail = 0;
 
       if (!lastWasChange) {
         skipStart = Math.max(0, displayLines.length - contextLines);
@@ -104,8 +105,9 @@ export function genDiff(
         const tail = displayLines.slice(-contextLines);
         linesToShow = [...displayLines.slice(0, contextLines), ELLIPSIS_MARKER, ...tail];
         skipMiddle = displayLines.length - contextLines * 2;
-      } else if (linesToShow.length > contextLines) {
+      } else if (!nextPartIsChange && linesToShow.length > contextLines) {
         linesToShow = linesToShow.slice(0, contextLines);
+        skipTail = displayLines.length - contextLines;
       }
 
       if (skipStart > 0) {
@@ -125,6 +127,9 @@ export function genDiff(
         newLineNum++;
         oldLineNum++;
       }
+      if (skipTail > 0) {
+        output.push(" ...");
+      }
     } else {
       newLineNum += displayLines.length;
       oldLineNum += displayLines.length;

package/src/replace-undo.ts

@@ -3,6 +3,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { loadHashStore, upsertSnapshot, upsertUndo, getUndoEntry, deleteUndo, type UndoRecord } from "./hash-store";
+import { recordServedDiff } from "./served";
 import { contentChecksum } from "./hashline/hasher";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { toCwd } from "./paths";
@@ -174,6 +175,7 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
         try {
           const store = await loadHashStore();
           upsertSnapshot(store, mutationTargetPath, contentChecksum(undo.content), splitLines(undo.content).length, undo.hashes);
+          recordServedDiff(store, mutationTargetPath, undoDiff);
         } catch (error) {
           console.error("Failed to restore hash store snapshot after undo:", error);
         }

package/src/replace.ts

@@ -20,6 +20,8 @@ import { applyEdit,
   resEdit,
   parseHashRef,
   MAX_HASH_LINES,
+  RangeStaleError,
+  AnchorMismatchError,
   type HEdit,
   type NEdit,
 } from "./hashline";
@@ -45,6 +47,7 @@ import {
 import { loadP, loadGuide } from "./prompts";
 import { saveUndo } from "./replace-undo";
 import { loadHashStore, findSnapshotPaths, type HashStore } from "./hash-store";
+import { getServed, recordServed, recordServedDiff } from "./served";
 
 const replacementTextSchema = Type.String({
   description:
@@ -232,13 +235,35 @@ export async function execPipeline(
     path, cwd, { signal: options?.signal, accessMode: options?.accessMode, maxLines: MAX_HASH_LINES, store: hashStore, noPersist: options?.noPersist },
   );
 
-  const anchorResult = applyEdit(
-    originalNormalized,
-    edit,
-    options?.signal,
-    originalHashes,
-    path,
-  );
+  const served = await getServed(hashStore, absolutePath);
+  let anchorResult: ReturnType<typeof applyEdit>;
+  try {
+    anchorResult = applyEdit(
+      originalNormalized,
+      edit,
+      options?.signal,
+      originalHashes,
+      path,
+      served,
+    );
+  } catch (error) {
+    if (options?.noPersist !== true) {
+      if (error instanceof RangeStaleError) {
+        try {
+          recordServed(hashStore, absolutePath, error.rangeHashes);
+        } catch (recordError) {
+          console.error("Failed to record served state from range-stale feedback:", recordError);
+        }
+      } else if (error instanceof AnchorMismatchError) {
+        try {
+          recordServed(hashStore, absolutePath, error.feedbackHashes);
+        } catch (recordError) {
+          console.error("Failed to record served state from anchor-mismatch feedback:", recordError);
+        }
+      }
+    }
+    throw error;
+  }
 
   const result = anchorResult.content;
   const isNoop = result === originalNormalized;
@@ -562,7 +587,16 @@ export function buildToolDef(): ToolDef {
           snapshotId: updatedSnapshotId,
           editMeta,
         };
-        return buildChanged(successInput);
+        const changed = buildChanged(successInput);
+        if (changed.details.diff) {
+          try {
+            const store = await loadHashStore();
+            recordServedDiff(store, mutationTargetPath, changed.details.diff);
+          } catch (error) {
+            console.error("Failed to record served state from post-edit diff:", error);
+          }
+        }
+        return changed;
       });
     },
   };

package/src/served.ts

@@ -0,0 +1,52 @@
+import type { HashStore } from "./hash-store";
+import { isValidHashList } from "./hash-store";
+import { HASH_CLASS } from "./hashline/alphabet";
+
+const SERVED_DIFF_ROW_RE = new RegExp(`^[+ ](${HASH_CLASS})│`);
+
+export function servedHashesFromDiff(diff: string): string[] {
+  const hashes: string[] = [];
+  for (const line of diff.split("\n")) {
+    const match = SERVED_DIFF_ROW_RE.exec(line);
+    if (match) hashes.push(match[1]!);
+  }
+  return hashes;
+}
+
+export function getServed(store: HashStore, path: string): Set<string> | undefined {
+  const row = store.stmts.servedGet(path);
+  if (!row) return undefined;
+  try {
+    const parsed = JSON.parse(row.hashes as string);
+    if (!isValidHashList(parsed)) {
+      store.stmts.servedDelete(path);
+      return undefined;
+    }
+    return new Set(parsed);
+  } catch {
+    store.stmts.servedDelete(path);
+    return undefined;
+  }
+}
+
+export function recordServed(store: HashStore, path: string, hashes: string[]): void {
+  if (hashes.length === 0) return;
+  const existing = getServed(store, path) ?? new Set<string>();
+  let changed = false;
+  for (const hash of hashes) {
+    if (!existing.has(hash)) {
+      existing.add(hash);
+      changed = true;
+    }
+  }
+  if (!changed) return;
+  store.stmts.servedUpsert(path, JSON.stringify([...existing]), Date.now());
+}
+
+export function recordServedDiff(store: HashStore, path: string, diff: string): void {
+  recordServed(store, path, servedHashesFromDiff(diff));
+}
+
+export function clearServed(store: HashStore, path: string): void {
+  store.stmts.servedDelete(path);
+}