pi-hashline-edit-pro 2.4.0 → 2.5.0

package/README.md

@@ -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.
 
@@ -142,6 +143,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 +169,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.0",
+  "version": "2.5.0",
   "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

@@ -1,7 +1,9 @@
+- `replace`: remove_from and remove_to take ONLY the bare 3-char hash — read row `ve7│function hello() {` means `"remove_from": "ve7"`. Never paste the line content, a code line, a paragraph, or the whole `HASH│content` row into these fields.
 - `replace`: remove_from and remove_to mark the exact lines that are REMOVED, and replacement_text is their complete replacement applied in order; nothing outside the range changes. Every line inside the range that is not reproduced byte-exact in replacement_text is deleted from the file.
 - `replace`: keep the range as tight as the change — anchor only the first and last line that actually change, never a whole function, class, or import block when only part of it changes.
 - `replace`: to replace a single line, set both remove_from and remove_to to the same hash: remove_from: "<HASH>", remove_to: "<HASH>".
 - `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/prompts/replace-snippet.md

@@ -1 +1 @@
-Replace lines in a text file via HASH anchors from read, anchoring exactly the lines that change; one edit per tool call
+Replace lines in a text file via bare 3-char HASH anchors from read — hash only, never line content; anchor exactly the lines that change; one edit per tool call

package/prompts/replace.md

@@ -1 +1 @@
-Replace a range of lines in a text file, targeted by the 3-char HASH anchors from read's HASH│content output.
+Replace a range of lines in a text file, targeted by the 3-char HASH anchors from read output. remove_from and remove_to must each be a BARE 3-character hash: copy only the hash from the leftmost column of a read row (row `ve7│function hello() {` means `"remove_from": "ve7"`). Never pass the line content, a code line, or a paragraph into these fields.

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/hash-store.ts

@@ -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,7 +40,7 @@ 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;
@@ -149,6 +152,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 +169,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 +184,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 +199,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 };
 }
@@ -459,6 +478,7 @@ export async function pruneMissing(store: HashStore): Promise<void> {
     for (const path of missing) {
       store.stmts.deleteOne(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-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:
@@ -52,11 +55,11 @@ const replacementTextSchema = Type.String({
 });
 
 const removeFromSchema = Type.String({
-  description: "3-char HASH from read output marking the FIRST line to remove (inclusive)",
+  description: "Bare 3-char HASH only (e.g. \"aB3\") — copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the FIRST line to remove (inclusive)",
 });
 
 const removeToSchema = Type.String({
-  description: "3-char HASH from read output marking the LAST line to remove (inclusive)",
+  description: "Bare 3-char HASH only (e.g. \"aB3\") — copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the LAST line to remove (inclusive)",
 });
 
 export const editToolSchema = Type.Object(
@@ -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);
+}