pi-hashline-edit-pro 2.5.2 → 2.6.0

package/README.md

@@ -32,7 +32,7 @@ kQm│}
   "path": "src/main.ts",
   "remove_from": "szJ",
   "remove_to": "szJ",
-  "replacement_text": "  console.log('hi');"
+  "replacement_lines": ["  console.log('hi');"]
 }
 ```
 
@@ -76,14 +76,14 @@ Edge cases:
 
 The built-in `edit` tool is disabled. `replace` is the only edit path, and it takes the hash anchors from `read` output.
 
-One edit per call, with `remove_from`, `remove_to`, and `replacement_text` at the top level:
+One edit per call, with `remove_from`, `remove_to`, and `replacement_lines` at the top level:
 
 ```json
 {
   "path": "src/main.ts",
   "remove_from": "szJ",
   "remove_to": "kQm",
-  "replacement_text": "  console.log('hi');\n}"
+  "replacement_lines": ["  console.log('hi');", "}"]
 }
 ```
 
@@ -91,12 +91,12 @@ One edit per call, with `remove_from`, `remove_to`, and `replacement_text` at th
 | --- | --- |
 | `remove_from` | 3-char hash from `read` output marking the FIRST line to remove (inclusive). |
 | `remove_to` | 3-char hash from `read` output marking the LAST line to remove (inclusive). |
-| `replacement_text` | Replacement text as a single string with `\n` line separators; every `\n` separates lines, so a trailing `\n` adds a final empty line — mirror the removed lines exactly, blank lines included (a replacement that is only blank lines is written as one `\n` per blank line). Use `""` to delete the range. |
+| `replacement_lines` | Replacement lines as an array of strings, one element per line. Mirror the removed lines exactly, blank lines included: use `[]` to delete the range, `[""]` for a single blank line, `["a", ""]` for a line followed by a blank line, and `["", ""]` for two blank lines. Do not embed `\n` inside an element — each element is exactly one line. |
 
 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.
+- Common copy-paste slips are fixed automatically and reported: a leftover `HASH│` prefix in `replacement_lines` 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.
@@ -157,12 +157,12 @@ A no-op replace never changes the file, so anchors remain valid. On first run af
 
 | Code | Meaning |
 | --- | --- |
-| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `replacement_text` must be a string with `\n` line separators). |
+| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `replacement_lines` must be an array of strings, one element per line). |
 | `[E_BAD_REF]` | An anchor in `remove_from`/`remove_to` is not a bare 3-char hash. |
 | `[E_STALE_ANCHOR]` | An anchor does not match any line in the current file; call `read` for fresh anchors. |
 | `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
-| `[E_INVALID_PATCH]` | A `replacement_text` line is a diff-preview row (`+HASH│`, `-HASH│`, `-   │`). The marker is stripped automatically with a warning. |
-| `[E_BARE_HASH_PREFIX]` | A `replacement_text` line starts with a hash-like `HASH│` prefix. The prefix is stripped automatically with a warning. |
+| `[E_INVALID_PATCH]` | A `replacement_lines` element is a diff-preview row (`+HASH│`, `-HASH│`, `-   │`). The marker is stripped automatically with a warning. |
+| `[E_BARE_HASH_PREFIX]` | A `replacement_lines` element starts with a hash-like `HASH│` prefix. The prefix is stripped automatically with a warning. |
 | `[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. |

package/index.ts

@@ -13,7 +13,7 @@ import {
   toggleAutoRead,
 } from "./src/config";
 import { loadHashStore, pruneMissing } from "./src/hash-store";
-import { recordServed, clearServed } from "./src/served";
+import { recordServedSafe, clearServed } from "./src/served";
 import { readNormFile } from "./src/file-reader";
 import { loadFileKindAndText } from "./src/file-kind";
 import { toCwd } from "./src/paths";
@@ -88,12 +88,7 @@ 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);
-        }
+        await recordServedSafe(absolutePath, preview.servedHashes, "auto-read");
         return {
           content: [
             ...(event.content ?? []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "2.5.2",
+  "version": "2.6.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,9 +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`: remove_from and remove_to mark the exact lines that are REMOVED, and replacement_lines 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_lines 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`: replacement_lines is an array of strings, one element per line. Mirror the removed lines exactly, blank lines included: use `[]` to delete the range, `[""]` for a single blank line, `["a", ""]` for a line followed by a blank line, and `["", ""]` for two blank lines. Do not embed `\n` inside an element — each element is exactly one 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/config.ts

@@ -1,6 +1,6 @@
 import { readFile } from "fs/promises";
 import { configPath } from "./paths";
-import { errCode } from "./utils";
+import { errCode, isRec } from "./utils";
 import { writeAtomic } from "./fs-write";
 
 export interface Config {
@@ -12,10 +12,12 @@ const DEFAULT_CONFIG: Config = {
 };
 
 function parseConfig(content: string): Config {
-  const parsed = JSON.parse(content) as Partial<Config>;
-  return {
-    autoRead: parsed.autoRead === true,
-  };
+  const parsed = JSON.parse(content) as unknown;
+  const autoRead = isRec(parsed) ? parsed.autoRead : undefined;
+  if (typeof autoRead !== "boolean") {
+    throw new Error("config.json must be an object with a boolean autoRead field");
+  }
+  return { autoRead };
 }
 
 

package/src/constants.ts

@@ -6,6 +6,6 @@ export const MAX_RANGE_STALE_LINES = 100;
 
 export const HASH_STORE_BUSY_TIMEOUT = 1000;
 export const HASH_STORE_VERSION = 5;
-export const NEW_CONTENT_NOT_STRING_MSG =
-  `[E_BAD_SHAPE] "replacement_text" must be a string with \\n line separators, not an array.`
-  + ` Do not pass an array of lines — pass the replacement text as one string: "line1\\nline2". Use "" to delete a range.`;
+export const NEW_CONTENT_NOT_ARRAY_MSG =
+  `[E_BAD_SHAPE] "replacement_lines" must be an array of strings, one element per line, not a single string.`
+  + ` Do not pass one string with \\n separators — pass an array of lines: ["line1", "line2"]. Use [] to delete a range.`;

package/src/file-reader.ts

@@ -45,6 +45,18 @@ export async function fileSnap(absolutePath: string): Promise<SnapInfo> {
   };
 }
 
+export async function safeSnapId(
+  absolutePath: string,
+  context: string,
+): Promise<string | undefined> {
+  try {
+    return (await fileSnap(absolutePath)).snapshotId;
+  } catch (error) {
+    console.error(`Failed to compute snapshot (${context}):`, error);
+    return undefined;
+  }
+}
+
 export interface ReadNormOptions {
   signal?: AbortSignal;
   accessMode?: number;

package/src/hash-store.ts

@@ -286,7 +286,11 @@ async function openStore(storePath: string): Promise<HashStore> {
   const { db, stmts } = opened;
 
   if (!existed) {
-    await migrateLegacy(db);
+    try {
+      await migrateLegacy(db);
+    } catch (error) {
+      console.error("Hash store migration failed; continuing without legacy import:", error);
+    }
   }
   cachedDb = { path: storePath, db, stmts };
 
@@ -328,20 +332,19 @@ export function shutdownHashStore(): void {
 }
 
 function withStore(fn: () => void): void {
-  if (cachedDb) {
-    withBusyRetry(() => {
-      cachedDb!.db.exec("BEGIN IMMEDIATE");
-      try {
-        fn();
-        cachedDb!.db.exec("COMMIT");
-      } catch (e) {
-        try { cachedDb!.db.exec("ROLLBACK"); } catch {}
-        throw e;
-      }
-    });
-  } else {
-    fn();
+  if (!cachedDb) {
+    throw new Error("Hash store is not open; transactional update aborted");
   }
+  withBusyRetry(() => {
+    cachedDb!.db.exec("BEGIN IMMEDIATE");
+    try {
+      fn();
+      cachedDb!.db.exec("COMMIT");
+    } catch (e) {
+      try { cachedDb!.db.exec("ROLLBACK"); } catch {}
+      throw e;
+    }
+  });
 }
 
 async function migrateLegacy(db: DatabaseSync): Promise<void> {
@@ -388,17 +391,19 @@ async function migrateLegacy(db: DatabaseSync): Promise<void> {
     ]);
   }
   if (rows.length > 0) {
-    db.exec("BEGIN IMMEDIATE");
-    try {
-      const stmt = db.prepare(
-        "INSERT OR REPLACE INTO snapshots (path, checksum, line_count, hashes, updated_at) VALUES (?, ?, ?, ?, ?)"
-      );
-      for (const row of rows) stmt.run(...row);
-      db.exec("COMMIT");
-    } catch (e) {
-      db.exec("ROLLBACK");
-      throw e;
-    }
+    withBusyRetry(() => {
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const stmt = db.prepare(
+          "INSERT OR REPLACE INTO snapshots (path, checksum, line_count, hashes, updated_at) VALUES (?, ?, ?, ?, ?)"
+        );
+        for (const row of rows) stmt.run(...row);
+        db.exec("COMMIT");
+      } catch (e) {
+        try { db.exec("ROLLBACK"); } catch {}
+        throw e;
+      }
+    });
   }
 
   try {

package/src/hashline/index.ts

@@ -6,9 +6,6 @@ export {
 	HASH_SPACE,
 	HASH_PROBE_STRIDE,
 	MAX_HASH_LINES,
-	HL_PREFIX_PLUS_RE,
-	HL_PREFIX_MINUS_RE,
-	HL_BARE_PREFIX_RE,
 	lineHashes,
 	_lineHashesPure,
 	initHasher,
@@ -22,7 +19,6 @@ export {
 } from "./parse";
 
 export {
-	type RAnchor,
 	type HEdit,
 	type RHEdit,
 	type HTEdit,
@@ -34,7 +30,6 @@ export {
 	stripBarePrefixes,
 	stripDiffPrefixes,
 	swapReversedRanges,
-	fmtMismatch,
 	findNewEdge,
 	assertRangeServed,
 	RangeStaleError,

package/src/hashline/parse.ts

@@ -2,7 +2,7 @@ import {
 	ANCHOR_LEN,
 	ALPH_RE,
 } from "./hash";
-import { NEW_CONTENT_NOT_STRING_MSG } from "../constants";
+import { NEW_CONTENT_NOT_ARRAY_MSG } from "../constants";
 
 export type Anchor = { hash: string };
 
@@ -39,12 +39,21 @@ function parseRef(ref: string): Anchor {
 
 export const parseHashRef = parseRef;
 
-export function parseText(edit: string): string[] {
-  if (typeof edit !== "string") {
-    throw new Error(NEW_CONTENT_NOT_STRING_MSG);
+export function parseText(edit: string[], warnings?: string[]): string[] {
+  if (!Array.isArray(edit) || edit.some((line) => typeof line !== "string")) {
+    throw new Error(NEW_CONTENT_NOT_ARRAY_MSG);
   }
-  const normalized = edit.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-  if (normalized === "") return [];
-  if (/^\n+$/.test(normalized)) return new Array(normalized.length).fill("");
-  return normalized.split("\n");
+  const out: string[] = [];
+  let split = false;
+  for (const line of edit) {
+    const normalized = line.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    if (normalized !== line) split = true;
+    out.push(...normalized.split("\n"));
+  }
+  if (split) {
+    warnings?.push(
+      "[E_BAD_SHAPE] Autocorrected: split replacement_lines element(s) containing embedded newlines into separate lines.",
+    );
+  }
+  return out;
 }

package/src/hashline/resolve.ts

@@ -1,7 +1,7 @@
 import { abortIf, rejectUnknownFields, firstNonEmptyIndex, lastNonEmptyIndex, clipLine } from "../utils";
 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, MAX_RANGE_STALE_LINES } from "../constants";
+import { NEW_CONTENT_NOT_ARRAY_MSG, MAX_RANGE_STALE_LINES } from "../constants";
 
 export type RAnchor = {
 	line: number;
@@ -39,7 +39,7 @@ export interface NEdit {
 }
 
 export type HTEdit = {
-  replacement_text: string;
+  replacement_lines: string[];
   remove_from: string;
   remove_to: string;
 };
@@ -133,19 +133,11 @@ export function fmtMismatchWithHashes(
   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"]);
+const ITEM_KS = new Set(["replacement_lines", "remove_from", "remove_to"]);
 
 function assertItem(edit: Record<string, unknown>): void {
-  rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { replacement_text, remove_from, remove_to }.");
+  rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { replacement_lines, remove_from, remove_to }.");
 
   if ("remove_from" in edit && typeof edit.remove_from !== "string") {
     throw new Error(
@@ -157,11 +149,11 @@ function assertItem(edit: Record<string, unknown>): void {
       `[E_BAD_SHAPE] Field "remove_to" must be an anchor string (3-char hash).`,
     );
   }
-  if (!("replacement_text" in edit)) {
-    throw new Error(`[E_BAD_SHAPE] The edit requires a "replacement_text" field. Provide the replacement text (use "" to delete).`);
+  if (!("replacement_lines" in edit)) {
+    throw new Error(`[E_BAD_SHAPE] The edit requires a "replacement_lines" field. Provide the replacement lines as an array of strings (use [] to delete).`);
   }
-  if (typeof edit.replacement_text !== "string") {
-    throw new Error(NEW_CONTENT_NOT_STRING_MSG);
+  if (!Array.isArray(edit.replacement_lines) || edit.replacement_lines.some((line) => typeof line !== "string")) {
+    throw new Error(NEW_CONTENT_NOT_ARRAY_MSG);
   }
   if (typeof edit.remove_from !== "string" || typeof edit.remove_to !== "string") {
     throw new Error(
@@ -175,7 +167,7 @@ const ANCHOR_ROW_RE = new RegExp(`^([+-]?)(${HASH_CLASS})│`);
 export function resEdit(edit: HTEdit, warnings?: string[]): HEdit {
   assertItem(edit as Record<string, unknown>);
 
-  const replaceLines = parseText(edit.replacement_text);
+  const replaceLines = parseText(edit.replacement_lines, warnings);
   const bounds = [edit.remove_from, edit.remove_to].map((ref) => {
     const trimmed = ref.trim();
     const match = trimmed.match(ANCHOR_ROW_RE);
@@ -225,7 +217,7 @@ export function stripBarePrefixes(
 	});
 	if (stripped.length === 0) return edit;
 	const locations = stripped
-		.map((s) => `replacement_text line ${s.lineIndex + 1}`)
+		.map((s) => `replacement_lines line ${s.lineIndex + 1}`)
 		.join(", ");
 	const matchedCount = stripped.filter((s) => s.matched).length;
 	const evidence =
@@ -261,7 +253,7 @@ export function stripDiffPrefixes(
 		return line;
 	});
 	if (stripped.length === 0) return edit;
-	const locations = stripped.map((i) => `replacement_text line ${i + 1}`).join(", ");
+	const locations = stripped.map((i) => `replacement_lines line ${i + 1}`).join(", ");
 	warnings.push(
 		`[E_INVALID_PATCH] Autocorrected: stripped diff-preview marker copied from the diff preview in ${locations}.`
 	);

package/src/read.ts

@@ -9,13 +9,11 @@ import {
 import { Type } from "typebox";
 import { MAX_READ_LINE_BYTES } from "./constants";
 import { loadFileKindAndText } from "./file-kind";
-import { readNormFile } from "./file-reader";
+import { readNormFile, safeSnapId } from "./file-reader";
 import { lineHashes, fmtRegion, HASH_SEP, MAX_HASH_LINES } from "./hashline";
 import { toCwd } from "./paths";
-import { abortIf, isRec, normalizeFilePath, visLines } from "./utils";
-import { fileSnap } from "./file-reader";
-import { loadHashStore } from "./hash-store";
-import { recordServed } from "./served";
+import { abortIf, makePrepareArguments, visLines } from "./utils";
+import { recordServedSafe } from "./served";
 import { loadP, loadGuide } from "./prompts";
 import { valAccess } from "./validation";
 
@@ -167,12 +165,7 @@ export function regRead(pi: ExtensionAPI): void {
 		description: R_DESC,
 		promptSnippet: R_SNIPPET,
 		promptGuidelines: readGuide(),
-		prepareArguments: (args: unknown) => {
-			if (!isRec(args)) return args as any;
-			const record = { ...args };
-			normalizeFilePath(record);
-			return record;
-		},
+		prepareArguments: makePrepareArguments(),
 		parameters: Type.Object({
 			path: Type.String({
 				description: "Path to the file to read (relative or absolute)",
@@ -223,18 +216,8 @@ export function regRead(pi: ExtensionAPI): void {
 				fileHashes,
 				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;
-			} catch (error) {
-				console.error("Failed to compute snapshot for read:", error);
-			}
+			await recordServedSafe(resolvedPath, preview.servedHashes, "read");
+			const snapshotId = await safeSnapId(absolutePath, "read");
 			const previewText =
 				hadUtf8DecodeErrors
 					? `${preview.text}\n\n[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]`

package/src/replace-render.ts

@@ -35,7 +35,8 @@ export function getPreviewInput(
 	if (
 		typeof normalized.remove_from !== "string" ||
 		typeof normalized.remove_to !== "string" ||
-		typeof normalized.replacement_text !== "string"
+		!Array.isArray(normalized.replacement_lines) ||
+		normalized.replacement_lines.some((line) => typeof line !== "string")
 	) {
 		return null;
 	}
@@ -44,7 +45,7 @@ export function getPreviewInput(
 		path: normalized.path,
 		remove_from: normalized.remove_from,
 		remove_to: normalized.remove_to,
-		replacement_text: normalized.replacement_text,
+		replacement_lines: normalized.replacement_lines,
 	};
 	return request;
 }

package/src/replace-response.ts

@@ -101,7 +101,7 @@ export function buildNoop(input: NoopInput): TResult {
 		? `Replacement for ${noopEdit.loc} is identical to current content:\n  ${noopEdit.loc}: ${clipLine(noopEdit.currentContent)}`
 		: "The edit produced identical content.";
 
-	const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}`;
+	const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}${warnBlock(warnings)}`;
 
 	const metrics = buildMetrics({
 		classification: "noop",

package/src/replace-undo.ts

@@ -8,7 +8,7 @@ import { contentChecksum } from "./hashline/hasher";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { toCwd } from "./paths";
 import { toLF, stripBOM, genDiff, restoreEndings, type LineEnding } from "./replace-diff";
-import { cntDiff, splitLines, errCode, isRec, normalizeFilePath } from "./utils";
+import { cntDiff, splitLines, errCode, makePrepareArguments } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { buildMetrics } from "./replace-response";
 import { changedRange, lineHashes } from "./hashline";
@@ -92,12 +92,7 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
     description: loadP("../prompts/undo-last-replace.md"),
     promptSnippet: loadP("../prompts/undo-last-replace-snippet.md"),
     promptGuidelines: loadGuide("../prompts/undo-last-replace-guidelines.md"),
-    prepareArguments: (args: unknown) => {
-      if (!isRec(args)) return args as any;
-      const record = { ...args };
-      normalizeFilePath(record);
-      return record;
-    },
+    prepareArguments: makePrepareArguments(),
     parameters: Type.Object({
       path: Type.String({
         description: "Path to the file to undo",

package/src/replace.ts

@@ -11,9 +11,9 @@ import {
   restoreEndings,
   type LineEnding,
 } from "./replace-diff";
-import { readNormFile } from "./file-reader";
+import { readNormFile, safeSnapId } from "./file-reader";
 import { normReq } from "./replace-normalize";
-import { isRec, rejectUnknownFields, abortIf, normalizeFilePath } from "./utils";
+import { isRec, rejectUnknownFields, abortIf, makePrepareArguments } from "./utils";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { applyEdit,
   lineHashes,
@@ -26,7 +26,6 @@ import { applyEdit,
   type NEdit,
 } from "./hashline";
 import { toCwd } from "./paths";
-import { fileSnap } from "./file-reader";
 import {
   buildChanged,
   buildNoop,
@@ -47,12 +46,18 @@ 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";
+import { getServed, recordServedSafe, recordServedDiffSafe } from "./served";
 
-const replacementTextSchema = Type.String({
-  description:
-    "Replacement text as a single string with \\n line separators; every \\n separates lines, so a trailing \\n adds a final empty line. Mirror the removed lines exactly, blank lines included. A replacement that is only blank lines is written as one \\n per blank line. Use \"\" to delete the range."
-});
+const replacementLinesSchema = Type.Array(
+  Type.String({
+    description:
+      "One replacement line. Each element is exactly one line; do not embed \\n inside an element — use separate elements.",
+  }),
+  {
+    description:
+      "Replacement lines as an array of strings, one element per line. Use [] to delete the range."
+  }
+);
 
 const removeFromSchema = Type.String({
   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)",
@@ -67,7 +72,7 @@ export const editToolSchema = Type.Object(
     path: Type.Optional(Type.String({ description: "Path to edit. Required — always provide it explicitly; it is only auto-resolved from the anchors as a fallback when omitted by mistake." })),
     remove_from: removeFromSchema,
     remove_to: removeToSchema,
-    replacement_text: replacementTextSchema,
+    replacement_lines: replacementLinesSchema,
   },
   { additionalProperties: false },
 );
@@ -75,7 +80,7 @@ export type ReqParams = {
   path: string;
   remove_from: string;
   remove_to: string;
-  replacement_text: string;
+  replacement_lines: string[];
 };
 
 export type ReplaceDetails = {
@@ -105,7 +110,7 @@ interface PipelineResult {
 
 const PREVIEW_DEBOUNCE_MS = 150;
 
-const ROOT_KS = new Set(["path", "remove_from", "remove_to", "replacement_text"]);
+const ROOT_KS = new Set(["path", "remove_from", "remove_to", "replacement_lines"]);
 
 export function assertReq(
   request: unknown,
@@ -123,10 +128,11 @@ export function assertReq(
   if (
     typeof request.remove_from !== "string" ||
     typeof request.remove_to !== "string" ||
-    typeof request.replacement_text !== "string"
+    !Array.isArray(request.replacement_lines) ||
+    request.replacement_lines.some((line) => typeof line !== "string")
   ) {
     throw new Error(
-      '[E_BAD_SHAPE] Edit request requires "remove_from", "remove_to", and "replacement_text" at the top level.',
+      '[E_BAD_SHAPE] Edit request requires "remove_from", "remove_to", and "replacement_lines" at the top level. replacement_lines must be an array of strings, one element per line (use [] to delete).',
     );
   }
 }
@@ -225,7 +231,7 @@ export async function execPipeline(
     {
       remove_from: params.remove_from,
       remove_to: params.remove_to,
-      replacement_text: params.replacement_text,
+      replacement_lines: params.replacement_lines,
     },
     editWarnings,
   );
@@ -249,17 +255,9 @@ export async function execPipeline(
   } 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);
-        }
+        await recordServedSafe(absolutePath, error.rangeHashes, "range-stale feedback");
       } 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);
-        }
+        await recordServedSafe(absolutePath, error.feedbackHashes, "anchor-mismatch feedback");
       }
     }
     throw error;
@@ -361,12 +359,7 @@ export function buildToolDef(): ToolDef {
     parameters,
     promptSnippet: E_SNIPPET,
     promptGuidelines: E_GUIDE,
-    prepareArguments: (args: unknown) => {
-      if (!isRec(args)) return args as any;
-      const record = { ...args };
-      normalizeFilePath(record);
-      return record;
-    },
+    prepareArguments: makePrepareArguments(),
     renderShell: "default",
     renderCall(args, theme, context) {
       const previewInput = getPreviewInput(args);
@@ -512,12 +505,7 @@ export function buildToolDef(): ToolDef {
 
         const editsAttempted = 1;
         if (originalNormalized === result) {
-          let noopSnapshotId: string | undefined;
-          try {
-            noopSnapshotId = (await fileSnap(absolutePath)).snapshotId;
-          } catch (error) {
-            console.error("Failed to compute snapshot for noop edit:", error);
-          }
+          const noopSnapshotId = await safeSnapId(absolutePath, "noop edit");
           return buildNoop({
             path,
             noopEdit,
@@ -561,12 +549,7 @@ export function buildToolDef(): ToolDef {
           await undo.restore();
           throw error;
         }
-        let updatedSnapshotId: string | undefined;
-        try {
-          updatedSnapshotId = (await fileSnap(absolutePath)).snapshotId;
-        } catch (error) {
-          console.error("Failed to compute post-edit snapshot:", error);
-        }
+        const updatedSnapshotId = await safeSnapId(absolutePath, "post-edit");
 
         const editMeta: RMeta = {
           editsAttempted,
@@ -589,12 +572,7 @@ export function buildToolDef(): ToolDef {
         };
         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);
-          }
+          await recordServedDiffSafe(mutationTargetPath, changed.details.diff, "post-edit diff");
         }
         return changed;
       });

package/src/served.ts

@@ -1,5 +1,4 @@
-import type { HashStore } from "./hash-store";
-import { parseHashList } from "./hash-store";
+import { loadHashStore, parseHashList, type HashStore } from "./hash-store";
 import { HASH_CLASS } from "./hashline/alphabet";
 
 const SERVED_DIFF_ROW_RE = new RegExp(`^[+ ](${HASH_CLASS})│`);
@@ -42,3 +41,26 @@ export function recordServedDiff(store: HashStore, path: string, diff: string):
 export function clearServed(store: HashStore, path: string): void {
   store.stmts.servedDelete(path);
 }
+
+export async function recordServedSafe(
+  path: string,
+  hashes: string[],
+  context: string,
+): Promise<void> {
+  if (hashes.length === 0) return;
+  try {
+    const store = await loadHashStore();
+    recordServed(store, path, hashes);
+  } catch (error) {
+    console.error(`Failed to record served state (${context}):`, error);
+  }
+}
+
+export async function recordServedDiffSafe(
+  path: string,
+  diff: string,
+  context: string,
+): Promise<void> {
+  if (!diff) return;
+  await recordServedSafe(path, servedHashesFromDiff(diff), context);
+}

package/src/utils.ts

@@ -9,6 +9,15 @@ export function normalizeFilePath(record: Record<string, unknown>): void {
   }
 }
 
+export function makePrepareArguments(): (args: unknown) => any {
+  return (args) => {
+    if (!isRec(args)) return args;
+    const record = { ...args };
+    normalizeFilePath(record);
+    return record;
+  };
+}
+
 export function splitLines(text: string): string[] {
   if (text.length === 0) return [""];
   const lines = text.split("\n");