pi-hashline-edit-pro 0.18.0 → 0.18.2

package/README.md

@@ -13,7 +13,7 @@ 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 hash is incremented (using a retry counter: `:R{retry}`) until a unique hash is found. 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.
+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.
 
 ## Installation
 
@@ -142,7 +142,9 @@ The file is created automatically when any setting is toggled. Both fields are i
 
 - **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.
+- **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.
+
+- **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.
 - **Per-file mutation queue.** Edits queue by the canonical write target, so concurrent edits through different symlink paths still serialize onto the same underlying file.
 - **Boundary duplication auto-fix.** When the last line of a replacement matches the next surviving line (or the first line matches the preceding one), the runtime automatically strips the duplicate from `content_lines` before applying the edit. This catches a common LLM pattern where closing delimiters like `}`, `});`, or `} else {` are accidentally duplicated. The auto-fix is completely silent — the model sees a normal successful edit. The duplicate never reaches the file. Raw line comparison (not trimmed) avoids false positives when indentation differs.
@@ -156,7 +158,7 @@ The alphabet is sized for an LLM consumer. The model tokenizes, it doesn't squin
 
 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 hash is incremented (using a retry counter: `:R{retry}`) until a unique hash is found. 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 (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.
 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.
 

package/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { initHasher } from "./src/hashline";
 import { regReplace, regReplaceFlat } from "./src/replace";
-import { regReplaceUndo } from "./src/replace-undo";
+import { regReplaceUndo, clearUndo } from "./src/replace-undo";
 import { regRead, fmtReadPreview } from "./src/read";
 import { visLines } from "./src/utils";
 import { AUTO_READ_MAX } from "./src/constants";
@@ -12,7 +12,8 @@ import {
 } from "./src/config";
 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 {
   if (mode === "flat") {
     regReplaceFlat(pi, autoRead);
@@ -73,8 +74,18 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("tool_result", async (event, ctx) => {
-    if (!autoRead) return;
     if (event.isError) return;
+    if (event.toolName === "write") {
+      const writtenPath = (event.input as Record<string, unknown>)?.path;
+      if (typeof writtenPath === "string") {
+        try {
+          clearUndo(await resolveTarget(toCwd(writtenPath, ctx.cwd)));
+        } catch (error) {
+          console.error("Failed to clear undo after write:", error);
+        }
+      }
+    }
+    if (!autoRead) return;
     if (event.toolName !== "write" && event.toolName !== "replace") return;
 
     const filePath = (event.input as Record<string, unknown>)?.path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "type": "module",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
@@ -40,6 +40,9 @@
     "@earendil-works/pi-coding-agent": ">=0.74.0",
     "@earendil-works/pi-tui": "*"
   },
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",

package/prompts/read-guidelines.md

@@ -1 +1,2 @@
-- `read`: call before `replace` when you need fresh HASH anchors for a file.
+- `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.

package/prompts/read.md

@@ -1,3 +1 @@
-Read a text file. Each line returned as HASH│content (3-char URL-safe base64 hash). No line numbers — use the 3-char HASH to reference lines in replace calls.
-
-Text → HASH│content lines. 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 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.

package/prompts/replace-guidelines.md

@@ -1,2 +1,2 @@
-- `replace`: Provide hash_range_inclusive [start_hash, end_hash] targeting lines by their 3-char hashes (replaces every line from first anchor through last anchor inclusively), and content_lines as a native JSON array of strings for the replacement text.
-- `replace`: preserve leading whitespace exactly as it appears after │ in read output.
+- `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.

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

@@ -1,2 +1 @@
-- `undo_last_replace`: call with the file path to revert the last replace on that file.
-- `undo_last_replace`: only the most recent replace per file is tracked.
+- `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.

package/src/constants.ts

@@ -6,7 +6,7 @@ export const MAX_HASH_LINES = 1_000_000;
 export const MAX_HASH_RETRIES = 262_144;
 
 export const HASH_STORE_BUSY_TIMEOUT = 1000;
-export const HASH_STORE_VERSION = 2;
+export const HASH_STORE_VERSION = 3;
 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/file-kind.ts

@@ -81,7 +81,7 @@ export async function loadFileKindAndText(
     }
 
 
-    const decoder = new TextDecoder("utf-8", { fatal: false });
+    const decoder = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true });
     let hadUtf8DecodeErrors = false;
     const parts: string[] = [];
 

package/src/hash-store.ts

@@ -2,10 +2,9 @@ import { existsSync } from "fs";
 import { readFile, rename, mkdir, stat } from "fs/promises";
 import { DatabaseSync } from "node:sqlite";
 import { hashStorePath, hashStoreDir, legacyHashStorePath } from "./paths";
-import { errCode } from "./utils";
+import { errCode, splitLines } from "./utils";
 import { initHasher, contentChecksum } from "./hashline/hasher";
 import { HASH_STORE_VERSION, HASH_STORE_BUSY_TIMEOUT } from "./constants";
-
 type SqlParams = (string | number)[];
 
 interface Prepared {
@@ -37,7 +36,7 @@ function isValidSnapshot(value: unknown): value is LegacySnapshot {
 }
 
 let cachedDb: { path: string; db: DatabaseSync; stmts: Prepared } | null = null;
-
+let exitHandlerRegistered = false;
 function openDb(storePath: string): { db: DatabaseSync; stmts: Prepared } {
   const db = new DatabaseSync(storePath, {
     timeout: HASH_STORE_BUSY_TIMEOUT,
@@ -92,11 +91,27 @@ export async function loadHashStore(): Promise<HashStore> {
   }
 
   cachedDb = { path: storePath, db, stmts };
+
+  if (!exitHandlerRegistered) {
+    exitHandlerRegistered = true;
+    process.once("exit", () => shutdownHashStore());
+    for (const sig of ["SIGINT", "SIGTERM"] as const) {
+      process.once(sig, () => {
+        shutdownHashStore();
+        process.kill(process.pid, sig);
+      });
+    }
+  }
+
   return { stmts, engine: "node:sqlite" };
 }
 
 export function shutdownHashStore(): void {
   if (cachedDb) {
+    try {
+      cachedDb.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    } catch {
+    }
     cachedDb.db.close();
     cachedDb = null;
   }
@@ -145,12 +160,11 @@ async function migrateLegacy(db: DatabaseSync): Promise<void> {
     rows.push([
       key,
       contentChecksum(value.content),
-      value.content.split("\n").length,
+      splitLines(value.content).length,
       JSON.stringify(value.hashes),
       Date.now(),
     ]);
   }
-
   if (rows.length > 0) {
     db.exec("BEGIN IMMEDIATE");
     try {
@@ -178,7 +192,7 @@ export function getSnapshot(
   content: string,
 ): string[] | undefined {
   const checksum = contentChecksum(content);
-  const lineCount = content.split("\n").length;
+  const lineCount = splitLines(content).length;
   const row = store.stmts.get(path, checksum, lineCount);
   return row ? (JSON.parse(row.hashes as string) as string[]) : undefined;
 }

package/src/hashline/apply.ts

@@ -1,4 +1,4 @@
-import { abortIf, visLines, lastNonEmptyIndex, firstNonEmptyIndex } from "../utils";
+import { abortIf, splitLines, lastNonEmptyIndex, firstNonEmptyIndex } from "../utils";
 import { _lineHashesPure, HASH_SEP } from "./hash";
 import {
 	valEdits,
@@ -18,22 +18,22 @@ type LIdx = {
 };
 
 export function buildIdx(content: string): LIdx {
-	const fileLines = content.split("\n");
-	const lineStarts: number[] = [];
-	let offset = 0;
-
-	for (let index = 0; index < fileLines.length; index++) {
-		lineStarts.push(offset);
-		offset += fileLines[index]!.length;
-		if (index < fileLines.length - 1) {
-			offset += 1;
-		}
-	}
+  const fileLines = splitLines(content);
+  const lineStarts: number[] = [];
+  let offset = 0;
+
+  for (let index = 0; index < fileLines.length; index++) {
+    lineStarts.push(offset);
+    offset += fileLines[index]!.length;
+    if (index < fileLines.length - 1) {
+      offset += 1;
+    }
+  }
 
-	return {
-		fileLines,
-		lineStarts,
-	};
+  return {
+    fileLines,
+    lineStarts,
+  };
 };
 
 type RESpan = {
@@ -124,16 +124,26 @@ function resToSpan(
     };
   }
 
+  if (content.endsWith("\n")) {
+    return {
+      kind: "replace",
+      index,
+      label,
+      start: lineStarts[startLine - 1]!,
+      end: content.length,
+      replacement: "",
+    };
+  }
+
   return {
     kind: "replace",
     index,
     label,
     start: Math.max(0, lineStarts[startLine - 1]! - 1),
-    end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
+    end: content.length,
     replacement: "",
   };
 }
-
 function assertNoConflict(spans: RESpan[]): void {
 	for (let leftIndex = 0; leftIndex < spans.length; leftIndex++) {
 		const left = spans[leftIndex]!;
@@ -375,14 +385,14 @@ export function changedRange(
 	if (original.length === 0) {
 		return {
 			firstChangedLine: 1,
-			lastChangedLine: visLines(result).length,
+			lastChangedLine: splitLines(result).length,
 		};
 	}
 
 	if (result.startsWith(original) && original.endsWith("\n")) {
 		return {
-			firstChangedLine: visLines(original).length + 1,
-			lastChangedLine: visLines(result).length,
+			firstChangedLine: splitLines(original).length + 1,
+			lastChangedLine: splitLines(result).length,
 		};
 	}
 
@@ -415,7 +425,7 @@ export function changedRange(
 	const firstChangedLine = idxToLine(firstDiff + 1, result);
 	let lastChangedLine: number;
 	if (lastRes < firstDiff) {
-		lastChangedLine = result.length === 0 ? 1 : visLines(result).length;
+		lastChangedLine = result.length === 0 ? 1 : splitLines(result).length;
 	} else if (
 		firstDiff === 0 &&
 		original.length > 0 &&

package/src/hashline/hash.ts

@@ -1,4 +1,4 @@
-import { MAX_HASH_RETRIES } from "../constants";
+import { splitLines } from "../utils";
 import {
   loadHashStore,
   type HashStore,
@@ -6,7 +6,6 @@ import {
   upsertSnapshot,
 } from "../hash-store";
 import { xxh32, contentChecksum, initHasher } from "./hasher";
-
 export { initHasher };
 
 export const HASH_LEN = 3;
@@ -22,58 +21,111 @@ const ALPH_SAFE = ALPH.replace(/-/g, "\\-");
 const ALPH_RE = new RegExp(`^[${ALPH_SAFE}]+$`);
 export const HASH_CLASS = `[${ALPH_SAFE}]{${HASH_LEN}}`;
 
-function h2s(h: number): string {
-	const totalBits = HASH_LEN * ALPH_BITS;
-	const shift = 32 - totalBits;
-	const n = h >>> shift;
-	let out = "";
-	for (let j = 0; j < HASH_LEN; j++) {
-		out +=
-			ALPH[
-				(n >>> ((HASH_LEN - 1 - j) * ALPH_BITS)) &
-					ALPH_MASK
-			]!;
-	}
-	return out;
+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]!;
+  }
+  return out;
 }
 
+const HASH_TABLE: string[] = Array.from(
+  { length: 262_144 },
+  (_, i) => idxToHash(i),
+);
+
 export const HL_PREFIX_RE = new RegExp(
 	`^\\s*(?:>>>|>>)?\\s*${HASH_CLASS}│`,
 );
 export const HL_PREFIX_PLUS_RE = new RegExp(
 	`^\\+\\s*${HASH_CLASS}│`,
 );
+export const HL_PREFIX_MINUS_RE = new RegExp(
+	`^-(?:\\s*${HASH_CLASS}│| {${ANCHOR_LEN}}│)`,
+);
 export const DIFF_MINUS_RE = /^-\s*\d+\s{4}/;
 
 export const HL_BARE_PREFIX_RE = new RegExp(`^\\s*(${HASH_CLASS})│`);
 
-
 function canon(line: string): string {
 	return line.replace(/\r/g, "").trimEnd();
 }
 
-function nextUniqueHash(content: string, used: Set<string>): string {
-	let retry = 0;
-	let hash = h2s(xxh32(content));
-	while (used.has(hash)) {
-		retry++;
-		if (retry > MAX_HASH_RETRIES) throw new Error("Hash space exhausted");
-		hash = h2s(xxh32(`${content}:R${retry}`));
-	}
-	used.add(hash);
-	return hash;
+const BITSET_WORDS = 8192;
+
+function getBit(bits: Uint32Array, idx: number): boolean {
+  return (bits[idx >>> 5] >>> (idx & 31) & 1) !== 0;
+}
+
+function setBit(bits: Uint32Array, idx: number): void {
+  bits[idx >>> 5] |= 1 << (idx & 31);
+}
+
+function nextZeroBit(bits: Uint32Array, start: number): number {
+  const totalWords = bits.length;
+  const totalBits = totalWords * 32;
+
+  if (start >= totalBits) start = 0;
+
+  const wordIdx = start >>> 5;
+  const bitOffset = start & 31;
+
+  let word = bits[wordIdx];
+  for (let b = bitOffset; b < 32; 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++) {
+        if ((word >>> b & 1) === 0) return w * 32 + b;
+      }
+    }
+  }
+
+  for (let w = 0; w < wordIdx; w++) {
+    word = bits[w];
+    if (~word !== 0) {
+      for (let b = 0; b < 32; b++) {
+        if ((word >>> b & 1) === 0) return w * 32 + b;
+      }
+    }
+  }
+
+  word = bits[wordIdx];
+  for (let b = 0; b < bitOffset; b++) {
+    if ((word >>> b & 1) === 0) return wordIdx * 32 + b;
+  }
+
+  throw new Error("Hash space exhausted");
+}
+
+function assignHash(used: Uint32Array, baseIdx: number, hint: { value: number }): string {
+  if (!getBit(used, baseIdx)) {
+    setBit(used, baseIdx);
+    hint.value = baseIdx + 1;
+    return HASH_TABLE[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];
 }
 
 export function _lineHashesPure(content: string): string[] {
-	const lines = content.split("\n");
-	const hashes = new Array<string>(lines.length);
-	const assigned = new Set<string>();
-	for (let i = 0; i < lines.length; i++) {
-		const c = canon(lines[i]!);
-		const hash = nextUniqueHash(c, assigned);
-		hashes[i] = hash;
-	}
-	return hashes;
+  const lines = splitLines(content);
+  const hashes = new Array<string>(lines.length);
+  const used = new Uint32Array(BITSET_WORDS);
+  const hint = { value: 0 };
+
+  for (let i = 0; i < lines.length; i++) {
+    const c = canon(lines[i]!);
+    const baseIdx = xxh32(c) >>> 14;
+    hashes[i] = assignHash(used, baseIdx, hint);
+  }
+  return hashes;
 }
 
 export async function lineHashes(
@@ -96,7 +148,7 @@ export async function lineHashes(
       previous.removedHashes,
     );
     if (persist !== false) {
-      upsertSnapshot(hashStore, path, contentChecksum(content), content.split("\n").length, newHashes);
+      upsertSnapshot(hashStore, path, contentChecksum(content), splitLines(content).length, newHashes);
     }
     return newHashes;
   }
@@ -108,23 +160,41 @@ export async function lineHashes(
 
   const newHashes = _lineHashesPure(content);
   if (persist !== false) {
-    upsertSnapshot(hashStore, path, contentChecksum(content), content.split("\n").length, newHashes);
+    upsertSnapshot(hashStore, path, contentChecksum(content), splitLines(content).length, newHashes);
   }
   return newHashes;
 }
 
+function hashToIndex(hash: string): number {
+  let idx = 0;
+  for (let j = 0; j < HASH_LEN; j++) {
+    const charIdx = ALPH.indexOf(hash[j]!);
+    if (charIdx < 0) return -1;
+    idx = (idx << ALPH_BITS) | charIdx;
+  }
+  return idx;
+}
+
 function mapStableHashes(
   oldContent: string,
   oldHashes: string[],
   newContent: string,
   removedHashes?: Set<string>,
 ): string[] {
-  const newLines = newContent.split("\n");
+  const newLines = splitLines(newContent);
   const newHashes = new Array<string>(newLines.length);
-  const used = new Set<string>();
+  const used = new Uint32Array(BITSET_WORDS);
+  const hint = { value: 0 };
+
+  if (removedHashes) {
+    for (const hash of removedHashes) {
+      const idx = hashToIndex(hash);
+      if (idx >= 0) setBit(used, idx);
+    }
+  }
 
   const contentMap = new Map<string, { index: number; hash: string }[]>();
-  const oldLines = oldContent.split("\n");
+  const oldLines = splitLines(oldContent);
   for (let i = 0; i < oldLines.length; i++) {
     const line = oldLines[i]!;
     const entry = { index: i, hash: oldHashes[i]! };
@@ -155,14 +225,18 @@ function mapStableHashes(
     if (removedHashes?.has(candidates[bestIdx]!.hash)) continue;
     const match = candidates.splice(bestIdx, 1)[0]!;
     newHashes[i] = match.hash;
-    used.add(match.hash);
+    const matchIdx = hashToIndex(match.hash);
+    if (matchIdx >= 0) {
+      setBit(used, matchIdx);
+      if (matchIdx + 1 > hint.value) hint.value = matchIdx + 1;
+    }
   }
 
   for (let i = 0; i < newLines.length; i++) {
     if (newHashes[i]) continue;
     const c = canon(newLines[i]!);
-    const hash = nextUniqueHash(c, used);
-    newHashes[i] = hash;
+    const baseIdx = xxh32(c) >>> 14;
+    newHashes[i] = assignHash(used, baseIdx, hint);
   }
   return newHashes;
 }

package/src/hashline/index.ts

@@ -5,6 +5,7 @@ export {
 	HASH_CLASS,
 	HL_PREFIX_RE,
 	HL_PREFIX_PLUS_RE,
+	HL_PREFIX_MINUS_RE,
 	DIFF_MINUS_RE,
 	HL_BARE_PREFIX_RE,
 	lineHashes,

package/src/hashline/parse.ts

@@ -2,6 +2,7 @@ import {
 	ANCHOR_LEN,
 	ALPH_RE,
 	HL_PREFIX_PLUS_RE,
+	HL_PREFIX_MINUS_RE,
 	DIFF_MINUS_RE,
 } from "./hash";
 import { CONTENT_LINES_NOT_STRING_MSG } from "../constants";
@@ -46,10 +47,11 @@ function assertNoPrefixes(lines: string[]): void {
 		if (!line.length) continue;
 		if (
 			HL_PREFIX_PLUS_RE.test(line) ||
+			HL_PREFIX_MINUS_RE.test(line) ||
 			DIFF_MINUS_RE.test(line)
 		) {
 			throw new Error(
-			`[E_INVALID_PATCH] "content_lines" must contain literal file content. Offending line looks like the diff preview's +HASH│ row: ${JSON.stringify(line)}. Use literal file content only — plain + or - lines are written literally.`
+			`[E_INVALID_PATCH] "content_lines" must contain literal file content. Offending line looks like a diff preview row (e.g. +HASH│ or -HASH│): ${JSON.stringify(line)}. Use literal file content only — plain + or - lines are written literally.`
 			);
 		}
 	}

package/src/read.ts

@@ -2,8 +2,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	createReadTool,
 	formatSize,
-	DEFAULT_MAX_BYTES,
-	DEFAULT_MAX_LINES,
 	truncateHead,
 	type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
@@ -18,10 +16,7 @@ import { visLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { valAccess } from "./validation";
 
-const R_DESC = loadP("../prompts/read.md", {
-	DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
-	DEFAULT_MAX_BYTES: formatSize(DEFAULT_MAX_BYTES),
-});
+const R_DESC = loadP("../prompts/read.md");
 
 const R_SNIPPET = loadP("../prompts/read-snippet.md");
 const R_GUIDE = loadGuide("../prompts/read-guidelines.md");

package/src/replace-undo.ts

@@ -7,7 +7,7 @@ import { contentChecksum } from "./hashline/hasher";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { toCwd } from "./paths";
 import { toLF, stripBOM, genDiff, restoreEndings } from "./replace-diff";
-import { cntDiff } from "./utils";
+import { cntDiff, splitLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { buildMetrics } from "./replace-response";
 export interface UndoEntry {
@@ -84,7 +84,7 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
         );
 
         const store = await loadHashStore();
-        upsertSnapshot(store, mutationTargetPath, contentChecksum(undo.content), undo.content.split("\n").length, undo.hashes);
+        upsertSnapshot(store, mutationTargetPath, contentChecksum(undo.content), splitLines(undo.content).length, undo.hashes);
 
         clearUndo(mutationTargetPath);
 

package/src/replace.ts

@@ -68,7 +68,7 @@ const changeItemSchema = Type.Object(
 
 export const editToolSchema = Type.Object(
   {
-    changes: Type.Array(changeItemSchema, { description: "Array of edits. Each edit pairs content_lines (literal file content, one string per line) with hash_range_inclusive (inclusive [start_hash, end_hash] — pair of 3-char hashes from read output)." }),
+    changes: Type.Array(changeItemSchema, { description: "Array of edits applied atomically against the same pre-edit snapshot." }),
     path: Type.String({ description: "Path to edit" }),
   },
   { additionalProperties: false },
@@ -117,6 +117,19 @@ interface PipelineResult {
 
 const ROOT_KS = new Set(["path", "changes", "content_lines", "hash_range_inclusive"]);
 
+const LEGACY_KS = ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines"];
+
+export function assertNoLegacyKeys(request: unknown): void {
+  if (!isRec(request)) return;
+  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>"]}.`
+      );
+    }
+  }
+}
+
 export function assertReq(
   request: unknown,
   flat?: boolean
@@ -125,13 +138,7 @@ export function assertReq(
     throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
   }
 
-  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 {content_lines: [...], hash_range_inclusive: ["<START>", "<END>"]}.`
-      );
-    }
-  }
+  assertNoLegacyKeys(request);
 
   rejectUnknownFields(request, ROOT_KS, "Edit request");
 
@@ -148,6 +155,7 @@ export function assertReq(
     throw new Error('[E_BAD_SHAPE] Edit request requires a "changes" array. Each change is { content_lines: [...], hash_range_inclusive: ["<START>", "<END>"] }.');
   }
 }
+
 export interface ExecPipelineOptions {
   accessMode?: number;
   signal?: AbortSignal;
@@ -155,6 +163,46 @@ export interface ExecPipelineOptions {
   noPersist?: boolean;
 }
 
+function collectRemovedHashes(
+  resolved: { hash_range_inclusive: [{ hash: string }, { hash: string }] }[],
+  originalHashes: string[],
+): Set<string> {
+  const removedHashes = new Set<string>();
+  for (const edit of resolved) {
+    const startHash = edit.hash_range_inclusive[0].hash;
+    const endHash = edit.hash_range_inclusive[1].hash;
+    const startLine = originalHashes.indexOf(startHash);
+    const endLine = originalHashes.indexOf(endHash);
+    if (startLine >= 0 && endLine >= 0) {
+      for (let i = startLine; i <= endLine; i++) {
+        removedHashes.add(originalHashes[i]!);
+      }
+    }
+  }
+  return removedHashes;
+}
+
+function countLineChanges(
+  resolved: { hash_range_inclusive: [{ hash: string }, { hash: string }]; content_lines: string[] }[],
+  originalHashes: string[],
+  noopEdits: { editIndex: number }[] | undefined,
+): { totalAddedLines: number; totalRemovedLines: number } {
+  let totalAddedLines = 0;
+  let totalRemovedLines = 0;
+  const noopIndices = new Set(noopEdits?.map((n) => n.editIndex) ?? []);
+  for (let i = 0; i < resolved.length; i++) {
+    if (noopIndices.has(i)) continue;
+    const edit = resolved[i]!;
+    const startLine = originalHashes.indexOf(edit.hash_range_inclusive[0].hash);
+    const endLine = originalHashes.indexOf(edit.hash_range_inclusive[1].hash);
+    if (startLine >= 0 && endLine >= 0) {
+      totalRemovedLines += endLine - startLine + 1;
+    }
+    totalAddedLines += edit.content_lines.length;
+  }
+  return { totalAddedLines, totalRemovedLines };
+}
+
 export async function execPipeline(
   params: ReqParams,
   cwd: string,
@@ -187,18 +235,7 @@ export async function execPipeline(
 
   const result = anchorResult.content;
 
-  const removedHashes = new Set<string>();
-  for (const edit of resolved) {
-    const startHash = edit.hash_range_inclusive[0].hash;
-    const endHash = edit.hash_range_inclusive[1].hash;
-    const startLine = originalHashes.indexOf(startHash);
-    const endLine = originalHashes.indexOf(endHash);
-    if (startLine >= 0 && endLine >= 0) {
-      for (let i = startLine; i <= endLine; i++) {
-        removedHashes.add(originalHashes[i]!);
-      }
-    }
-  }
+  const removedHashes = collectRemovedHashes(resolved, originalHashes);
 
   const noPersist = options?.noPersist;
   const resultHashes = await lineHashes(result, absolutePath, {
@@ -209,19 +246,9 @@ export async function execPipeline(
 
   const warnings = [...(anchorResult.warnings ?? [])];
 
-  let totalAddedLines = 0;
-  let totalRemovedLines = 0;
-  const noopIndices = new Set(anchorResult.noopEdits?.map((n) => n.editIndex) ?? []);
-  for (let i = 0; i < resolved.length; i++) {
-    if (noopIndices.has(i)) continue;
-    const edit = resolved[i]!;
-    const startLine = originalHashes.indexOf(edit.hash_range_inclusive[0].hash);
-    const endLine = originalHashes.indexOf(edit.hash_range_inclusive[1].hash);
-    if (startLine >= 0 && endLine >= 0) {
-      totalRemovedLines += endLine - startLine + 1;
-    }
-    totalAddedLines += edit.content_lines.length;
-  }
+  const { totalAddedLines, totalRemovedLines } = countLineChanges(
+    resolved, originalHashes, anchorResult.noopEdits,
+  );
 
   return {
     path,
@@ -249,6 +276,11 @@ export async function compPreview(
 ): Promise<RPreview> {
   try {
     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.`
+      };
+    }
     assertReq(normalized, flat);
     const { path, originalNormalized, originalHashes, result, resultHashes } = await execPipeline(
       normalized,
@@ -289,27 +321,12 @@ export function reuseMarkdown(context: any, content: string, theme: any): Markdo
   m.setText(content);
   return m;
 }
+
 const MODE_CFG = {
   flat: {
-    desc: " Only one edit per call. The `hash_range_inclusive` and `content_lines` fields sit at the top level of the request object.",
-    examples: [
-      "", "Single line:", "{ \"content_lines\": [\"const x = 1;\"], \"hash_range_inclusive\": [\"MQX\", \"MQX\"], \"path\": \"src/main.ts\" }", "", "Range replace:", "{ \"content_lines\": [\"function greet() {\", \"  return 1;\", \"}\"], \"hash_range_inclusive\": [\"ZPM\", \"VRW\"], \"path\": \"src/main.ts\" }",
-    ].join("\n"),
-    rules: "",
-    requestStructure: [
-      "Flat mode:", "```json", "{ \"content_lines\": [...], \"hash_range_inclusive\": [\"aB3\", \"xY7\"], \"path\": \"...\" }", "```",
-    ].join("\n"),
     prefix: "performing one edit per call",
   },
   bulk: {
-    desc: "\n\nPut all operations on one file in a single `replace` call. Stack every region into the `changes` array, even when they are far apart. Anchors within one call must all come from the same pre-edit read; the runtime applies them atomically against that one snapshot.",
-    examples: [
-      "", "Single line:", "{ \"changes\": [{ \"content_lines\": [\"const x = 1;\"], \"hash_range_inclusive\": [\"MQX\", \"MQX\"] }], \"path\": \"src/main.ts\" }", "", "Range replace:", "{ \"changes\": [{ \"content_lines\": [\"function greet() {\", \"  return 1;\", \"}\"], \"hash_range_inclusive\": [\"ZPM\", \"VRW\"] }], \"path\": \"src/main.ts\" }",
-    ].join("\n"),
-    rules: "- Multiple edits in one call must not overlap. Overlapping ranges are rejected with [E_EDIT_CONFLICT].",
-    requestStructure: [
-      "Bulk mode (default):", "```json", "{ \"changes\": [{ \"content_lines\": [...], \"hash_range_inclusive\": [\"aB3\", \"xY7\"] }], \"path\": \"...\" }", "```",
-    ].join("\n"),
     prefix: "batching all changes to a file in one call",
   },
 } as const;
@@ -334,6 +351,7 @@ export function buildToolDef(opts: { flat: boolean; autoRead?: boolean }): ToolD
     promptGuidelines: E_GUIDE,
     prepareArguments: opts.flat
       ? (args: unknown) => {
+          assertNoLegacyKeys(args);
           if (!isRec(args)) return args as any;
           const record = { ...args };
           normalizeFilePath(record);
@@ -342,8 +360,10 @@ export function buildToolDef(opts: { flat: boolean; autoRead?: boolean }): ToolD
           }
           return record;
         }
-      : (args: unknown) =>
-          normReq(args) as ReqParams,
+      : (args: unknown) => {
+          assertNoLegacyKeys(args);
+          return normReq(args) as ReqParams;
+        },
     renderShell: "default",
     renderCall(args, theme, context) {
       const previewInput = getPreviewInput(args);
@@ -435,7 +455,6 @@ export function buildToolDef(opts: { flat: boolean; autoRead?: boolean }): ToolD
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const canonical = normReq(params);
 
-
       const normalizedParams = canonical as { path: string; changes: HTEdit[] };
       const path = normalizedParams.path;
       const absolutePath = toCwd(path, ctx.cwd);

package/src/utils.ts

@@ -6,6 +6,12 @@ export function has(record: Record<string, unknown>, key: string): boolean {
 	return Object.hasOwn(record, key);
 }
 
+export function splitLines(text: string): string[] {
+  if (text.length === 0) return [""];
+  const lines = text.split("\n");
+  return text.endsWith("\n") ? lines.slice(0, -1) : lines;
+}
+
 export function visLines(text: string): string[] {
   if (text.length === 0) return [];
   const lines = text.split("\n");