pi-hashline-edit-pro 0.19.2 → 0.20.0

package/README.md

@@ -12,8 +12,8 @@ The original uses 2-character hashes of a 16-character alphabet, with the hash b
 
 This fork makes two changes that compound:
 
-1. **3-character hash length** over a 64-char URL-safe base64 alphabet (up from 2 characters in the upstream), expanding the hash space from 256 to 262,144 buckets.
-2. **Perfect hashing (collision resolution).** When computing hashes for a file, if a line's base hash collides with an already-assigned hash, the next available hash is assigned from a bitset (32KB, 262,144 bits) using a hint cursor for O(1) amortized lookup. This ensures every line gets a unique anchor, even within a 3-character hash space. Two byte-identical lines (e.g. repeated `}` or repeated `import` statements) get different hashes automatically.
+1. **3-character hash length** over a 62-char alphanumeric alphabet (up from 2 characters in the upstream), expanding the hash space from 256 to 238,328 buckets.
+2. **Perfect hashing (collision resolution).** When computing hashes for a file, if a line's base hash collides with an already-assigned hash, the next available hash is assigned from a bitset (238,328 bits) using a hint cursor for O(1) amortized lookup. This ensures every line gets a unique anchor, even within a 3-character hash space. Two byte-identical lines (e.g. repeated `}` or repeated `import` statements) get different hashes automatically.
 
 ## Installation
 
@@ -49,7 +49,7 @@ szJ│  console.log("world");
 _zl│}
 ```
 
-- `HASH` is a 3-character content hash from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `aB3`). See [Hashing](#hashing) for details.
+- `HASH` is a 3-character content hash from the alphanumeric alphabet `A-Za-z0-9` (e.g. `aB3`). See [Hashing](#hashing) for details.
 
 Optional parameters:
 
@@ -66,10 +66,10 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 
 ```json
 {
+  "path": "src/main.ts",
   "changes": [
-    { "content_lines": ["  console.log('hashline');"], "hash_range_inclusive": ["ve7", "ve7"] }
-  ],
-  "path": "src/main.ts"
+    { "hash_range_inclusive": ["ve7", "ve7"], "content_lines": ["  console.log('hashline');"] }
+  ]
 }
 ```
 
@@ -77,9 +77,9 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 
 ```json
 {
-  "content_lines": ["  console.log('hashline');"],
+  "path": "src/main.ts",
   "hash_range_inclusive": ["ve7", "ve7"],
-  "path": "src/main.ts"
+  "content_lines": ["  console.log('hashline');"]
 }
 ```
 
@@ -89,7 +89,7 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 | `content_lines` | Literal replacement content, one string per line (use `[]` to delete the range). |
 
 - **Request structure validation.** The request envelope (`path`, `changes` in bulk mode; `path`, `hash_range_inclusive`, `content_lines` in flat mode) 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 `{content_lines: [...], hash_range_inclusive: ["<START>", "<END>"]}`.
+- **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 (bulk mode).** 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.
 
 ### Stable hashing across edits
@@ -169,13 +169,13 @@ The file is created automatically when any setting is toggled. Both fields are i
 | `[E_BAD_OP]` | Range start line is after range end line. |
 | `[E_EDIT_CONFLICT]` | Two edits in one batch overlap the same original lines. |
 | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. |
-| `[E_FILE_TOO_LARGE]` | The file exceeds the 262,144-line hashline limit. |
+| `[E_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit. |
 
 ## 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_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.
+- **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. When a range has one stale and one still-valid anchor, the error also shows the current lines (with fresh hashes) around the resolved anchor, so the model can re-locate the range without a full re-read. 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 diff-preview rows — `+HASH│` addition prefixes, `-HASH│` or `-   │` deletion rows (the padded format the diff preview emits), 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.
+- **Strict patch content.** If `content_lines` contains diff-preview rows — `+HASH│` addition prefixes, `-HASH│` or `-   │` deletion rows (the padded format the diff preview emits), 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 alphanumeric 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.
 
 - **BOM preservation.** A UTF-8 BOM is stripped for display and hashing but restored on write, so edits (and undo) never silently strip a BOM from a file that has one.
 - **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.
@@ -185,17 +185,17 @@ The file is created automatically when any setting is toggled. Both fields are i
 - **Persistent hash store.** `lineHashes` is async and uses a persistent store to preserve hashes for unchanged lines across edits. The store is a SQLite database at `~/.config/pi-hashline-edit-pro/hash-store.sqlite` (per-path snapshots keyed by resolved path storing a 64-bit content checksum + line hashes; auto-created on first use). When called from the replace pipeline, it maps old vs new content and copies hashes for unchanged lines. When called from read, it returns saved hashes if the content's checksum matches, otherwise computes fresh hashes via `_lineHashesPure`. Stale snapshots are pruned on session start. This ensures that editing one part of a file does not cascade to change hashes of unrelated lines. Per-operation work scales with the target file, not cumulative history. If the database is corrupt or unreadable it is quarantined (renamed to `hash-store.sqlite.corrupt-<timestamp>`) and rebuilt from content on the next session start — the store is a cache, never a source of truth.
 ## Hashing
 
-Hashes are computed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32 via WebAssembly), then mapped to a 3-character string from the URL-safe base64 alphabet `A-Za-z0-9-_`. That's 64 distinct characters, 6 bits per position, 18 bits of entropy per anchor.
+Hashes are computed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32 via WebAssembly), then mapped to a 3-character string from the alphanumeric alphabet `A-Za-z0-9`. That's 62 distinct characters, 62³ = 238,328 possible anchors (≈17.9 bits of entropy per anchor).
 
-The alphabet is sized for an LLM consumer. The model tokenizes, it doesn't squint at pixel glyphs, so the human-readability heuristics used by smaller hand-curated alphabets (no G/L/I/O because they look like digits, no vowels so the hash doesn't accidentally spell a word, no hex digits so it can't be confused with `0xFF`) don't apply. The full 64 chars give maximum entropy per character, with case and digits included.
+The alphabet is sized for an LLM consumer. The model tokenizes, it doesn't squint at pixel glyphs, so the human-readability heuristics used by smaller hand-curated alphabets (no G/L/I/O because they look like digits, no vowels so the hash doesn't accidentally spell a word, no hex digits so it can't be confused with `0xFF`) don't apply — 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 (`-HASH│`), and `-`/`_` at a line start are markdown-active (list bullet, emphasis), so they invite mis-copying and false `[E_INVALID_PATCH]`/`[E_BARE_HASH_PREFIX]` rejections. The 9% hash-space cost (238,328 vs 262,144) is irrelevant for real files.
 
 Before hashing, each line is normalized: carriage returns are stripped and trailing whitespace is trimmed. This `canon()` normalization prevents insignificant whitespace changes from cascade-triggering hash churn across the file. Two lines that differ only in trailing spaces or `\r` characters produce the same hash, so anchor stability is preserved across editor-save cycles that add or remove trailing whitespace.
 
-**Perfect hashing (collision resolution):** When computing hashes for a file, if a line's base hash collides with an already-assigned hash, the next available hash is assigned from a bitset (32KB, 262,144 bits) using a hint cursor for O(1) amortized lookup. This ensures every line in a file gets a unique anchor, even with the shorter 3-character hash space. Two byte-identical lines (e.g. repeated `}` or repeated `import` statements) get different hashes automatically.
+**Perfect hashing (collision resolution):** When computing hashes for a file, if a line's base hash collides with an already-assigned hash, the next available hash is assigned from a bitset (238,328 bits) using a hint cursor for O(1) amortized lookup. This ensures every line in a file gets a unique anchor, even with the shorter 3-character hash space. Two byte-identical lines (e.g. repeated `}` or repeated `import` statements) get different hashes automatically.
 The runtime always precomputes the full per-line hash array for a file via `lineHashes(content, path)`, then looks up by line number during validation and during `read` / `replace` response formatting. There is no per-line recomputation that could disagree with what the model saw in its last read. When `path` is provided, `lineHashes` uses a persistent store to preserve hashes for unchanged lines across edits — see [Stable hashing across edits](#stable-hashing-across-edits).
 `HASH_LEN` in `src/hashline/hash.ts` sets the hash body length; bump it to 4 if you need even more entropy without collision resolution.
 
-The 3-character space holds 262,144 unique anchors, so files are capped at 262,144 lines: `read` and `replace` reject larger files with `[E_FILE_TOO_LARGE]` (use `write` or a non-line-based approach for very large files).
+The 3-character space holds 238,328 unique anchors, so files are capped at 238,328 lines: `read` and `replace` reject larger files with `[E_FILE_TOO_LARGE]` (use `write` or a non-line-based approach for very large files).
 
 ### Bare-prefix detector
 

package/index.ts

@@ -15,11 +15,11 @@ import { loadHashStore, pruneMissing } from "./src/hash-store";
 import { readNormFile } from "./src/file-reader";
 import { toCwd } from "./src/paths";
 import { resolveTarget } from "./src/fs-write";
-function registerReplaceTool(pi: ExtensionAPI, mode: string, autoRead?: boolean): void {
+function registerReplaceTool(pi: ExtensionAPI, mode: string): void {
   if (mode === "flat") {
-    regReplaceFlat(pi, autoRead);
+    regReplaceFlat(pi);
   } else {
-    regReplace(pi, autoRead);
+    regReplace(pi);
   }
 }
 
@@ -46,7 +46,7 @@ export default function (pi: ExtensionAPI): void {
     const config = await readConfig();
     const mode = config.replaceMode;
     autoRead = config.autoRead;
-    registerReplaceTool(pi, mode, autoRead);
+    registerReplaceTool(pi, mode);
 
 
     if (debugValue === "1" || debugValue === "true") {
@@ -58,7 +58,7 @@ export default function (pi: ExtensionAPI): void {
     description: "Toggle replace tool between bulk (changes array) and flat (single edit at top level) mode",
     handler: async (_args, ctx) => {
       const mode = await toggleReplaceMode();
-      registerReplaceTool(pi, mode, autoRead);
+      registerReplaceTool(pi, mode);
       ctx.ui.notify(`Replace mode switched to: ${mode}`, "info");
     },
   });
@@ -68,7 +68,7 @@ export default function (pi: ExtensionAPI): void {
     handler: async (_args, ctx) => {
       autoRead = await toggleAutoRead();
       const mode = (await readConfig()).replaceMode;
-      registerReplaceTool(pi, mode, autoRead);
+      registerReplaceTool(pi, mode);
       const state = autoRead ? "enabled" : "disabled";
       ctx.ui.notify(`Auto-read after write/replace: ${state}`, "info");
     },

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "type": "module",
-  "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
+  "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 62-symbol, perfect hashing)",
   "main": "index.ts",
   "repository": {
     "type": "git",

package/prompts/read.md

@@ -1 +1 @@
-Read a text file; each line returned as HASH│content with a 3-char URL-safe base64 hash. No line numbers — use the HASH as the anchor in replace calls. Images → visual attachments; Binary/directory → 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; empty → HASH│ (replace to insert); pageable with offset/limit; BOM stripped; non-UTF-8 shown as U+FFFD.

package/prompts/replace-guidelines.md

@@ -1,3 +1,3 @@
-- `replace`: content_lines is a native JSON array of strings — never a serialized JSON string; strip the HASH│ prefix from read output and keep leading whitespace exactly as shown after │; no line numbers or diff markers.
 - `replace`: hash_range_inclusive must use only anchors from the most recent read of the same file; on [E_STALE_ANCHOR], re-read the file and retry with fresh anchors.
+- `replace`: content_lines is a native JSON array of strings — never a serialized JSON string; strip the HASH│ prefix from read output and keep leading whitespace exactly as shown after │; no line numbers or diff markers.
 - `replace`: minimize the replaced range — anchor only the lines that actually change; for insertions use a single-line range (e.g. the line after the insertion point) instead of a whole block, so fewer unchanged lines must be reproduced byte-exact.

package/src/constants.ts

@@ -3,7 +3,7 @@ export const SNIFF_BYTES = 8192;
 export const MAX_BYTES = 100 * 1024 * 1024;
 
 export const HASH_STORE_BUSY_TIMEOUT = 1000;
-export const HASH_STORE_VERSION = 3;
+export const HASH_STORE_VERSION = 4;
 export const CONTENT_LINES_NOT_STRING_MSG =
   `[E_BAD_SHAPE] "content_lines" must be a native JSON array of strings, not a JSON string.`
   + ` Do not serialize the array (e.g. '["line1", "line2"]') — pass it as a proper JSON array: ["line1", "line2"].`;

package/src/fs-write.ts

@@ -10,6 +10,7 @@ import {
 	stat,
 	writeFile,
 	copyFile,
+	chmod,
 } from "fs/promises";
 import { dirname, join, parse, resolve, sep } from "path";
 import { errCode } from "./utils";
@@ -73,6 +74,7 @@ export async function resolveTarget(path: string): Promise<string> {
 }
 
 const TEMP_PREFIX = ".tmp-";
+const TEMP_UUID_RE = /^\.tmp-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const STALE_TEMP_MS = 60 * 60 * 1000;
 const sweptDirs = new Set<string>();
 
@@ -83,7 +85,7 @@ async function sweepStaleTemps(dir: string): Promise<void> {
     const entries = await readdir(dir, { withFileTypes: true });
     const now = Date.now();
     for (const entry of entries) {
-      if (!entry.isFile() || !entry.name.startsWith(TEMP_PREFIX)) continue;
+      if (!entry.isFile() || !TEMP_UUID_RE.test(entry.name)) continue;
       const tempPath = join(dir, entry.name);
       try {
         const stats = await stat(tempPath);
@@ -154,6 +156,9 @@ export async function writeAtomic(
     if (errCode(error) === "EXDEV") {
       try {
         await copyFile(tempPath, targetPath);
+        if (existingStats) {
+          await chmod(targetPath, existingStats.mode & 0o7777);
+        }
         await rm(tempPath, { force: true });
         await syncDir(dir);
         return;

package/src/hashline/hash.ts

@@ -14,9 +14,7 @@ export const ANCHOR_LEN = HASH_LEN;
 export const HASH_SEP = "│";
 
 const ALPH =
-	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-const ALPH_BITS = 6;
-const ALPH_MASK = (1 << ALPH_BITS) - 1;
+	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 const ALPH_SAFE = ALPH.replace(/-/g, "\\-");
 const ALPH_RE = new RegExp(`^[${ALPH_SAFE}]+$`);
 export const HASH_CLASS = `[${ALPH_SAFE}]{${HASH_LEN}}`;
@@ -27,15 +25,22 @@ export const MAX_HASH_LINES = HASH_SPACE;
 function idxToHash(idx: number): string {
   let out = "";
   for (let j = 0; j < HASH_LEN; j++) {
-    out += ALPH[(idx >>> ((HASH_LEN - 1 - j) * ALPH_BITS)) & ALPH_MASK]!;
+    out = ALPH[idx % ALPH.length]! + out;
+    idx = Math.floor(idx / ALPH.length);
   }
   return out;
 }
 
-const HASH_TABLE: string[] = Array.from(
-  { length: HASH_SPACE },
-  (_, i) => idxToHash(i),
-);
+const hashCache = new Map<number, string>();
+
+function hashAt(idx: number): string {
+  let hash = hashCache.get(idx);
+  if (hash === undefined) {
+    hash = idxToHash(idx);
+    hashCache.set(idx, hash);
+  }
+  return hash;
+}
 
 export const HL_PREFIX_PLUS_RE = new RegExp(
 	`^\\+\\s*${HASH_CLASS}│`,
@@ -63,22 +68,24 @@ function setBit(bits: Uint32Array, idx: number): void {
 
 function nextZeroBit(bits: Uint32Array, start: number): number {
   const totalWords = bits.length;
-  const totalBits = totalWords * 32;
+  const totalBits = HASH_SPACE;
+  const lastWordBits = HASH_SPACE - (totalWords - 1) * 32;
 
   if (start >= totalBits) start = 0;
 
   const wordIdx = start >>> 5;
   const bitOffset = start & 31;
+  const wordBits = (w: number): number => (w === totalWords - 1 ? lastWordBits : 32);
 
   let word = bits[wordIdx];
-  for (let b = bitOffset; b < 32; b++) {
+  for (let b = bitOffset; b < wordBits(wordIdx); b++) {
     if ((word >>> b & 1) === 0) return wordIdx * 32 + b;
   }
 
   for (let w = wordIdx + 1; w < totalWords; w++) {
     word = bits[w];
     if (~word !== 0) {
-      for (let b = 0; b < 32; b++) {
+      for (let b = 0; b < wordBits(w); b++) {
         if ((word >>> b & 1) === 0) return w * 32 + b;
       }
     }
@@ -87,7 +94,7 @@ function nextZeroBit(bits: Uint32Array, start: number): number {
   for (let w = 0; w < wordIdx; w++) {
     word = bits[w];
     if (~word !== 0) {
-      for (let b = 0; b < 32; b++) {
+      for (let b = 0; b < wordBits(w); b++) {
         if ((word >>> b & 1) === 0) return w * 32 + b;
       }
     }
@@ -107,13 +114,13 @@ function assignHash(used: Uint32Array, baseIdx: number, hint: { value: number })
   if (!getBit(used, baseIdx)) {
     setBit(used, baseIdx);
     hint.value = baseIdx + 1;
-    return HASH_TABLE[baseIdx];
+    return hashAt(baseIdx);
   }
   const start = hint.value > baseIdx + 1 ? hint.value : baseIdx + 1;
   const nextIdx = nextZeroBit(used, start);
   setBit(used, nextIdx);
   hint.value = nextIdx + 1;
-  return HASH_TABLE[nextIdx];
+  return hashAt(nextIdx);
 }
 
 export function _lineHashesPure(content: string): string[] {
@@ -124,7 +131,7 @@ export function _lineHashesPure(content: string): string[] {
 
   for (let i = 0; i < lines.length; i++) {
     const c = canon(lines[i]!);
-    const baseIdx = xxh32(c) >>> 14;
+    const baseIdx = (xxh32(c) >>> 14) % HASH_SPACE;
     hashes[i] = assignHash(used, baseIdx, hint);
   }
   return hashes;
@@ -172,7 +179,7 @@ function hashToIndex(hash: string): number {
   for (let j = 0; j < HASH_LEN; j++) {
     const charIdx = ALPH.indexOf(hash[j]!);
     if (charIdx < 0) return -1;
-    idx = (idx << ALPH_BITS) | charIdx;
+    idx = idx * ALPH.length + charIdx;
   }
   return idx;
 }
@@ -283,7 +290,7 @@ function mapStableHashes(
   for (let i = 0; i < newLines.length; i++) {
     if (newHashes[i]) continue;
     const c = canon(newLines[i]!);
-    const baseIdx = xxh32(c) >>> 14;
+    const baseIdx = (xxh32(c) >>> 14) % HASH_SPACE;
     newHashes[i] = assignHash(used, baseIdx, hint);
   }
 

package/src/hashline/parse.ts

@@ -14,7 +14,7 @@ function diagRef(ref: string): string {
 	const trimmed = ref.trim();
 
 	if (!trimmed.length) {
-		return `[E_BAD_REF] Invalid anchor. Expected a 3-char base64 anchor (e.g. "aB3").`;
+		return `[E_BAD_REF] Invalid anchor. Expected a 3-char alphanumeric anchor (e.g. "aB3").`;
 	}
 
 	if (/^\d+/.test(trimmed)) {
@@ -25,7 +25,7 @@ function diagRef(ref: string): string {
 		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").`;
+	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a 3-char alphanumeric anchor (e.g. "aB3").`;
 }
 
 function parseRef(ref: string): Anchor {
@@ -59,7 +59,9 @@ function assertNoPrefixes(lines: string[]): void {
 }
 
 export function parseText(edit: string[] | string | null): string[] {
-  if (edit === null) return [];
+  if (edit === null) {
+    throw new Error('[E_BAD_SHAPE] "content_lines" must be a string array; use [] to delete a range.');
+  }
   if (typeof edit === "string") {
     throw new Error(CONTENT_LINES_NOT_STRING_MSG);
   }

package/src/hashline/resolve.ts

@@ -19,6 +19,7 @@ interface HMismatch {
 	ref: Anchor;
 	kind: "not_found" | "ambiguous";
 	candidates?: number[];
+	context?: RAnchor;
 }
 
 export interface BDupWarn {
@@ -95,6 +96,18 @@ export function fmtMismatch(
     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 hash_range_inclusive of your next replace call.`
     );
+    for (const m of notFound) {
+      const ctx = m.context;
+      if (!ctx) continue;
+      const from = Math.max(1, ctx.line - 1);
+      const to = Math.min(fileLines.length, ctx.line + 1);
+      const rows: string[] = [];
+      for (let ln = from; ln <= to; ln++) {
+        rows.push(`    ${ln}: ${fileHashes[ln - 1]}│${clipLine(fileLines[ln - 1] ?? "")}`);
+      }
+      out.push("");
+      out.push(`  Current context around resolved anchor "${ctx.hash}" (line ${ctx.line}):\n${rows.join("\n")}`);
+    }
   }
   if (ambiguous.length > 0) {
     if (out.length > 0) out.push("");
@@ -297,6 +310,13 @@ export function valEdits(
 		const startResolved = tryResolve(edit.hash_range_inclusive[0]);
 		const endResolved = tryResolve(edit.hash_range_inclusive[1]);
 		if (!startResolved || !endResolved) {
+			if (!startResolved && endResolved) {
+				const startMismatch = mismatches.findLast((m) => m.ref === edit.hash_range_inclusive[0]);
+				if (startMismatch && startMismatch.kind === "not_found") startMismatch.context = endResolved;
+			} else if (startResolved && !endResolved) {
+				const endMismatch = mismatches.findLast((m) => m.ref === edit.hash_range_inclusive[1]);
+				if (endMismatch && endMismatch.kind === "not_found") endMismatch.context = startResolved;
+			}
 			continue;
 		}
 		if (startResolved.line > endResolved.line) {

package/src/read.ts

@@ -30,7 +30,7 @@ function normPosInt(
 	}
 
 	if (!Number.isInteger(value) || value < 1) {
-		throw new Error(`Read request field "${name}" must be a positive integer.`);
+		throw new Error(`[E_BAD_SHAPE] Read request field "${name}" must be a positive integer.`);
 	}
 
 	return value;

package/src/replace-diff.ts

@@ -45,7 +45,6 @@ export function genDiff(
   newContent: string,
   contextLines = 2,
   newContentHashes?: string[],
-  _oldHashes?: string[],
 ): { diff: string; firstChangedLine: number | undefined } {
   const effectiveNewHashes = newContentHashes ?? _lineHashesPure(newContent);
 

package/src/replace-normalize.ts

@@ -78,7 +78,7 @@ export function normReq(input: unknown): unknown {
     const hri = record.hash_range_inclusive;
     const cl = record.content_lines;
     if (Array.isArray(hri) && Array.isArray(cl)) {
-      record.changes = [{ content_lines: cl, hash_range_inclusive: hri }];
+      record.changes = [{ hash_range_inclusive: hri, content_lines: cl }];
       delete record.hash_range_inclusive;
       delete record.content_lines;
     }

package/src/replace-response.ts

@@ -129,10 +129,10 @@ export function buildNoop(input: NoopInput): TResult {
 }
 
 export function buildChanged(input: SuccessInput): TResult {
-  const { path, result, warnings, snapshotId, originalNormalized, originalHashes, editMeta, resultHashes } = input;
+  const { path, result, warnings, snapshotId, originalNormalized, editMeta, resultHashes } = input;
 
   const resultLines = visLines(result);
-  const diffResult = genDiff(originalNormalized, result, 2, resultHashes, originalHashes);
+  const diffResult = genDiff(originalNormalized, result, 2, resultHashes);
   const addedLines = editMeta.addedLines;
   const removedLines = editMeta.removedLines;
   const warningsBlock = warnBlock(warnings);

package/src/replace-undo.ts

@@ -85,8 +85,12 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
           undo.bom + restoreEndings(undo.content, undo.originalEnding),
         );
 
-        const store = await loadHashStore();
-        upsertSnapshot(store, mutationTargetPath, contentChecksum(undo.content), splitLines(undo.content).length, undo.hashes);
+        try {
+          const store = await loadHashStore();
+          upsertSnapshot(store, mutationTargetPath, contentChecksum(undo.content), splitLines(undo.content).length, undo.hashes);
+        } catch (error) {
+          console.error("Failed to restore hash store snapshot after undo:", error);
+        }
 
         clearUndo(mutationTargetPath);
 

package/src/replace.ts

@@ -59,25 +59,25 @@ const hashRangeInclSchema = Type.Array(
 
 const changeItemSchema = Type.Object(
   {
-    content_lines: contentLinesSchema,
     hash_range_inclusive: hashRangeInclSchema,
+    content_lines: contentLinesSchema,
   },
   { additionalProperties: false },
 );
 
 export const editToolSchema = Type.Object(
   {
-    changes: Type.Array(changeItemSchema, { description: "Array of edits applied atomically against the same pre-edit snapshot." }),
     path: Type.String({ description: "Path to edit" }),
+    changes: Type.Array(changeItemSchema, { description: "Array of edits applied atomically against the same pre-edit snapshot." }),
   },
   { additionalProperties: false },
 );
 
 export const flatEditToolSchema = Type.Object(
   {
-    content_lines: contentLinesSchema,
-    hash_range_inclusive: hashRangeInclSchema,
     path: Type.String({ description: "Path to edit" }),
+    hash_range_inclusive: hashRangeInclSchema,
+    content_lines: contentLinesSchema,
   },
   { additionalProperties: false },
 );
@@ -123,7 +123,7 @@ export function assertNoLegacyKeys(request: unknown): void {
   for (const legacyKey of LEGACY_KS) {
     if (has(request, legacyKey)) {
       throw new Error(
-        `[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {content_lines: [...], hash_range_inclusive: ["<START>", "<END>"]}.`
+        `[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}.`
       );
     }
   }
@@ -148,10 +148,10 @@ export function assertReq(
   if (!Array.isArray(request.changes)) {
     if (flat) {
       throw new Error(
-        '[E_BAD_SHAPE] Edit request requires both "content_lines" and "hash_range_inclusive" at the top level.',
+        '[E_BAD_SHAPE] Edit request requires both "hash_range_inclusive" and "content_lines" at the top level.',
       );
     }
-    throw new Error('[E_BAD_SHAPE] Edit request requires a "changes" array. Each change is { content_lines: [...], hash_range_inclusive: ["<START>", "<END>"] }.');
+    throw new Error('[E_BAD_SHAPE] Edit request requires a "changes" array. Each change is { hash_range_inclusive: ["<START>", "<END>"], content_lines: [...] }.');
   }
 }
 
@@ -283,11 +283,11 @@ export async function compPreview(
     const normalized = normReq(request);
     if (flat && isRec(request) && Array.isArray(request.changes)) {
       return {
-        error: `[E_BAD_SHAPE] Flat mode does not accept a "changes" array. Send content_lines and hash_range_inclusive at the top level (one edit per call), or use bulk mode for multiple edits per call.`
+        error: `[E_BAD_SHAPE] Flat mode does not accept a "changes" array. Send hash_range_inclusive and content_lines at the top level (one edit per call), or use bulk mode for multiple edits per call.`
       };
     }
     assertReq(normalized, flat);
-    const { path, originalNormalized, originalHashes, result, resultHashes } = await execPipeline(
+    const { path, originalNormalized, result, resultHashes } = await execPipeline(
       normalized,
       cwd,
       { accessMode: constants.R_OK, noPersist: true },
@@ -299,7 +299,7 @@ export async function compPreview(
       };
     }
 
-    return { diff: genDiff(originalNormalized, result, 4, resultHashes, originalHashes).diff };
+    return { diff: genDiff(originalNormalized, result, 4, resultHashes).diff };
   } catch (error: unknown) {
     return { error: error instanceof Error ? error.message : String(error) };
   }
@@ -336,7 +336,7 @@ const MODE_CFG = {
   },
 } as const;
 
-export function buildToolDef(opts: { flat: boolean; autoRead?: boolean }): ToolDef {
+export function buildToolDef(opts: { flat: boolean }): ToolDef {
   const cfg = MODE_CFG[opts.flat ? "flat" : "bulk"];
 
   const E_DESC = loadP("../prompts/replace.md");
@@ -554,14 +554,14 @@ export function buildToolDef(opts: { flat: boolean; autoRead?: boolean }): ToolD
   };
 }
 
-export function regReplace(pi: ExtensionAPI, autoRead?: boolean): void {
-  pi.registerTool(buildToolDef({ flat: false, autoRead }));
+export function regReplace(pi: ExtensionAPI): void {
+  pi.registerTool(buildToolDef({ flat: false }));
 }
 
-export function buildToolDefFlat(autoRead?: boolean) {
-  return buildToolDef({ flat: true, autoRead });
+export function buildToolDefFlat() {
+  return buildToolDef({ flat: true });
 }
 
-export function regReplaceFlat(pi: ExtensionAPI, autoRead?: boolean): void {
-  pi.registerTool(buildToolDef({ flat: true, autoRead }));
+export function regReplaceFlat(pi: ExtensionAPI): void {
+  pi.registerTool(buildToolDef({ flat: true }));
 }