pi-hashline-edit-pro 0.12.3 → 0.13.1

package/README.md

@@ -66,18 +66,18 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 {
   "path": "src/main.ts",
   "changes": [
-    { "hash_range_incl": ["ve7", "ve7"], "content_lines": ["  console.log('hashline');"] }
+    { "hash_range_inclusive": ["ve7", "ve7"], "content_lines": ["  console.log('hashline');"] }
   ]
 }
 ```
 
 | Field | Description |
 | --- | --- |
-| `hash_range_incl` | Inclusive line range `[start_hash, end_hash]` (required). |
+| `hash_range_inclusive` | Inclusive line range `[start_hash, end_hash]` (required). |
 | `content_lines` | Literal replacement content, one string per line (use `[]` to delete the range). |
 
 - **Request structure validation.** The request envelope (`path`, `changes`) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_REF]`.
-- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{hash_range_incl: ["<START>", "<END>"], content_lines: [...]}`.
+- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}`.
 - **Batched atomicity.** All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so the hashes from a single `read` call remain valid across all edits in the batch.
 
 ### Chained edits
@@ -101,7 +101,7 @@ The post-edit diff (with `+`/`-` markers) is exposed to the host UI via `details
 
 ## Design Decisions
 
-- **Stale anchors fail (per-line).** A hash mismatch means that specific line's content changed since the last `read`; the error tells the model to call `read()` to get fresh anchors, then copy the 3-character HASH of the start and end of the range being replaced into `hash_range_incl` of the next replace call. Because staleness is per-line, editing or appending lines does **not** invalidate anchors for lines whose content is unchanged — anchors for untouched regions stay valid across edits to other regions.
+- **Stale anchors fail (per-line).** A hash mismatch means that specific line's content changed since the last `read`; the error tells the model to call `read()` to get fresh anchors, then copy the 3-character HASH of the start and end of the range being replaced into `hash_range_inclusive` of the next replace call. Because staleness is per-line, editing or appending lines does **not** invalidate anchors for lines whose content is unchanged — anchors for untouched regions stay valid across edits to other regions.
 - **No fallback relocation.** Mismatched anchors are never silently relocated to a "close enough" line. This trades convenience for correctness.
 - **Strict patch content.** If `content_lines` contains `+HASH│` display prefixes (or `-N   ` numbered deletion rows), the edit is rejected with `[E_INVALID_PATCH]`. This narrowly guards against pasting the tool's own diff-preview rows back as content; standard unified-diff lines (`+x`, `-x`, ` x`, `@@ … @@`) are **not** rejected — they are written literally, since literal content must never be silently altered. Bare `HASH│` content (the first 4 chars of a `content_lines` entry looking like 3 base64 chars + `│`) is rejected with `[E_BARE_HASH_PREFIX]`. When the suspect's prefix happens to match a real file-line anchor, the error message flags that as strong evidence the model copied an anchor from the read output.
 - **Atomic writes.** Files are written via temp-file-then-rename to avoid corruption from interrupted writes. Symlink chains are resolved so the target file is updated without replacing the symlink. Hard-linked files are updated in place to preserve the shared inode. File permissions are preserved across atomic renames.

package/index.ts

@@ -4,7 +4,7 @@ import { join, isAbsolute } from "path";
 import { lineHashes, initHasher, fmtRegion } from "./src/hashline";
 import { regReplace } from "./src/replace";
 import { regRead, formatPaginationHint } from "./src/read";
-import { toLF } from "./src/replace-diff";
+import { toLF, stripBOM } from "./src/replace-diff";
 import { visLines } from "./src/utils";
 import { AUTO_READ_MAX } from "./src/constants";
 
@@ -12,10 +12,15 @@ export default function (pi: ExtensionAPI): void {
   regRead(pi);
   regReplace(pi);
 
+  const debugValue = process.env.PI_HASHLINE_DEBUG;
+
   pi.on("session_start", async (_event, ctx) => {
     const active = pi.getActiveTools();
     pi.setActiveTools(active.filter((t) => t !== "edit"));
     await initHasher();
+    if (debugValue === "1" || debugValue === "true") {
+      ctx.ui.notify("Hashline Edit mode active", "info");
+    }
   });
 
   const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;
@@ -40,8 +45,8 @@ export default function (pi: ExtensionAPI): void {
     try {
       const absolutePath = isAbsolute(filePath) ? filePath : join(ctx.cwd, filePath);
       const content = await readFile(absolutePath, "utf-8");
-
-      const normalized = toLF(content);
+      const { text: rawContent } = stripBOM(content);
+      const normalized = toLF(rawContent);
       const visibleLines = visLines(normalized);
 
       if (visibleLines.length === 0) return;
@@ -65,14 +70,9 @@ export default function (pi: ExtensionAPI): void {
           ],
         };
       }
-    } catch {
+    } catch (error) {
+      console.error("Auto-read after write failed:", error);
     }
   });
 
-  const debugValue = process.env.PI_HASHLINE_DEBUG;
-  if (debugValue === "1" || debugValue === "true") {
-    pi.on("session_start", async (_event, ctx) => {
-      ctx.ui.notify("Hashline Edit mode active", "info");
-    });
-  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.12.3",
+  "version": "0.13.1",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
   "repository": {

package/prompts/replace-guidelines.md

@@ -1,3 +1,4 @@
 - Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
 - After a successful `replace`, the response text is empty (warnings only). Call `read` to get fresh anchors for follow-up edits.
-- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_incl`, and retry.
+- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
+- `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.

package/prompts/replace.md

@@ -9,10 +9,10 @@ How to use:
 read({ path: "src/main.ts" })
 ```
 
-2. Copy the 3-character HASH (before `│`) into `hash_range_incl`:
+2. Copy the 3-character HASH (before `│`) into `hash_range_inclusive`:
 ```json
 { "path": "src/main.ts", "changes": [
-  { "hash_range_incl": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
+  { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
 ] }
 ```
 
@@ -21,14 +21,14 @@ Examples:
 1. Single line replace:
 ```json
 { "path": "src/main.ts", "changes": [
-  { "hash_range_incl": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
+  { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
 ] }
 ```
 
 2. Range replace (3 lines → 3 new lines):
 ```json
 { "path": "src/main.ts", "changes": [
-  { "hash_range_incl": ["ZPM", "VRW"], "content_lines": [
+  { "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
     "function greet(name) {",
     "  return `Hello, ${name}`;",
     "}"
@@ -39,8 +39,8 @@ Examples:
 3. Multiple regions in one call (delete two non-adjacent ranges):
 ```json
 { "path": "src/server.ts", "changes": [
-  { "hash_range_incl": ["aB3", "xY7"], "content_lines": [] },
-  { "hash_range_incl": ["MQX", "ZPM"], "content_lines": [] }
+  { "hash_range_inclusive": ["aB3", "xY7"], "content_lines": [] },
+  { "hash_range_inclusive": ["MQX", "ZPM"], "content_lines": [] }
 ] }
 ```
 
@@ -48,7 +48,7 @@ Examples:
 
 ```json
 { "path": "src/main.ts", "changes": [
-  { "hash_range_incl": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
+  { "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
 ] }
 ```
 
@@ -56,7 +56,7 @@ Examples:
 
 ```json
 { "path": "src/main.ts", "changes": [
-  { "hash_range_incl": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
+  { "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
 ] }
 ```
 
@@ -64,48 +64,69 @@ Examples:
 
 Wrong:
 ```json
-{ "hash_range_incl": ["F4T", "F4T"], "content_lines": ["F4T│import { x } from \"./x\";"] }
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["F4T│import { x } from \"./x\";"] }
 ```
 
 Right:
 ```json
-{ "hash_range_incl": ["F4T", "F4T"], "content_lines": ["import { x } from \"./x\";"] }
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["import { x } from \"./x\";"] }
 ```
 
-`hash_range_incl` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
+`hash_range_inclusive` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
 
-⚠️ Common mistake: `hash_range_incl` is only the 3-character HASH, not the full `HASH│content` line.
+⚠️ Common mistake: `hash_range_inclusive` is only the 3-character HASH, not the full `HASH│content` line.
 
 Wrong:
 ```json
-{ "hash_range_incl": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "content_lines": [...] }
+{ "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "content_lines": [...] }
 ```
 
 Right:
 ```json
-{ "hash_range_incl": ["F4T", "F4T"], "content_lines": [...] }
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": [...] }
 ```
 
 Rules:
-- `hash_range_incl` is a pair `[start, end]`. A single-line replace is `hash_range_incl: ["X", "X"]`.
+- `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
 - To delete a range, use `content_lines: []`.
-- `hash_range_incl` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
+- `hash_range_inclusive` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
 - `content_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix. A line that happens to start with `+` or `-` is written as-is; the only rejected form is the diff preview's `+HASH│…` row (see `[E_INVALID_PATCH]`).
 - Don't add `""` for spacing unless you actually want a new blank line.
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - All changes in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
 - If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
-- The `hash_range_incl` is inclusive — both anchors and every line between them are replaced. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
+- The `hash_range_inclusive` is inclusive — the entire span from the first anchor through the second anchor is deleted and replaced with `content_lines`. The old lines in that span are gone. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
 On success, the response text is empty (or contains only warnings if present). Call `read` to get fresh anchors for follow-up edits.
 
+⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
+
+Wrong: To replace lines 2-3 in this function:
+```
+function greet() {
+  const x = 1;
+  return x;
+}
+```
+A model might write:
+```json
+{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;", "}"] }
+```
+This produces `function greet() {\n  const y = 2;\n  return y;\n}\n}` — the `}` appears twice because it was already on line 4 (outside the range) AND in `content_lines`.
+
+Right: Only include the new lines that belong in the range:
+```json
+{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;"] }
+```
+The `}` on line 4 is outside the range and stays in place.
+
 Error recovery:
-- `[E_STALE_ANCHOR]` — the anchored line's content changed since the last read. Call `read` to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into `hash_range_incl` and retry. (Staleness is per-line: editing or appending lines does not invalidate anchors for lines whose content is unchanged, so anchors for untouched regions stay valid across edits.)
+- `[E_STALE_ANCHOR]` — the anchored line's content changed since the last read. Call `read` to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into `hash_range_inclusive` and retry. (Staleness is per-line: editing or appending lines does not invalidate anchors for lines whose content is unchanged, so anchors for untouched regions stay valid across edits.)
 - `[E_BAD_REF]` — malformed HASH. Re-read and try again.
 - `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
 - `[E_BAD_SHAPE]` — malformed request or change item (missing fields, wrong types, unknown fields).
-- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_incl, content_lines}` instead.
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_inclusive, content_lines}` instead.
 - `[E_EDIT_CONFLICT]` — two changes overlap on the same line range. Make changes non-overlapping.
 - `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
-- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_incl` uses hashes, `content_lines` does not.
+- `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.

package/src/hashline/apply.ts

@@ -76,8 +76,8 @@ function resToSpan(
 ): RESpan | null {
   const { fileLines, lineStarts, hasTerminalNewline } = lineIndex;
 
-  const startLine = edit.hash_range_incl[0].line;
-  const endLine = edit.hash_range_incl[1].line;
+  const startLine = edit.hash_range_inclusive[0].line;
+  const endLine = edit.hash_range_inclusive[1].line;
   const originalLines = fileLines.slice(startLine - 1, endLine);
   if (
     originalLines.length === edit.content_lines.length &&
@@ -87,7 +87,7 @@ function resToSpan(
   ) {
     noopEdits.push({
       editIndex: index,
-      loc: edit.hash_range_incl[0].hash,
+      loc: edit.hash_range_inclusive[0].hash,
       currentContent: originalLines.join("\n"),
     });
     return null;
@@ -228,8 +228,8 @@ function fmtBoundaryWarning(params: {
 }): string {
 	const header =
 		params.kind === "trailing"
-			? "Boundary duplication (trailing): the last replacement line duplicated the next line. Delete the duplicate."
-			: "Boundary duplication (leading): the first replacement line duplicated the previous line. Delete the duplicate.";
+			? "Boundary duplication (trailing): the last replacement line duplicated the next line. This happens when `content_lines` includes a line that was already outside the replaced range. Delete the duplicate — the original line outside the range is still there."
+			: "Boundary duplication (leading): the first replacement line duplicated the previous line. This happens when `content_lines` includes a line that was already outside the replaced range. Delete the duplicate — the original line outside the range is still there.";
 
 	// Locate the adjacent duplicated pair (two identical neighboring lines). The
 	// occurrence-based matchIndex usually lands inside the pair; when a file has

package/src/hashline/hash.ts

@@ -98,8 +98,5 @@ export function lineHashes(content: string): string[] {
 	return hashes;
 }
 
-export function lineHash(idx: number, line: string): string {
-	return h2s(xxh32(canon(line)));
-}
 
 export { ALPH_RE };

package/src/hashline/index.ts

@@ -8,7 +8,6 @@ export {
 	DIFF_MINUS_RE,
 	HL_BARE_PREFIX_RE,
 	lineHashes,
-	lineHash,
 	initHasher,
 } from "./hash";
 

package/src/hashline/parse.ts

@@ -20,7 +20,7 @@ function diagRef(ref: string): string {
 	}
 
 	if (trimmed.includes("│")) {
-		return `[E_BAD_REF] Invalid anchor "${trimmed}". hash_range_incl must contain the 3-char hash only — remove everything from "│" onward.`;
+		return `[E_BAD_REF] Invalid anchor "${trimmed}". hash_range_inclusive must contain the 3-char hash only — remove everything from "│" onward.`;
 	}
 
 	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a 3-char base64 anchor (e.g. "aB3").`;

package/src/hashline/resolve.ts

@@ -9,9 +9,9 @@ export type RAnchor = {
 	hashMatched: boolean;
 };
 
-export type HEdit = { hash_range_incl: [Anchor, Anchor]; content_lines: string[] };
+export type HEdit = { hash_range_inclusive: [Anchor, Anchor]; content_lines: string[] };
 export type RHEdit = {
-  hash_range_incl: [RAnchor, RAnchor];
+  hash_range_inclusive: [RAnchor, RAnchor];
   content_lines: string[];
 };
 
@@ -37,7 +37,7 @@ export interface NEdit {
 }
 
 export type HTEdit = {
-  hash_range_incl: [string, string];
+  hash_range_inclusive: [string, string];
   content_lines: string[];
 };
 
@@ -90,13 +90,13 @@ export function fmtMismatch(
 	const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
 	if (notFound.length > 0) {
 		out.push(
-			`[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_incl of your next replace call.`
+			`[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_inclusive of your next replace call.`
 		);
 	}
 	if (ambiguous.length > 0) {
 		if (out.length > 0) out.push("");
 		out.push(
-			`[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_incl of your next replace call.`
+			`[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_inclusive of your next replace call.`
 		);
 		for (const m of ambiguous) {
 			const sample = (m.candidates ?? []).slice(0, 5);
@@ -119,7 +119,7 @@ export function fmtMismatch(
 	return out.join("\n");
 }
 
-const ITEM_KS = new Set(["hash_range_incl", "content_lines"]);
+const ITEM_KS = new Set(["hash_range_inclusive", "content_lines"]);
 
 function isStrArr(value: unknown): value is string[] {
 	return (
@@ -136,11 +136,11 @@ function isStrPair(value: unknown): value is [string, string] {
 }
 
 function assertItem(edit: Record<string, unknown>, index: number): void {
-  rejectUnknownFields(edit, ITEM_KS, `Edit ${index}`, "Each edit takes only { hash_range_incl, content_lines }.");
+  rejectUnknownFields(edit, ITEM_KS, `Edit ${index}`, "Each edit takes only { hash_range_inclusive, content_lines }.");
 
-  if ("hash_range_incl" in edit && !isStrPair(edit.hash_range_incl)) {
+  if ("hash_range_inclusive" in edit && !isStrPair(edit.hash_range_inclusive)) {
     throw new Error(
-      `[E_BAD_SHAPE] Edit ${index} field "hash_range_incl" must be a pair of anchor strings [start, end].`,
+      `[E_BAD_SHAPE] Edit ${index} field "hash_range_inclusive" must be a pair of anchor strings [start, end].`,
     );
   }
   if (!("content_lines" in edit)) {
@@ -149,9 +149,9 @@ function assertItem(edit: Record<string, unknown>, index: number): void {
   if ("content_lines" in edit && !isStrArr(edit.content_lines)) {
     throw new Error(`[E_BAD_SHAPE] Edit ${index} field "content_lines" must be a string array.`);
   }
-  if (!isStrPair(edit.hash_range_incl)) {
+  if (!isStrPair(edit.hash_range_inclusive)) {
     throw new Error(
-      `[E_BAD_SHAPE] Edit ${index} requires an "hash_range_incl" pair of anchor strings [start, end].`,
+      `[E_BAD_SHAPE] Edit ${index} requires an "hash_range_inclusive" pair of anchor strings [start, end].`,
     );
   }
 }
@@ -163,7 +163,7 @@ export function resEdits(edits: HTEdit[]): HEdit[] {
 
     const replaceLines = parseText(edit.content_lines);
     result.push({
-      hash_range_incl: [parseHashRef(edit.hash_range_incl[0]), parseHashRef(edit.hash_range_incl[1])],
+      hash_range_inclusive: [parseHashRef(edit.hash_range_inclusive[0]), parseHashRef(edit.hash_range_inclusive[1])],
       content_lines: replaceLines,
     });
   }
@@ -214,14 +214,39 @@ export function assertNoBarePrefix(
       : `${matchedCount} match file line hashes — strong evidence the prefix was copied from read output.`;
 
   throw new Error(
-    `[E_BARE_HASH_PREFIX] ${suspects.length} edit line(s) start with a hash-like prefix (${locations}). Example: ${JSON.stringify(exampleLine)}. ${linesHint} Remove the "HASH│" prefix from each affected content_lines entry; keep only the literal line content that appears after "│" in read output. Remember: hash_range_incl uses hash anchors, content_lines uses file content only.`
+    `[E_BARE_HASH_PREFIX] ${suspects.length} edit line(s) start with a hash-like prefix (${locations}). Example: ${JSON.stringify(exampleLine)}. ${linesHint} Remove the "HASH│" prefix from each affected content_lines entry; keep only the literal line content that appears after "│" in read output. Remember: hash_range_inclusive uses hash anchors, content_lines uses file content only.`
   );
 }
 
 export function descEdit(edit: RHEdit): string {
-	return `replace ${edit.hash_range_incl[0].hash}-${edit.hash_range_incl[1].hash}`;
+	return `replace ${edit.hash_range_inclusive[0].hash}-${edit.hash_range_inclusive[1].hash}`;
 }
 
+function checkBoundaryDup(
+  adjacentLine: string | undefined,
+  replacementEdge: string | undefined,
+  kind: "trailing" | "leading",
+  survivingLineIndex: number,
+  fileLines: string[],
+  editIndex: number,
+): BDupWarn | null {
+  if (
+    adjacentLine === undefined ||
+    replacementEdge === undefined ||
+    replacementEdge.length === 0 ||
+    replacementEdge !== adjacentLine
+  ) return null;
+  return {
+    kind,
+    survivingLineContent: adjacentLine,
+    survivingLineIndex,
+    occurrence: fileLines.slice(0, survivingLineIndex).filter((l) => l === adjacentLine).length,
+    replacementLineContent: replacementEdge,
+    editIndex,
+  };
+}
+
+
 export function valEdits(
   edits: HEdit[],
   fileLines: string[],
@@ -245,53 +270,27 @@ export function valEdits(
 
   for (const edit of edits) {
     abortIf(signal);
-    const startResolved = tryResolve(edit.hash_range_incl[0]);
-    const endResolved = tryResolve(edit.hash_range_incl[1]);
+    const startResolved = tryResolve(edit.hash_range_inclusive[0]);
+    const endResolved = tryResolve(edit.hash_range_inclusive[1]);
     if (!startResolved || !endResolved) {
       continue;
     }
     if (startResolved.line > endResolved.line) {
       throw new Error(
-        `[E_BAD_OP] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.hash_range_incl[0].hash} and ${edit.hash_range_incl[1].hash}).`,
+        `[E_BAD_OP] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.hash_range_inclusive[0].hash} and ${edit.hash_range_inclusive[1].hash}).`,
       );
     }
     const endLine = endResolved.line;
     const nextLine = fileLines[endLine];
     const replacementLastLine = edit.content_lines.at(-1);
-    if (
-      nextLine !== undefined &&
-      replacementLastLine !== undefined &&
-      replacementLastLine.length > 0 &&
-      replacementLastLine === nextLine
-    ) {
-      boundaryWarnings.push({
-        kind: "trailing",
-        survivingLineContent: nextLine,
-        survivingLineIndex: endLine,
-        occurrence: fileLines.slice(0, endLine).filter(l => l === nextLine).length,
-        replacementLineContent: replacementLastLine,
-        editIndex: resolved.length,
-      });
-    }
+    const trailing = checkBoundaryDup(nextLine, replacementLastLine, "trailing", endLine, fileLines, resolved.length);
+    if (trailing) boundaryWarnings.push(trailing);
     const prevLine = fileLines[startResolved.line - 2];
     const replacementFirstLine = edit.content_lines[0];
-    if (
-      prevLine !== undefined &&
-      replacementFirstLine !== undefined &&
-      replacementFirstLine.length > 0 &&
-      replacementFirstLine === prevLine
-    ) {
-      boundaryWarnings.push({
-        kind: "leading",
-        survivingLineContent: prevLine,
-        survivingLineIndex: startResolved.line - 2,
-        occurrence: fileLines.slice(0, startResolved.line - 2).filter(l => l === prevLine).length,
-        replacementLineContent: replacementFirstLine,
-        editIndex: resolved.length,
-      });
-    }
+    const leading = checkBoundaryDup(prevLine, replacementFirstLine, "leading", startResolved.line - 2, fileLines, resolved.length);
+    if (leading) boundaryWarnings.push(leading);
     resolved.push({
-      hash_range_incl: [startResolved, endResolved],
+      hash_range_inclusive: [startResolved, endResolved],
       content_lines: edit.content_lines,
     });
   }

package/src/replace-normalize.ts

@@ -1,46 +1,12 @@
 import { isRec, has } from "./utils";
 
-function coerceChangesArray(changes: unknown): unknown {
-  if (typeof changes !== "string") {
-    return changes;
-  }
+function tryParseJSON<T>(value: unknown, guard: (v: unknown) => v is T): T | undefined {
+  if (typeof value !== "string") return undefined;
   try {
-    const parsed: unknown = JSON.parse(changes);
-    return Array.isArray(parsed) ? parsed : changes;
-  } catch {
-    return changes;
-  }
-}
-
-function coerceContentLines(changes: unknown): unknown {
-  if (!Array.isArray(changes)) return changes;
-  return changes.map((change: unknown) => {
-    if (!isRec(change)) return change;
-    if (typeof change.content_lines !== "string") return change;
-    try {
-      const parsed: unknown = JSON.parse(change.content_lines);
-      if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
-        return { ...change, content_lines: parsed };
-      }
-    } catch {
-      // not valid JSON, leave as-is for downstream validation
-    }
-    return change;
-  });
-}
-
-function coerceChangeItems(changes: unknown): unknown {
-  if (!Array.isArray(changes)) return changes;
-  return changes.map((item: unknown) => {
-    if (typeof item !== "string") return item;
-    try {
-      const parsed: unknown = JSON.parse(item);
-      if (isRec(parsed)) return parsed;
-    } catch {
-      // not valid JSON, leave as-is for downstream validation
-    }
-    return item;
-  });
+    const parsed: unknown = JSON.parse(value);
+    if (guard(parsed)) return parsed;
+  } catch {}
+  return undefined;
 }
 
 export function normReq(input: unknown): unknown {
@@ -59,14 +25,33 @@ export function normReq(input: unknown): unknown {
   const hasEditsField = has(record, "edits");
 
   if (hasChangesField) {
-    record.changes = coerceChangesArray(record.changes);
-    record.changes = coerceChangeItems(record.changes);
-    record.changes = coerceContentLines(record.changes);
+    const raw = tryParseJSON(record.changes, Array.isArray) ?? record.changes;
+    if (Array.isArray(raw)) {
+      record.changes = raw
+        .map((item: unknown) => tryParseJSON(item, isRec) ?? item)
+        .map((change: unknown) => {
+          if (!isRec(change)) return change;
+          if (typeof change.content_lines !== "string") return change;
+          const parsed = tryParseJSON(change.content_lines, (v): v is string[] =>
+            Array.isArray(v) && v.every((i) => typeof i === "string"),
+          );
+          return parsed ? { ...change, content_lines: parsed } : change;
+        });
+    }
   } else if (hasEditsField) {
-    // Accept "edits" as an alias for "changes" for backward compatibility
-    record.changes = coerceChangesArray(record.edits);
-    record.changes = coerceChangeItems(record.changes);
-    record.changes = coerceContentLines(record.changes);
+    const raw = tryParseJSON(record.edits, Array.isArray) ?? record.edits;
+    if (Array.isArray(raw)) {
+      record.changes = raw
+        .map((item: unknown) => tryParseJSON(item, isRec) ?? item)
+        .map((change: unknown) => {
+          if (!isRec(change)) return change;
+          if (typeof change.content_lines !== "string") return change;
+          const parsed = tryParseJSON(change.content_lines, (v): v is string[] =>
+            Array.isArray(v) && v.every((i) => typeof i === "string"),
+          );
+          return parsed ? { ...change, content_lines: parsed } : change;
+        });
+    }
     delete record.edits;
   }
 

package/src/replace.ts

@@ -59,7 +59,7 @@ const hashRangeInclSchema = Type.Array(
 
 const changeItemSchema = Type.Object(
   {
-    hash_range_incl: hashRangeInclSchema,
+    hash_range_inclusive: hashRangeInclSchema,
     content_lines: contentLinesSchema,
   },
   { additionalProperties: false },
@@ -86,6 +86,21 @@ export type ReplaceDetails = {
 	metrics?: RMetrics;
 };
 
+interface PipelineResult {
+  path: string;
+  toolEdits: HTEdit[];
+  originalNormalized: string;
+  result: string;
+  bom: string;
+  originalEnding: "\r\n" | "\n";
+  hadUtf8DecodeErrors: boolean;
+  warnings: string[];
+  noopEdits?: { editIndex: number; loc: string; currentContent: string }[];
+  firstChangedLine?: number;
+  lastChangedLine?: number;
+  originalHashes?: string[];
+}
+
 const E_DESC = loadP("../prompts/replace.md");
 const E_SNIPPET = loadP("../prompts/replace-snippet.md");
 const E_GUIDE = loadGuide("../prompts/replace-guidelines.md");
@@ -101,7 +116,7 @@ export function assertReq(
   for (const legacyKey of ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines"]) {
     if (has(request, legacyKey)) {
       throw new Error(
-        `[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {hash_range_incl: ["<START>", "<END>"], content_lines: [...]}.`
+        `[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}.`
       );
     }
   }
@@ -113,7 +128,7 @@ export function assertReq(
   }
 
   if (!Array.isArray(request.changes)) {
-    throw new Error('[E_BAD_SHAPE] Edit request requires a "changes" array. Each change is { hash_range_incl: ["<START>", "<END>"], content_lines: [...] }.');
+    throw new Error('[E_BAD_SHAPE] Edit request requires a "changes" array. Each change is { hash_range_inclusive: ["<START>", "<END>"], content_lines: [...] }.');
   }
 }
 
@@ -122,20 +137,7 @@ async function execPipeline(
   cwd: string,
   accessMode: number,
   signal?: AbortSignal,
-): Promise<{
-  path: string;
-  toolEdits: HTEdit[];
-  originalNormalized: string;
-  result: string;
-  bom: string;
-  originalEnding: "\r\n" | "\n";
-  hadUtf8DecodeErrors: boolean;
-  warnings: string[];
-  noopEdits?: { editIndex: number; loc: string; currentContent: string }[];
-  firstChangedLine?: number;
-  lastChangedLine?: number;
-  originalHashes?: string[];
-}> {
+): Promise<PipelineResult> {
 
   const path = params.path;
   const toolEdits = Array.isArray(params.changes)
@@ -205,6 +207,21 @@ type ToolDef = ToolDefinition<
 	ReplaceDetails,
 	RRState
 > & { renderShell?: "default" | "self" };
+function reuseText(context: any, content: string): Text {
+  const t = context.lastComponent instanceof Text
+    ? context.lastComponent
+    : new Text("", 0, 0);
+  t.setText(content);
+  return t;
+}
+
+function reuseMarkdown(context: any, content: string, theme: any): Markdown {
+  const m = context.lastComponent instanceof Markdown
+    ? context.lastComponent
+    : new Markdown("", 0, 0, mkMdTheme(theme));
+  m.setText(content);
+  return m;
+}
 
 const toolDef: ToolDef = {
 	name: "replace",
@@ -273,10 +290,7 @@ const toolDef: ToolDef = {
 
 	renderResult(result, { isPartial }, theme, context) {
 		if (isPartial) {
-			const text =
-				(context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-			text.setText(theme.fg("warning", "Editing..."));
-			return text;
+			return reuseText(context, theme.fg("warning", "Editing..."));
 		}
 
 		const typedResult = result as {
@@ -292,44 +306,18 @@ const toolDef: ToolDef = {
 		}
 
 		if (context.isError) {
-			if (!renderedText) {
-				return new Text("", 0, 0);
-			}
-			const text =
-				context.lastComponent instanceof Text
-					? context.lastComponent
-					: new Text("", 0, 0);
-			text.setText(`\n${theme.fg("error", renderedText)}`);
-			return text;
+			return renderedText
+				? reuseText(context, `\n${theme.fg("error", renderedText)}`)
+				: new Text("", 0, 0);
 		}
 
 		if (isApplied(typedResult.details)) {
-			const appliedChangedText = buildAppliedText(
-				renderedText,
-				typedResult.details,
-				theme,
-			);
-			if (!appliedChangedText) {
-				return new Text("", 0, 0);
-			}
-			const text =
-				context.lastComponent instanceof Text
-					? context.lastComponent
-					: new Text("", 0, 0);
-			text.setText(appliedChangedText);
-			return text;
-		}
-
-		if (!renderedText) {
-			return new Text("", 0, 0);
+			const appliedText = buildAppliedText(renderedText, typedResult.details, theme);
+			return appliedText ? reuseText(context, appliedText) : new Text("", 0, 0);
 		}
 
-		const markdown =
-			context.lastComponent instanceof Markdown
-				? context.lastComponent
-				: new Markdown("", 0, 0, mkMdTheme(theme));
-		markdown.setText(fmtResultMd(renderedText));
-		return markdown;
+		if (!renderedText) return new Text("", 0, 0);
+		return reuseMarkdown(context, fmtResultMd(renderedText), theme);
 	},
 
 	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -353,7 +341,7 @@ const toolDef: ToolDef = {
 				firstChangedLine,
 				lastChangedLine,
 			} = await execPipeline(
-				normalized,
+				normalizedParams,
 				ctx.cwd,
 				constants.R_OK | constants.W_OK,
 				signal,