pi-hashline-edit-pro 1.0.5 → 1.0.7

package/README.md

@@ -62,6 +62,8 @@ Optional parameters:
 
 Paged output ends with a continuation hint, e.g. `[Showing lines 1-50 of 120. Use offset=51 to continue.]`.
 
+Lines up to 200KB are displayed in full; larger lines are replaced by a marker with a bash inspection hint (`sed -n 'Np' <path> | head -c 204800`) since hash anchors require full lines.
+
 Edge cases:
 
 - **Images** (JPEG, PNG, GIF, WebP) are passed through as visual attachments and don't participate in the hashline protocol.
@@ -93,7 +95,7 @@ Exactly one edit per call, with `hash_range_inclusive` and `content_lines` at th
 Behavior:
 
 - **Validation before any file I/O.** Unknown fields, missing fields, wrong types, and malformed anchors are rejected with `[E_BAD_SHAPE]` / `[E_BAD_REF]`. The edit applies against the pre-edit snapshot, so all hashes in the request come from one consistent file state.
-- **Rejected dialects.** The `changes` array dialect and the legacy `oldText`/`newText` dialect are rejected with `[E_BAD_SHAPE]` / `[E_LEGACY_SHAPE]`; the error tells you to send `{hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}`.
+- **Rejected dialects.** The `changes` array dialect and the legacy `oldText`/`newText` dialect are rejected with `[E_LEGACY_SHAPE]`; the error tells you to send `{hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}`.
 - **Autocorrections** (all accompanied by a warning unless noted):
   - A `HASH│` prefix accidentally left on a `content_lines` entry is stripped.
   - Diff-preview rows (`+HASH│…`, `-HASH│…`, `-   │…`) pasted into `content_lines` have their markers stripped. Numbered deletion rows (`-1    foo`) and unified-diff lines are written literally — never silently altered.
@@ -120,6 +122,7 @@ Enabled by default. After a successful `write`, `replace`, or `undo_last_replace
 
 - After `replace` / `undo_last_replace`, the block covers the changed span plus 2 lines of context above and below — the rest of the file keeps its anchors from the persistent store.
 - After `write`, the block dumps from the top of the file. For files over 2000 lines, the dump is truncated with a pagination hint — use `read` with `offset` to continue.
+- 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.
 - If the auto-read itself fails (e.g. the file was deleted between the operation and the read), a short `--- Auto-read failed: ... ---` notice is appended instead of the anchor block, so the model knows the anchors are missing.
 
@@ -129,6 +132,7 @@ Enabled by default. After a successful `write`, `replace`, or `undo_last_replace
 
 - History is per-file and single-level: only the most recent replace can be reverted.
 - History is persisted in the hash store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) and survives session restarts; a failed `write` does not clear it.
+- **Undo is a precondition, not a convenience.** The undo record is persisted *before* the edit is written; if it cannot be persisted, the `replace` is refused with `[E_UNDO_UNAVAILABLE]` and the file is not touched, so every applied edit is undoable. If the file write itself then fails, the previous undo record is restored, so a refused edit never destroys earlier undo history.
 - A successful `write` clears the history for that file.
 - Call `read` after an undo to get fresh anchors for follow-up edits.
 - **Safety guard.** If the file was modified or deleted since the last replace, `undo_last_replace` refuses with `[E_UNDO_STALE]` rather than overwriting those changes.
@@ -157,13 +161,14 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 | `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
 | `[E_INVALID_PATCH]` | A `content_lines` entry is a diff-preview row (`+HASH│`, `-HASH│`, `-   │`) — the marker is stripped automatically with a warning. |
 | `[E_BARE_HASH_PREFIX]` | A `content_lines` entry starts with a hash-like `HASH│` prefix — the prefix is stripped automatically with a warning. |
-| `[E_LEGACY_SHAPE]` | The request uses the unsupported `oldText`/`newText` dialect. |
+| `[E_LEGACY_SHAPE]` | The request uses an unsupported dialect: `oldText`/`newText` fields or a `changes` array. |
 | `[E_BAD_OP]` | Range start line is after range end line — the pair is swapped automatically with a warning. |
 | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. |
 | `[E_NOT_FOUND]` | The path does not exist. |
 | `[E_ACCESS]` | The file is not readable or writable. |
 | `[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_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit. |
 
 ## Hashing
@@ -182,6 +187,14 @@ The alphabet is sized for an LLM consumer: the model tokenizes rather than squin
 - **Atomic and ordered writes.** Files are written via temp-file-then-rename; symlink chains are resolved so the target is updated without replacing the symlink; hard-linked files are updated in place; concurrent edits to the same underlying file serialize through a per-target mutation queue.
 - **One edit per call.** The request shape stays `{path, hash_range_inclusive, content_lines}` from schema through validation to application; there is no batching dialect.
 
+## Troubleshooting
+
+- **Stale anchors.** `[E_STALE_ANCHOR]` / `[E_AMBIGUOUS_ANCHOR]` mean the file changed since the anchors were read, or an earlier `read` never happened. Call `read` for fresh anchors and retry.
+- **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>` (plus `-wal`/`-shm` variants) and rebuilt automatically; the quarantined files can be deleted once a healthy store exists.
+- **Legacy migration.** On first run after upgrading from an older version, the previous `hash-store.json` is imported once and renamed to `hash-store.json.bak`, which can be deleted.
+- **`[E_UNDO_UNAVAILABLE]`.** The edit was refused because the undo record could not be written — check disk space and that the config directory is writable, then retry.
+
 ## Development
 
 Requires [Node.js](https://nodejs.org) ≥ 22.13 and npm.

package/index.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
 import { initHasher } from "./src/hashline";
 import { regReplace } from "./src/replace";
 import { regReplaceUndo, clearUndo } from "./src/replace-undo";
@@ -98,6 +99,7 @@ export default function (pi: ExtensionAPI): void {
         { offset, limit },
         fileHashes,
         absolutePath,
+        DEFAULT_MAX_BYTES,
       );
 
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 62-symbol, perfect hashing)",
   "main": "index.ts",
@@ -47,7 +47,7 @@
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test:coverage": "vitest run --coverage --coverage.thresholds.lines=90 --coverage.thresholds.statements=90 --coverage.thresholds.functions=85 --coverage.thresholds.branches=80",
     "lint": "eslint \"src/**/*.ts\" \"index.ts\" \"test/**/*.ts\"",
     "typecheck": "tsc --noEmit"
   },

package/src/constants.ts

@@ -1,6 +1,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 HASH_STORE_BUSY_TIMEOUT = 1000;
 export const HASH_STORE_VERSION = 4;

package/src/hashline/hash.ts

@@ -143,6 +143,7 @@ export async function lineHashes(
   store?: HashStore,
   persist?: boolean,
 ): Promise<string[]> {
+  await initHasher();
   if (!path) {
     return _lineHashesPure(content);
   }
@@ -233,6 +234,16 @@ function mapStableHashes(
     if (idx !== undefined) removedIndexes.add(idx);
   }
 
+  let spanStart = oldLines.length;
+  let spanEnd = -1;
+  for (const idx of removedIndexes) {
+    if (idx < spanStart) spanStart = idx;
+    if (idx > spanEnd) spanEnd = idx;
+  }
+  const spanLen = spanEnd >= spanStart ? spanEnd - spanStart + 1 : 0;
+  const replacementLen = newLines.length - oldLines.length + spanLen;
+  const shiftAfterSpan = spanEnd >= spanStart ? replacementLen - spanLen : 0;
+
   const survivors: { index: number; hash: string }[] = [];
   const removedEntries: { index: number; hash: string }[] = [];
   for (let i = 0; i < oldLines.length; i++) {
@@ -260,7 +271,8 @@ function mapStableHashes(
   for (const entry of survivors) {
     const candidates = newByContent.get(canon(oldLines[entry.index]!));
     if (!candidates || candidates.length === 0) continue;
-    const pos = nearestNew(candidates, entry.index);
+    const target = entry.index > spanEnd ? entry.index + shiftAfterSpan : entry.index;
+    const pos = nearestNew(candidates, target);
     if (pos < 0) continue;
     const newIdx = candidates.splice(pos, 1)[0]!;
     newHashes[newIdx] = entry.hash;

package/src/hashline/hasher.ts

@@ -9,7 +9,7 @@ let hasher: Hasher | null = null;
 
 export function getH(): Hasher {
 	if (hasher) return hasher;
-	throw new Error("xxhash-wasm not initialized yet. This should not happen.");
+	throw new Error("xxhash-wasm hasher not initialized; await initHasher() before calling hashline APIs.");
 }
 
 const hasherP: Promise<Hasher> = xxhash().then((h) => {

package/src/hashline/resolve.ts

@@ -225,7 +225,7 @@ export function stripBarePrefixes(
 			? "none of the stripped hashes match current file lines"
 			: `${matchedCount} of ${stripped.length} stripped hash(es) match current file lines`;
 	warnings.push(
-		`Autocorrected: stripped "HASH│" prefix copied from read output in ${locations} (${evidence}).`
+		`[E_BARE_HASH_PREFIX] Autocorrected: stripped "HASH│" prefix copied from read output in ${locations} (${evidence}).`
 	);
 	return { ...edit, content_lines: contentLines };
 }
@@ -251,7 +251,7 @@ export function stripDiffPrefixes(
 	if (stripped.length === 0) return edit;
 	const locations = stripped.map((i) => `content_lines[${i}]`).join(", ");
 	warnings.push(
-		`Autocorrected: stripped diff-preview marker copied from the diff preview in ${locations}.`
+		`[E_INVALID_PATCH] Autocorrected: stripped diff-preview marker copied from the diff preview in ${locations}.`
 	);
 	return { ...edit, content_lines: contentLines };
 }
@@ -276,7 +276,7 @@ export function swapReversedRanges(
 		return edit;
 	}
 	warnings.push(
-		`Autocorrected: hash_range_inclusive was reversed (start ${startRef.hash} is after end ${endRef.hash}); swapped the pair.`
+		`[E_BAD_OP] Autocorrected: hash_range_inclusive was reversed (start ${startRef.hash} is after end ${endRef.hash}); swapped the pair.`
 	);
 	return { ...edit, hash_range_inclusive: [endRef, startRef] as [Anchor, Anchor] };
 }

package/src/read.ts

@@ -6,6 +6,7 @@ import {
 	type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { MAX_READ_LINE_BYTES } from "./constants";
 import { loadFileKindAndText } from "./file-kind";
 import { readNormFile } from "./file-reader";
 import { lineHashes, fmtRegion, HASH_SEP, MAX_HASH_LINES } from "./hashline";
@@ -58,6 +59,7 @@ export async function fmtReadPreview(
 	options: { offset?: number; limit?: number },
 	precomputedHashes?: string[],
 	path?: string,
+	maxLineBytes = MAX_READ_LINE_BYTES,
 ): Promise<{ text: string; truncation?: TruncationResult; nextOffset?: number }> {
 	const allLines = visLines(text);
 	const totalLines = allLines.length;
@@ -88,15 +90,42 @@ export async function fmtReadPreview(
 	const allHashes = precomputedHashes ?? await (path ? lineHashes(text, path) : lineHashes(text));
 	const selectedHashes = allHashes.slice(startLine - 1, endIdx);
 	const formatted = fmtRegion(selectedHashes, selected);
-
-	const truncation = truncateHead(formatted);
-	if (truncation.firstLineExceedsLimit) {
+	const maxBytes = maxLineBytes;
+	const rowSizes = selected.map((line, index) => ({
+		lineNumber: startLine + index,
+		bytes: Buffer.byteLength(`${selectedHashes[index]}${HASH_SEP}${line}`, "utf-8"),
+	}));
+	if (rowSizes.some((row) => row.bytes > maxBytes)) {
+		const oversized = rowSizes.filter((row) => row.bytes > maxBytes);
+		const rows = rowSizes.map((row, index) =>
+			row.bytes > maxBytes
+				? `[Line ${row.lineNumber} is ${formatSize(row.bytes)}, exceeds ${formatSize(maxBytes)}; content not shown. Use bash: sed -n '${row.lineNumber}p' <path> | head -c ${maxBytes}]`
+				: fmtRegion([selectedHashes[index]!], [selected[index]!]),
+		);
+		const skippedTruncation = truncateHead(rows.join("\n"), { maxBytes });
+		const shownRows = rowSizes.filter((row) => row.bytes <= maxBytes);
+		const lastShownLine = shownRows.at(-1)?.lineNumber ?? startLine - 1;
+		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(";");
+		const warning = `[${lineLabel} ${verb} ${formatSize(maxBytes)}; content not shown because hashline anchors require full lines. Inspect with bash: sed -n '${addresses}' <path> | head -c ${maxBytes}]`;
+		let preview = skippedTruncation.content;
+		let nextOffset: number | undefined;
+		if (shownRows.length > 0 && (skippedTruncation.truncated || lastShownLine < totalLines)) {
+			nextOffset = lastShownLine + 1;
+			preview += `\n\n${warning}\n${formatPaginationHint(startLine, lastShownLine, totalLines, nextOffset, skippedTruncation.truncated ? skippedTruncation.maxBytes : undefined)}`;
+		} else {
+			preview += `\n\n${warning}`;
+		}
 		return {
-			text: `[Line ${startLine} exceeds ${formatSize(truncation.maxBytes)}. Hashline output requires full lines; cannot compute hashes for a truncated preview.]`,
-			truncation,
+			text: preview,
+			truncation: skippedTruncation.truncated ? skippedTruncation : undefined,
+			...(nextOffset !== undefined ? { nextOffset } : {}),
 		};
 	}
 
+	const truncation = truncateHead(formatted, { maxBytes });
+
 	let preview = truncation.content;
 	let nextOffset: number | undefined;
 	if (truncation.truncated) {

package/src/replace-render.ts

@@ -16,6 +16,7 @@ export type RRState = {
 	argsKey?: string;
 	preview?: RPreview;
 	previewGeneration?: number;
+	previewTimer?: ReturnType<typeof setTimeout>;
 };
 
 export function getPreviewInput(

package/src/replace-undo.ts

@@ -2,7 +2,7 @@ import { readFile } from "fs/promises";
 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 } from "./hash-store";
+import { loadHashStore, upsertSnapshot, upsertUndo, getUndoEntry, deleteUndo, type UndoRecord } from "./hash-store";
 import { contentChecksum } from "./hashline/hasher";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { toCwd } from "./paths";
@@ -19,9 +19,14 @@ export interface UndoEntry {
   resultContent: string;
 }
 
-export async function saveUndo(path: string, entry: UndoEntry): Promise<boolean> {
+export async function saveUndo(
+  path: string,
+  entry: UndoEntry,
+): Promise<{ persisted: boolean; restore: () => Promise<void> }> {
+  let previous: UndoRecord | undefined;
   try {
     const store = await loadHashStore();
+    previous = getUndoEntry(store, path);
     upsertUndo(store, path, {
       content: entry.content,
       bom: entry.bom,
@@ -29,11 +34,22 @@ export async function saveUndo(path: string, entry: UndoEntry): Promise<boolean>
       hashes: entry.hashes,
       resultContent: entry.resultContent,
     });
-    return true;
   } catch (error) {
     console.error("Failed to persist undo entry:", error);
-    return false;
+    return { persisted: false, restore: async () => undefined };
   }
+  return {
+    persisted: true,
+    restore: async () => {
+      try {
+        const store = await loadHashStore();
+        if (previous) upsertUndo(store, path, previous);
+        else deleteUndo(store, path);
+      } catch (error) {
+        console.error("Failed to restore previous undo entry:", error);
+      }
+    },
+  };
 }
 
 export async function getUndo(path: string): Promise<UndoEntry | undefined> {
@@ -101,16 +117,15 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
       }
 
       return withFileMutationQueue(mutationTargetPath, async () => {
-        let currentNormalized: string | undefined;
+        let currentRaw: string | undefined;
         try {
-          const currentRaw = await readFile(mutationTargetPath, "utf-8");
-          const { text: currentStripped } = stripBOM(currentRaw);
-          currentNormalized = toLF(currentStripped);
+          currentRaw = await readFile(mutationTargetPath, "utf-8");
         } catch (error) {
           if (errCode(error) !== "ENOENT") throw error;
         }
 
-        if (currentNormalized === undefined) {
+        if (currentRaw === undefined) {
+          await clearUndo(mutationTargetPath);
           return {
             content: [
               {
@@ -122,7 +137,8 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
             details: {},
           };
         }
-        if (currentNormalized !== undo.resultContent) {
+        if (currentRaw !== undo.bom + restoreEndings(undo.resultContent, undo.originalEnding)) {
+          await clearUndo(mutationTargetPath);
           return {
             content: [
               {
@@ -135,6 +151,8 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
           };
         }
 
+        const { text: currentStripped } = stripBOM(currentRaw);
+        const currentNormalized = toLF(currentStripped);
         const diffResult = genDiff(undo.content, currentNormalized, 0);
         const linesAddedByReplace = cntDiff(diffResult.diff, "+");
         const linesRemovedByReplace = cntDiff(diffResult.diff, "-");

package/src/replace.ts

@@ -99,9 +99,11 @@ interface PipelineResult {
   totalRemovedLines: number;
 }
 
+const PREVIEW_DEBOUNCE_MS = 150;
+
 const ROOT_KS = new Set(["path", "content_lines", "hash_range_inclusive"]);
 
-const LEGACY_KS = ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines"];
+const LEGACY_KS = ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines", "changes"];
 
 export function assertNoLegacyKeys(request: unknown): void {
   if (!isRec(request)) return;
@@ -251,11 +253,6 @@ export async function compPreview(
 ): Promise<RPreview> {
   try {
     const normalized = normReq(request);
-    if (isRec(request) && Array.isArray(request.changes)) {
-      return {
-        error: `[E_BAD_SHAPE] The replace tool does not accept a "changes" array. Send hash_range_inclusive and content_lines at the top level (one edit per call).`
-      };
-    }
     assertReq(normalized);
     const { path, originalNormalized, result, resultHashes } = await execPipeline(
       normalized,
@@ -323,12 +320,20 @@ export function buildToolDef(): ToolDef {
     renderShell: "default",
     renderCall(args, theme, context) {
       const previewInput = getPreviewInput(args);
+      const cancelPendingPreview = () => {
+        if (context.state.previewTimer) {
+          clearTimeout(context.state.previewTimer);
+          context.state.previewTimer = undefined;
+        }
+      };
       if (context.executionStarted) {
+        cancelPendingPreview();
         context.state.argsKey = undefined;
         context.state.preview = undefined;
         context.state.previewGeneration =
           (context.state.previewGeneration ?? 0) + 1;
       } else if (!context.argsComplete || !previewInput) {
+        cancelPendingPreview();
         context.state.argsKey = undefined;
         context.state.preview = undefined;
         context.state.previewGeneration =
@@ -336,31 +341,35 @@ export function buildToolDef(): ToolDef {
       } else {
         const argsKey = JSON.stringify(previewInput);
         if (context.state.argsKey !== argsKey) {
+          cancelPendingPreview();
           context.state.argsKey = argsKey;
           context.state.preview = undefined;
           const previewGeneration = (context.state.previewGeneration ?? 0) + 1;
           context.state.previewGeneration = previewGeneration;
-          compPreview(args, context.cwd)
-            .then((preview) => {
-              if (
-                context.state.argsKey === argsKey &&
-                context.state.previewGeneration === previewGeneration
-              ) {
-                context.state.preview = preview;
-                context.invalidate();
-              }
-            })
-            .catch((err: unknown) => {
-              if (
-                context.state.argsKey === argsKey &&
-                context.state.previewGeneration === previewGeneration
-              ) {
-                context.state.preview = {
-                  error: err instanceof Error ? err.message : String(err),
-                };
-                context.invalidate();
-              }
-            });
+          context.state.previewTimer = setTimeout(() => {
+            context.state.previewTimer = undefined;
+            compPreview(args, context.cwd)
+              .then((preview) => {
+                if (
+                  context.state.argsKey === argsKey &&
+                  context.state.previewGeneration === previewGeneration
+                ) {
+                  context.state.preview = preview;
+                  context.invalidate();
+                }
+              })
+              .catch((err: unknown) => {
+                if (
+                  context.state.argsKey === argsKey &&
+                  context.state.previewGeneration === previewGeneration
+                ) {
+                  context.state.preview = {
+                    error: err instanceof Error ? err.message : String(err),
+                  };
+                  context.invalidate();
+                }
+              });
+          }, PREVIEW_DEBOUNCE_MS);
         }
       }
       const text =
@@ -389,6 +398,10 @@ export function buildToolDef(): ToolDef {
 
       const renderState = context.state as RRState | undefined;
       if (renderState) {
+        if (renderState.previewTimer) {
+          clearTimeout(renderState.previewTimer);
+          renderState.previewTimer = undefined;
+        }
         renderState.preview = undefined;
         renderState.previewGeneration = (renderState.previewGeneration ?? 0) + 1;
       }
@@ -410,8 +423,9 @@ export function buildToolDef(): ToolDef {
 
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const canonical = normReq(params);
+      assertReq(canonical);
 
-      const normalizedParams = canonical as ReqParams;
+      const normalizedParams = canonical;
       const path = normalizedParams.path;
       const absolutePath = toCwd(path, ctx.cwd);
       const mutationTargetPath = await resolveTarget(absolutePath);
@@ -462,21 +476,27 @@ export function buildToolDef(): ToolDef {
         }
 
         abortIf(signal);
-        await writeAtomic(
-          absolutePath,
-          bom + restoreEndings(result, originalEnding),
-        );
-        const undoPersisted = await saveUndo(mutationTargetPath, {
+        const undo = await saveUndo(mutationTargetPath, {
           content: originalNormalized,
           bom,
           originalEnding,
           hashes: originalHashes,
           resultContent: result,
         });
-        if (!undoPersisted) {
-          warnings.push(
-            "Undo history could not be persisted; undo_last_replace will not be available for this edit.",
+        if (!undo.persisted) {
+          throw new Error(
+            `[E_UNDO_UNAVAILABLE] Cannot persist undo history to the hash store; the edit was NOT applied and ${path} is unchanged. Retry the replace, or use write if the store cannot be recovered.`
+          );
+        }
+        try {
+          abortIf(signal);
+          await writeAtomic(
+            absolutePath,
+            bom + restoreEndings(result, originalEnding),
           );
+        } catch (error) {
+          await undo.restore();
+          throw error;
         }
         const updatedSnapshotId = (await fileSnap(absolutePath))
           .snapshotId;