pi-hashline-edit-pro 2.6.4 → 2.6.5

package/README.md

@@ -2,18 +2,18 @@
 
 [![npm version](https://img.shields.io/npm/v/pi-hashline-edit-pro.svg)](https://www.npmjs.com/package/pi-hashline-edit-pro) [![npm downloads](https://img.shields.io/npm/dm/pi-hashline-edit-pro.svg)](https://www.npmjs.com/package/pi-hashline-edit-pro)
 
-Hash-anchored `read` and `replace` tools for [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent). Every line of a file gets a unique 3-character hash, and you edit by hash. No line numbers, no fuzzy matching, no edits landing on the wrong line.
+Hash-anchored `read` and `replace` tools for [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent). Every line of a file gets a unique 3-character hash, and you edit by hash. There are no line numbers and no fuzzy matching, so edits land on the lines you meant.
 
 Fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW, extended with 3-character hashes and collision resolution.
 
-## What you get
+## Features
 
-- **Read with anchors.** Every line comes back as `HASH│content`. The hash is the line's address.
-- **Edit by hash.** `replace` targets a range of hashes, so edits always land on the lines you meant.
-- **Anchors that stay put.** Edit one part of a file and the hashes of the rest stay the same. Read once, keep editing.
-- **Fresh anchors, automatically.** After every `write` you get the new anchors. After every `replace` you get the diff with the new hashes.
-- **Undo when you need it.** The last replace on a file can be reverted, even after a restart.
-- **Safe writes.** Permissions, line endings, BOMs, symlinks, and hard links survive every edit.
+- `read` returns every line as `HASH│content`. The hash is the line's address.
+- `replace` targets a range of hashes, so edits land on the lines you meant.
+- Editing one part of a file leaves the hashes of the rest unchanged, so anchors from an earlier read stay valid across edits.
+- After a `write` you get the new anchors. After a `replace` you get the diff with the new hashes.
+- The most recent replace on a file can be reverted, even after a restart.
+- Permissions, line endings, BOMs, symlinks, and hard links survive every edit.
 
 ## Quick start
 
@@ -36,7 +36,7 @@ kQm│}
 }
 ```
 
-3. Keep editing. Anchors for lines you didn't touch stay valid, and auto-read hands you fresh anchors after each change.
+3. Keep editing. Anchors for lines you didn't touch stay valid, and auto-read returns fresh anchors after each change.
 
 ## Installation
 
@@ -91,14 +91,14 @@ One edit per call, with `remove_from`, `remove_to`, and `replacement_lines` at t
 | --- | --- |
 | `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_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. |
+| `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 (including a truncated or expanded prefix of up to 6 characters, e.g. `L3│` or `ab12│`) 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. When such a noop happened because a boundary anti-duplication cut removed lines from the replacement (the cut blocked a line that duplicates the block next to the range from being added), the exact same replacement sent once more runs with the edge anti-duplication turned off for that single call and is applied literally — the duplicated lines are kept, and the result carries a `[E_BOUNDARY_BYPASS]` notice. The pending bypass is per file and keyed to that payload; copied `HASH│` prefixes, diff markers, and stray whitespace in the resend are normalized before matching, so a copy-paste resend still hits it. Any applied edit clears it, and a successful `write` also clears it.
-- 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.
+- Common copy-paste slips are fixed automatically and reported: a leftover `HASH│` prefix (including a truncated or expanded prefix of up to 6 characters, e.g. `L3│` or `ab12│`) 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. When such a noop happened because a boundary anti-duplication cut removed lines from the replacement (the cut blocked a line that duplicates the block next to the range from being added), the same replacement sent once more runs with the edge anti-duplication turned off for that single call and is applied literally. The duplicated lines are kept, and the result carries a `[E_BOUNDARY_BYPASS]` notice. The pending bypass is per file and keyed to that payload; copied `HASH│` prefixes, diff markers, and stray whitespace in the resend are normalized before matching, so a copy-paste resend still hits it. Any applied edit clears it, and a successful `write` also clears it.
+- Every line in the removed range must match what was last shown to you. The extension records the `HASH│content` rows it serves (`read` output, the auto-read block after `write`, the `+HASH│`/` HASH│` rows of post-edit diffs (replace and undo), the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale/ambiguous-anchor feedback) and verifies the whole range against that record before writing. If an interior line changed on disk since it was shown (external editor, formatter-on-save, code generation) or was never shown, the edit is refused with `[E_RANGE_STALE]` and the current range is returned with fresh anchors, so the retry needs no `read`. Edits outside the served record are only possible for files that were never read (for example right after a `write` with auto-read disabled); once the file has been served, every replaced line must have been shown.
 - After a successful edit you get the post-edit diff with fresh anchors, so you can keep editing without re-reading.
 - Do not issue multiple replace calls on the same file in one message; parallel edits split attention across the post-edit diffs and removed lines are easy to miss. Verify each diff before the next edit on that file.
 - Line endings and BOMs survive every edit. The file's line ending is detected from its first newline and restored on write; a file that mixes LF and CRLF (for example a WSL-edited file) is normalized to the first-seen ending.
@@ -134,7 +134,7 @@ All three tools return machine-readable metadata in `details` alongside the mode
 
 | Command | Description |
 | --- | --- |
-| `/toggle-auto-read` | Toggle automatic hashline anchors after write and post-edit diffs after replace and undo_last_replace operations. Persists across sessions. |
+| `/toggle-auto-read` | Toggle auto-read anchors after write and post-edit diffs after replace and undo_last_replace. Persists across sessions. |
 
 Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatically when a setting is toggled. On non-Windows platforms, the config directory honors `XDG_CONFIG_HOME` when set (falling back to `~/.config`); on Windows it always uses `~/.config`:
 
@@ -148,9 +148,9 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 
 Each line is canonicalized (carriage returns stripped, trailing whitespace trimmed) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32), then mapped to a 3-character string over `A-Za-z0-9`, which gives 62³ = 238,328 possible anchors. The canonicalization keeps anchors stable across editor-save cycles that add or remove trailing whitespace.
 
-The alphabet is sized for an LLM consumer: the model tokenizes rather than squinting at glyphs, so case and digits are all included. The URL-safe specials `-` and `_` are deliberately excluded. A hash starting with `-` is shape-identical to a diff-preview deletion row, and `-`/`_` at a line start are markdown-active, inviting mis-copying and false autocorrections.
+The alphabet is sized for an LLM consumer: the model reads the hashes as tokens rather than inspecting glyph shapes, so letters and digits are all included. The URL-safe specials `-` and `_` are deliberately excluded. A hash starting with `-` looks like a diff-preview deletion row, and `-`/`_` at the start of a line are markdown-active, which invites mis-copying and false autocorrections.
 
-Unique anchors by construction. If a line's base hash collides with an already-assigned hash, the next free hash is allocated from a bitset by probing with a stride coprime to the hash space (O(1) amortized). The stride is `62² + 62 + 1`, so consecutive collisions, runs of blank lines, repeated `}`, land on anchors that differ in all three characters instead of sharing a prefix. Every line in a file therefore gets a unique anchor; two byte-identical lines (repeated `}`, repeated `import` statements) never share one. The same guarantee sets the file size cap: at most 238,328 lines per file, beyond which `read` and `replace` reject with `[E_FILE_TOO_LARGE]` (use `write` for very large files).
+Anchors are unique by construction. If a line's base hash collides with an already-assigned hash, the next free hash is allocated from a bitset by probing with a stride coprime to the hash space (O(1) amortized). The stride is `62² + 62 + 1`, so consecutive collisions, runs of blank lines, repeated `}`, land on anchors that differ in all three characters instead of sharing a prefix. Every line in a file therefore gets a unique anchor; two byte-identical lines (repeated `}`, repeated `import` statements) never share one. The same guarantee sets the file size cap: at most 238,328 lines per file, beyond which `read` and `replace` reject with `[E_FILE_TOO_LARGE]` (use `write` for very large files).
 
 Hashes live in a persistent per-file store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) that keeps the hashes of unchanged lines across edits. When a range is replaced, the runtime maps the old content onto the new content and copies hashes for lines that survived; only genuinely new lines get fresh hashes.
 

package/index.ts

@@ -48,11 +48,11 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("toggle-auto-read", {
-    description: "Toggle automatic hashline anchors after write and post-edit diffs after replace and undo_last_replace operations",
+    description: "Toggle auto-read anchors after write and post-edit diffs after replace and undo_last_replace",
     handler: async (_args, ctx) => {
       autoRead = await toggleAutoRead();
       const state = autoRead ? "enabled" : "disabled";
-      ctx.ui.notify(`Auto-read anchors (write) and post-edit diffs (replace/undo): ${state}`, "info");
+      ctx.ui.notify(`Auto-read anchors after write and post-edit diffs after replace/undo: ${state}`, "info");
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "2.6.4",
+  "version": "2.6.5",
   "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/read-guidelines.md

@@ -1,2 +1,2 @@
 - `read`: call before `replace` when you need fresh HASH anchors for a file.
-- `read`: call again after any edit to that file — changed lines get new anchors (the post-edit diff rows from replace/undo also carry fresh anchors for the changed range).
+- `read`: call again after an edit when you need anchors you do not have. The post-edit diff after replace/undo already carries fresh anchors for the changed range.

package/prompts/read.md

@@ -1 +1 @@
-Read a text file; each line returned as HASH│content with a 3-char alphanumeric hash. No line numbers — use the HASH as the anchor in replace calls. Images → visual attachments; Binary/directory → rejected; UTF-16/UTF-32 (BOM) → rejected; empty → HASH│ (replace to insert); pageable with offset/limit; BOM stripped; non-UTF-8 shown as U+FFFD.
+Read a text file; each line returned as HASH│content with a 3-char alphanumeric hash. No line numbers: use the HASH as the anchor in replace calls. Images → visual attachments; Binary/directory → rejected; UTF-16/UTF-32 (BOM) → rejected; empty → HASH│ (replace to insert); pageable with offset/limit; BOM stripped; non-UTF-8 shown as U+FFFD.

package/prompts/replace-guidelines.md

@@ -1,8 +1,8 @@
-- `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 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_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`: 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, use the same hash for both remove_from and remove_to (e.g. 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`: 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`: 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`: do not issue multiple replace calls on the same file in one message. Issue the next edit only after verifying the previous diff.

package/prompts/replace-snippet.md

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

package/prompts/replace.md

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

package/prompts/undo-last-replace-guidelines.md

@@ -1,2 +1,2 @@
-- `undo_last_replace`: reverts only the most recent replace on the file — any write to the file clears the undo history, so call it immediately after a bad replace. A replace is bad when its post-edit diff shows `-HASH│` rows for lines you meant to keep (a closing brace, import, or declaration).
+- `undo_last_replace`: reverts only the most recent replace on the file: any write to the file clears the undo history, so call it immediately after a bad replace. A replace is bad when its post-edit diff shows `-HASH│` rows for lines you meant to keep (a closing brace, import, or declaration).
 - `undo_last_replace`: when auto-read shows the post-edit diff, its `+HASH│` and ` HASH│` rows are the fresh anchors for the restored file, so follow-up edits can anchor on the diff without re-reading.

package/src/constants.ts

@@ -7,5 +7,4 @@ 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_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.`;
+  `[E_BAD_SHAPE] "replacement_lines" must be an array of strings, one per line (use [] to delete).`;

package/src/file-kind.ts

@@ -143,7 +143,7 @@ export async function loadFileKindAndText(
         }
         if (newlineCount > options.maxLines) {
           throw new Error(
-            `[E_FILE_TOO_LARGE] ${options.displayPath ?? filePath} has more than ${options.maxLines} lines, exceeding the ${options.maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
+            `[E_FILE_TOO_LARGE] ${options.displayPath ?? filePath} has more than ${options.maxLines} lines, exceeding the ${options.maxLines}-line hashline limit. For very large files, use write.`,
           );
         }
       }

package/src/file-reader.ts

@@ -91,7 +91,7 @@ export async function readNormFile(
     const lineCount = visLines(normalized).length;
     if (lineCount > options.maxLines) {
       throw new Error(
-        `[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${options.maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
+        `[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${options.maxLines}-line hashline limit. For very large files, use write.`,
       );
     }
   }

package/src/hashline/apply.ts

@@ -55,7 +55,7 @@ type NoopSpan = {
 function assertNotEmpty(originalContent: string, result: string): void {
 	if (originalContent.length > 0 && result.length === 0) {
 		throw new Error(
-			"[E_WOULD_EMPTY] Cannot empty a non-empty file via edit. Use `write` if you need to clear the file."
+			"[E_WOULD_EMPTY] A replace cannot empty a non-empty file. Use `write` to clear the file."
 		);
 	}
 }

package/src/hashline/hash.ts

@@ -70,7 +70,7 @@ function nextZeroBit(bits: Uint32Array, start: number): number {
     if (idx >= totalBits) idx -= totalBits;
   }
   throw new Error(
-    `[E_FILE_TOO_LARGE] Cannot allocate a unique hash anchor: the file exceeds the ${HASH_SPACE}-line limit for ${HASH_LEN}-char hashline anchors. For very large files use write or a non-line-based approach.`,
+    `[E_FILE_TOO_LARGE] File exceeds the ${HASH_SPACE}-line hashline limit; use write for very large files.`,
   );
 }
 

package/src/hashline/parse.ts

@@ -14,11 +14,11 @@ function diagRef(ref: string): string {
 	}
 
 	if (/^\d+/.test(trimmed)) {
-		return `[E_BAD_REF] Invalid anchor. Use the hash alone (e.g. "aB3") — no line numbers or trailing content.`;
+		return `[E_BAD_REF] Invalid anchor. Use the hash alone (e.g. "aB3"): no line numbers or trailing content.`;
 	}
 
 	if (trimmed.includes("│")) {
-		return `[E_BAD_REF] Invalid anchor "${trimmed}". remove_from and remove_to must contain the 3-char hash only — remove everything from "│" onward.`;
+		return `[E_BAD_REF] Invalid anchor "${trimmed}": use only the 3-char hash, drop everything from "│" onward.`;
 	}
 
 	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a 3-char alphanumeric anchor (e.g. "aB3").`;
@@ -52,7 +52,7 @@ export function parseText(edit: string[], warnings?: string[]): string[] {
   }
   if (split) {
     warnings?.push(
-      "[E_BAD_SHAPE] Autocorrected: split replacement_lines element(s) containing embedded newlines into separate lines.",
+      "[E_BAD_SHAPE] Autocorrected: split embedded newlines in replacement_lines into separate lines.",
     );
   }
   return out;

package/src/hashline/resolve.ts

@@ -90,7 +90,7 @@ export function fmtMismatchWithHashes(
   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}. The file content has changed since those anchors were 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 remove_from and remove_to of your next replace call.`
+      `[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. The file changed since read. Call read() for fresh anchors.`
     );
     for (const m of notFound) {
       const ctx = m.context;
@@ -109,7 +109,7 @@ export function fmtMismatchWithHashes(
   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 remove_from and remove_to of your next replace call.`
+      `[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Call read() for fresh anchors.`
     );
     for (const m of ambiguous) {
       const sample = (m.candidates ?? []).slice(0, 5);
@@ -150,7 +150,7 @@ function assertItem(edit: Record<string, unknown>): void {
     );
   }
   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).`);
+    throw new Error(`[E_BAD_SHAPE] The edit requires a "replacement_lines" array (use [] to delete).`);
   }
   if (!Array.isArray(edit.replacement_lines) || edit.replacement_lines.some((line) => typeof line !== "string")) {
     throw new Error(NEW_CONTENT_NOT_ARRAY_MSG);
@@ -174,11 +174,11 @@ export function resEdit(edit: HTEdit, warnings?: string[]): HEdit {
     if (match) {
       let message: string;
       if (match[1] === "+") {
-        message = `[E_BAD_REF] Autocorrected: stripped diff-preview marker copied from the diff preview in remove_from/remove_to entry "${trimmed}".`;
+        message = `[E_BAD_REF] Stripped diff-preview marker from remove_from/remove_to entry "${trimmed}".`;
       } else if (match[1] === "-") {
-        message = `[E_BAD_REF] Autocorrected: stripped leading "-" marker in remove_from/remove_to entry "${trimmed}".`;
+        message = `[E_BAD_REF] Stripped leading "-" marker from remove_from/remove_to entry "${trimmed}".`;
       } else {
-        message = `[E_BAD_REF] Autocorrected: stripped "HASH│" prefix copied from read output in remove_from/remove_to entry "${trimmed}".`;
+        message = `[E_BAD_REF] Stripped "HASH│" prefix from remove_from/remove_to entry "${trimmed}".`;
       }
       warnings?.push(message);
       return match[2]!;
@@ -197,7 +197,7 @@ function warnUnicodeEsc(
 ): void {
   if (edit.content_lines.some((line) => /\\uDDDD/i.test(line))) {
     warnings.push(
-      "Detected literal \\uDDDD in edit content; no autocorrection applied. Verify whether this should be a real Unicode escape or plain text.",
+      "Detected literal \\uDDDD in edit content; no autocorrection applied.",
     );
   }
 }
@@ -220,16 +220,12 @@ export function stripBarePrefixes(
 		.map((s) => `replacement_lines line ${s.lineIndex + 1}`)
 		.join(", ");
 	const matchedCount = stripped.filter((s) => s.matched).length;
-	const evidence =
-		matchedCount === 0
-			? "none of the stripped hashes match current file lines"
-			: `${matchedCount} of ${stripped.length} stripped hash(es) match current file lines`;
 	const guidance =
 		matchedCount === 0
-			? " Verify that these lines were pasted from read output; literal content starting with 'HASH│' would be altered by this strip."
+			? " Verify it was pasted from read output."
 			: "";
 	warnings.push(
-		`[E_BARE_HASH_PREFIX] Autocorrected: stripped "HASH│" prefix copied from read output in ${locations} (${evidence}).${guidance}`
+		`[E_BARE_HASH_PREFIX] Stripped "HASH│" prefix from ${locations}.${guidance}`
 	);
 	return { ...edit, content_lines: contentLines };
 }
@@ -255,7 +251,7 @@ export function stripDiffPrefixes(
 	if (stripped.length === 0) return edit;
 	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}.`
+		`[E_INVALID_PATCH] Stripped diff-preview marker from ${locations}.`
 	);
 	return { ...edit, content_lines: contentLines };
 }
@@ -280,7 +276,7 @@ export function swapReversedRanges(
 		return edit;
 	}
 	warnings.push(
-		`[E_BAD_OP] Autocorrected: remove_from and remove_to were reversed (remove_from ${startRef.hash} is after remove_to ${endRef.hash}); swapped the pair.`
+		`[E_BAD_OP] Autocorrected: remove_from/remove_to were reversed; swapped them.`
 	);
 	return { ...edit, hash_bounds: [endRef, startRef] as [Anchor, Anchor] };
 }
@@ -345,6 +341,7 @@ function firstNewAfterDups(
 	let runLen = 0;
 	while (
 		runLen < maxK &&
+		canonLines[endLine + runLen]!.length > 0 &&
 		canon(contentLines[firstNew.index + runLen]!) === canonLines[endLine + runLen]!
 	) {
 		runLen++;
@@ -369,6 +366,7 @@ function lastNewBeforeDups(
 	let runLen = 0;
 	while (
 		runLen < maxK &&
+		canonLines[startLine - 2 - runLen]!.length > 0 &&
 		canon(contentLines[lastNew.index - runLen]!) === canonLines[startLine - 2 - runLen]!
 	) {
 		runLen++;
@@ -402,8 +400,8 @@ export function findNewEdge(
 	const start = fromEnd ? contentLines.length - 1 : 0;
 	for (let i = start; i >= 0 && i < contentLines.length; i += step) {
 		const line = contentLines[i]!;
-		if (line.length === 0) continue;
 		const key = canon(line);
+		if (key.length === 0) continue;
 		const count = multiset.get(key) ?? 0;
 		if (count > 0) {
 			multiset.set(key, count - 1);
@@ -531,7 +529,7 @@ export function assertRangeServed(
       ? `\n\n[The range has ${rangeLength} lines; showing the first ${shownLength}. Call read() with offset=${startLine + shownLength} to see the rest.]`
       : "";
   const message =
-    `[E_RANGE_STALE] ${mismatchText} what was previously shown: the file changed on disk after the anchors were read, or the line(s) were never shown. Nothing was modified. Current range with fresh anchors:\n\n${rows.join("\n")}${capHint}`;
+    `[E_RANGE_STALE] ${mismatchText} what was shown. Nothing was modified. Current range with fresh anchors:\n\n${rows.join("\n")}${capHint}`;
   throw new RangeStaleError(message, first, shownHashes);
 }
 

package/src/read.ts

@@ -72,7 +72,7 @@ export async function fmtReadPreview(
 			};
 		}
 		return {
-			text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use replace to insert content.`,
+			text: `Offset ${startLine} is beyond end of file (0 lines). Use replace to insert content.`,
 			servedHashes: [],
 		};
 	}
@@ -114,7 +114,7 @@ export async function fmtReadPreview(
 		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}]`;
+		const warning = `[${lineLabel} ${verb} ${formatSize(maxBytes)}; content not shown. Inspect with bash: sed -n '${addresses}' <path> | head -c ${maxBytes}]`;
 		let preview = skippedTruncation.content;
 		let nextOffset: number | undefined;
 		if (shownRowCount > 0 && (skippedTruncation.truncated || lastShownLine < totalLines)) {

package/src/replace-response.ts

@@ -38,6 +38,7 @@ export interface NoopInput {
 	snapshotId?: string;
 	editMeta: RMeta;
 	warnings: string[] | undefined;
+	boundaryRemovedLines?: number;
 }
 
 export interface SuccessInput {
@@ -95,13 +96,18 @@ export function buildNoop(input: NoopInput): TResult {
 		snapshotId,
 		editMeta,
 		warnings,
+		boundaryRemovedLines,
 	} = input;
 
 	const noopDetailsText = noopEdit
 		? `Replacement for ${noopEdit.loc} is identical to current content:\n  ${noopEdit.loc}: ${clipLine(noopEdit.currentContent)}`
 		: "The edit produced identical content.";
+	const dedupNote =
+		boundaryRemovedLines !== undefined && boundaryRemovedLines > 0
+			? `\nBoundary dedup removed ${boundaryRemovedLines} line(s) from the replacement. Send the same edit again to apply it literally.`
+			: "";
 
-	const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}${warnBlock(warnings)}`;
+	const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}${dedupNote}${warnBlock(warnings)}`;
 
 	const metrics = buildMetrics({
 		classification: "noop",

package/src/replace-undo.ts

@@ -110,7 +110,7 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
           content: [
             {
               type: "text",
-              text: `No undo history for ${path}. There is no previous replace to revert.`,
+              text: `No undo history for ${path}.`,
             },
           ],
           isError: true,
@@ -132,7 +132,7 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
             content: [
               {
                 type: "text",
-                text: `[E_UNDO_STALE] Cannot undo last replace on ${path}: the file no longer exists. Call read() to inspect the current state.`
+                text: `[E_UNDO_STALE] Cannot undo last replace on ${path}: the file no longer exists.`
               },
             ],
             isError: true,
@@ -145,7 +145,7 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
             content: [
               {
                 type: "text",
-                text: `[E_UNDO_STALE] Cannot undo last replace on ${path}: the file was modified after the replace, so undoing would overwrite those changes. Call read() to inspect the current state.`
+                text: `[E_UNDO_STALE] Cannot undo last replace on ${path}: the file changed after the replace. Call read() to inspect the current state.`
               },
             ],
             isError: true,
@@ -182,11 +182,11 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
         ];
         if (linesAddedByReplace > 0 || linesRemovedByReplace > 0) {
           parts.push(
-            `Removed ${linesAddedByReplace} line(s) that were added and restored ${linesRemovedByReplace} line(s) that were removed.`,
+            `Removed ${linesAddedByReplace} line(s), restored ${linesRemovedByReplace} line(s).`,
           );
         }
         parts.push(
-          "File reverted to previous state. Call `read` to get fresh anchors for follow-up edits.",
+          "Call read for fresh anchors.",
         );
 
         return {

package/src/replace.ts

@@ -52,7 +52,7 @@ import { noopPayloadKey, markBoundaryNoop, consumeBoundaryBypass, clearBoundaryB
 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.",
+      "One replacement line. Each element is exactly one line; do not embed \\n inside an element: use separate elements.",
   }),
   {
     description:
@@ -61,16 +61,16 @@ const replacementLinesSchema = Type.Array(
 );
 
 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)",
+  description: "Bare 3-char HASH only (e.g. \"aB3\"): copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the FIRST line to remove (inclusive)",
 });
 
 const removeToSchema = Type.String({
-  description: "Bare 3-char HASH only (e.g. \"aB3\") — copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the LAST line to remove (inclusive)",
+  description: "Bare 3-char HASH only (e.g. \"aB3\"): copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the LAST line to remove (inclusive)",
 });
 
 export const editToolSchema = Type.Object(
   {
-    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." })),
+    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_lines: replacementLinesSchema,
@@ -109,6 +109,7 @@ interface PipelineResult {
   totalAddedLines: number;
   totalRemovedLines: number;
   hadBoundaryDedup: boolean;
+  boundaryRemovedLines: number;
 }
 
 const PREVIEW_DEBOUNCE_MS = 150;
@@ -135,7 +136,7 @@ export function assertReq(
     request.replacement_lines.some((line) => typeof line !== "string")
   ) {
     throw new Error(
-      '[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).',
+      '[E_BAD_SHAPE] Edit request requires "remove_from", "remove_to", and "replacement_lines" (array of strings, one per line; use [] to delete).',
     );
   }
 }
@@ -165,12 +166,12 @@ async function resolveMissingPath(
   if (matches.length === 1) {
     return {
       path: matches[0]!,
-      warning: `[E_BAD_SHAPE] Autocorrected: missing "path" resolved to ${matches[0]} — the only file whose stored hashes contain both anchors.`,
+      warning: `[E_BAD_SHAPE] Autocorrected: missing "path" resolved to ${matches[0]}.`,
     };
   }
   if (matches.length > 1) {
     throw new Error(
-      `[E_BAD_SHAPE] Edit request requires a non-empty "path" string; the anchors match multiple known files: ${matches.join(", ")}. Include the intended path.`,
+      `[E_BAD_SHAPE] Edit request requires a non-empty "path" string; the anchors match multiple known files: ${matches.join(", ")}.`,
     );
   }
   return undefined;
@@ -303,6 +304,7 @@ export async function execPipeline(
     totalAddedLines,
     totalRemovedLines,
     hadBoundaryDedup: (anchorResult.autoFixes?.length ?? 0) > 0,
+    boundaryRemovedLines: anchorResult.autoFixes?.length ?? 0,
   };
 }
 
@@ -500,6 +502,7 @@ export function buildToolDef(): ToolDef {
           lastChangedLine,
           resultHashes,
           hadBoundaryDedup,
+          boundaryRemovedLines,
           totalAddedLines,
           totalRemovedLines,
         } = await execPipeline(
@@ -512,7 +515,7 @@ export function buildToolDef(): ToolDef {
           warnings.unshift(resolution.warning);
         }
         if (boundaryBypass && originalNormalized !== result) {
-          warnings.push("[E_BOUNDARY_BYPASS] Boundary dedup was off for this call. Boundary dedup is now restored.");
+          warnings.push("[E_BOUNDARY_BYPASS] Boundary dedup was off for this call and is back on.");
         }
 
         const editsAttempted = 1;
@@ -532,6 +535,7 @@ export function buildToolDef(): ToolDef {
               removedLines: 0,
             },
             warnings,
+            boundaryRemovedLines,
           });
         }
 
@@ -551,7 +555,7 @@ export function buildToolDef(): ToolDef {
         });
         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.`
+            `[E_UNDO_UNAVAILABLE] Could not persist undo history; the edit was not applied and ${path} is unchanged.`
           );
         }
         try {

package/src/validation.ts

@@ -38,7 +38,7 @@ export function valKind(file: LFile, path: string): asserts file is { kind: "tex
 	}
 	if (file.kind === "too_large") {
 		throw new Error(
-			`[E_FILE_TOO_LARGE] File is too large: ${path} (${file.description}). Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
+			`[E_FILE_TOO_LARGE] File is too large: ${path} (${file.description}). For very large files, use write.`,
 		);
 	}
 }