pi-hashline-edit-pro 0.18.1 → 0.18.3

package/README.md

@@ -94,7 +94,7 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 
 ### Stable hashing across edits
 
-Hashes are now computed with a persistent store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) that preserves hashes for unchanged lines across edits. When you replace lines in a file, the runtime maps the old content against the new content and copies hashes for unchanged lines to their new positions. This means editing one part of a file does not change the hashes of unrelated lines elsewhere — the model can keep using previously seen anchors for untouched regions.
+Hashes are now computed with a persistent store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) that preserves hashes for unchanged lines across edits. When you replace lines in a file, the runtime maps the old content against the new content and copies hashes for unchanged lines to their new positions. This means editing one part of a file does not change the hashes of unrelated lines elsewhere — the model can keep using previously seen anchors for untouched regions. A replace that produces identical content (a no-op, reported as "No changes made") never rotates hashes: no file change means no anchor change, so previously read anchors remain valid after a no-op.
 
 The store is a SQLite database (WAL journal mode) keyed by canonical file path. Each snapshot stores a 64-bit content checksum (`xxhash64`) plus the per-line hashes, not the full text, so a cache hit is a single keyed lookup and a one-row write. Reads, replaces, undo, and pruning all share one transactional store, so concurrent Pi sessions editing different files never silently clobber each other's snapshots (per-path writers serialize via `BEGIN IMMEDIATE`; same-path concurrent edits still fail safe — stale anchors are rejected by content matching). Stale snapshots (for files that no longer exist) are pruned on session start.
 
@@ -138,16 +138,34 @@ Settings are stored in `~/.config/pi-hashline-edit-pro/config.json`:
 
 The file is created automatically when any setting is toggled. Both fields are independent — toggling one never clobbers the other.
 
+### Error codes
+
+| Code | Meaning |
+| --- | --- |
+| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields. |
+| `[E_BAD_REF]` | An anchor in `hash_range_inclusive` is not a bare 3-char hash. |
+| `[E_STALE_ANCHOR]` | An anchor does not match any line in the current file; call `read` for fresh anchors. |
+| `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
+| `[E_INVALID_PATCH]` | `content_lines` contains diff-preview rows (`+HASH│`, `-HASH│`, `-   │`, `-N   `). |
+| `[E_BARE_HASH_PREFIX]` | A `content_lines` entry starts with a hash-like `HASH│` prefix. |
+| `[E_LEGACY_SHAPE]` | The request uses the unsupported `oldText`/`newText` dialect. |
+| `[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. |
+
 ## 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.
 - **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.
 - **Flat mode normalization.** When flat mode is active, the tool's `execute` function wraps the top-level `hash_range_inclusive` and `content_lines` into a single-element `changes` array internally, then runs the same pipeline as bulk mode. The `normReq` function in `replace-normalize.ts` also handles flat format directly, so any code path that normalizes input (e.g. `compPreview`) works with both formats.
-- **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.
+- **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.
@@ -160,6 +178,8 @@ Before hashing, each line is normalized: carriage returns are stripped and trail
 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).
+
 ### Bare-prefix detector
 
 With the `│` delimiter format, the bare-prefix detector regex `^\s*([A-Za-z0-9_\-]{3})│` is highly specific. It only matches lines starting with a hash-like prefix. This eliminates false positives from common code patterns like `init:`, `data:`, `else:`, etc. The detector rejects edit lines matching this pattern with `[E_BARE_HASH_PREFIX]` to prevent the model from accidentally pasting hash anchors into file content.

package/index.ts

@@ -1,10 +1,11 @@
 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";
+import { MAX_HASH_LINES } from "./src/hashline";
 import {
   readConfig,
   toggleReplaceMode,
@@ -12,7 +13,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,16 +75,27 @@ 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;
     if (typeof filePath !== "string") return;
 
     try {
-      const { normalized, fileHashes, absolutePath } = await readNormFile(filePath, ctx.cwd);
-
+      const { normalized, fileHashes, absolutePath } = await readNormFile(
+        filePath, ctx.cwd, { maxLines: MAX_HASH_LINES },
+      );
       if (visLines(normalized).length === 0) return;
 
       const preview = await fmtReadPreview(normalized, { limit: AUTO_READ_MAX }, fileHashes, absolutePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "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

@@ -0,0 +1 @@
+- `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/config.ts

@@ -1,6 +1,7 @@
-import { readFile, writeFile, mkdir } from "fs/promises";
-import { configDir, configPath } from "./paths";
+import { readFile } from "fs/promises";
+import { configPath } from "./paths";
 import { errCode } from "./utils";
+import { writeAtomic } from "./fs-write";
 
 export type ReplaceMode = "bulk" | "flat";
 export interface Config {
@@ -32,8 +33,7 @@ export async function readConfig(): Promise<Config> {
   }
 }
 export async function writeConfig(config: Config): Promise<void> {
-  await mkdir(configDir(), { recursive: true });
-  await writeFile(configPath(), JSON.stringify(config, null, 2), "utf-8");
+  await writeAtomic(configPath(), JSON.stringify(config, null, 2));
 }
 
 

package/src/constants.ts

@@ -2,9 +2,6 @@ export const AUTO_READ_MAX = 2000;
 export const SNIFF_BYTES = 8192;
 export const MAX_BYTES = 100 * 1024 * 1024;
 
-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 = 3;
 export const CONTENT_LINES_NOT_STRING_MSG =

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/fs-write.ts

@@ -3,6 +3,7 @@ import {
 	lstat,
 	mkdir,
 	open,
+	readdir,
 	readlink,
 	rename,
 	rm,
@@ -71,6 +72,44 @@ export async function resolveTarget(path: string): Promise<string> {
   return resParts(root, parts);
 }
 
+const TEMP_PREFIX = ".tmp-";
+const STALE_TEMP_MS = 60 * 60 * 1000;
+const sweptDirs = new Set<string>();
+
+async function sweepStaleTemps(dir: string): Promise<void> {
+  if (sweptDirs.has(dir)) return;
+  sweptDirs.add(dir);
+  try {
+    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;
+      const tempPath = join(dir, entry.name);
+      try {
+        const stats = await stat(tempPath);
+        if (now - stats.mtimeMs > STALE_TEMP_MS) {
+          await rm(tempPath, { force: true });
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+
+async function syncDir(dir: string): Promise<void> {
+  if (process.platform === "win32") return;
+  try {
+    const handle = await open(dir, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } catch {
+  }
+}
+
 export async function writeAtomic(
   path: string,
   content: string,
@@ -92,7 +131,8 @@ export async function writeAtomic(
   }
 
   const dir = dirname(targetPath);
-  const tempPath = join(dir, `.tmp-${randomUUID()}`);
+  await sweepStaleTemps(dir);
+  const tempPath = join(dir, `${TEMP_PREFIX}${randomUUID()}`);
   await mkdir(dir, { recursive: true });
   const tempHandle = await open(tempPath, "wx", 0o600);
   try {
@@ -100,6 +140,7 @@ export async function writeAtomic(
     if (existingStats) {
       await tempHandle.chmod(existingStats.mode & 0o7777);
     }
+    await tempHandle.sync();
   } catch (error: unknown) {
     await tempHandle.close();
     try { await rm(tempPath, { force: true }); } catch {}
@@ -108,12 +149,13 @@ export async function writeAtomic(
   try {
     await tempHandle.close();
     await rename(tempPath, targetPath);
+    await syncDir(dir);
   } catch (error: unknown) {
     if (errCode(error) === "EXDEV") {
       try {
-        await tempHandle.close();
         await copyFile(tempPath, targetPath);
         await rm(tempPath, { force: true });
+        await syncDir(dir);
         return;
       } catch {
         try { await rm(tempPath, { force: true }); } catch {}

package/src/hash-store.ts

@@ -40,8 +40,7 @@ let exitHandlerRegistered = false;
 function openDb(storePath: string): { db: DatabaseSync; stmts: Prepared } {
   const db = new DatabaseSync(storePath, {
     timeout: HASH_STORE_BUSY_TIMEOUT,
-    defensive: false,
-  } as any);
+  });
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA synchronous = NORMAL");
   db.exec(
@@ -72,6 +71,36 @@ function openDb(storePath: string): { db: DatabaseSync; stmts: Prepared } {
   return { db, stmts };
 }
 
+function isHealthy(db: DatabaseSync): boolean {
+  try {
+    const row = db.prepare("PRAGMA quick_check").get() as { quick_check?: string } | undefined;
+    return row?.quick_check === "ok";
+  } catch {
+    return false;
+  }
+}
+
+async function quarantineStore(storePath: string): Promise<void> {
+  const suffix = `.corrupt-${Date.now()}`;
+  for (const candidate of [storePath, `${storePath}-wal`, `${storePath}-shm`]) {
+    try {
+      await rename(candidate, `${candidate}${suffix}`);
+    } catch (error) {
+      if (errCode(error) !== "ENOENT") {
+        console.error("Failed to quarantine corrupt hash store file:", error);
+      }
+    }
+  }
+}
+
+function shutdownDb(db: DatabaseSync): void {
+  try {
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  } catch {
+  }
+  db.close();
+}
+
 export async function loadHashStore(): Promise<HashStore> {
   const storePath = hashStorePath();
   if (cachedDb && cachedDb.path === storePath && cachedDb.db.isOpen) {
@@ -83,13 +112,27 @@ export async function loadHashStore(): Promise<HashStore> {
   await initHasher();
   await mkdir(hashStoreDir(), { recursive: true });
 
-  const existed = existsSync(storePath);
-  const { db, stmts } = openDb(storePath);
+  let existed = existsSync(storePath);
+  let opened: { db: DatabaseSync; stmts: Prepared };
+  try {
+    opened = openDb(storePath);
+  } catch (error) {
+    console.error("Hash store failed to open, rebuilding:", error);
+    await quarantineStore(storePath);
+    existed = false;
+    opened = openDb(storePath);
+  }
+  if (!isHealthy(opened.db)) {
+    shutdownDb(opened.db);
+    await quarantineStore(storePath);
+    existed = false;
+    opened = openDb(storePath);
+  }
+  const { db, stmts } = opened;
 
   if (!existed) {
     await migrateLegacy(db);
   }
-
   cachedDb = { path: storePath, db, stmts };
 
   if (!exitHandlerRegistered) {
@@ -108,11 +151,7 @@ export async function loadHashStore(): Promise<HashStore> {
 
 export function shutdownHashStore(): void {
   if (cachedDb) {
-    try {
-      cachedDb.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
-    } catch {
-    }
-    cachedDb.db.close();
+    shutdownDb(cachedDb.db);
     cachedDb = null;
   }
 }

package/src/hashline/hash.ts

@@ -21,6 +21,9 @@ const ALPH_SAFE = ALPH.replace(/-/g, "\\-");
 const ALPH_RE = new RegExp(`^[${ALPH_SAFE}]+$`);
 export const HASH_CLASS = `[${ALPH_SAFE}]{${HASH_LEN}}`;
 
+export const HASH_SPACE = ALPH.length ** HASH_LEN;
+export const MAX_HASH_LINES = HASH_SPACE;
+
 function idxToHash(idx: number): string {
   let out = "";
   for (let j = 0; j < HASH_LEN; j++) {
@@ -30,7 +33,7 @@ function idxToHash(idx: number): string {
 }
 
 const HASH_TABLE: string[] = Array.from(
-  { length: 262_144 },
+  { length: HASH_SPACE },
   (_, i) => idxToHash(i),
 );
 
@@ -40,6 +43,9 @@ export const HL_PREFIX_RE = new RegExp(
 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})│`);
@@ -48,7 +54,7 @@ function canon(line: string): string {
 	return line.replace(/\r/g, "").trimEnd();
 }
 
-const BITSET_WORDS = 8192;
+const BITSET_WORDS = Math.ceil(HASH_SPACE / 32);
 
 function getBit(bits: Uint32Array, idx: number): boolean {
   return (bits[idx >>> 5] >>> (idx & 31) & 1) !== 0;
@@ -95,7 +101,9 @@ function nextZeroBit(bits: Uint32Array, start: number): number {
     if ((word >>> b & 1) === 0) return wordIdx * 32 + b;
   }
 
-  throw new Error("Hash space exhausted");
+  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.`,
+  );
 }
 
 function assignHash(used: Uint32Array, baseIdx: number, hint: { value: number }): string {
@@ -172,6 +180,47 @@ function hashToIndex(hash: string): number {
   return idx;
 }
 
+function findNearestCandidate(
+  candidates: { index: number; hash: string }[],
+  target: number,
+  removedHashes?: Set<string>,
+): number {
+  let lo = 0;
+  let hi = candidates.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (candidates[mid]!.index < target) lo = mid + 1;
+    else hi = mid;
+  }
+  let left = lo - 1;
+  let right = lo;
+  while (left >= 0 || right < candidates.length) {
+    let bestPos = -1;
+    let bestDist = Infinity;
+    if (left >= 0) {
+      const candidate = candidates[left]!;
+      if (!removedHashes?.has(candidate.hash)) {
+        bestPos = left;
+        bestDist = target - candidate.index;
+      }
+    }
+    if (right < candidates.length) {
+      const candidate = candidates[right]!;
+      if (!removedHashes?.has(candidate.hash)) {
+        const dist = candidate.index - target;
+        if (dist < bestDist) {
+          bestPos = right;
+          bestDist = dist;
+        }
+      }
+    }
+    if (bestPos >= 0) return bestPos;
+    left--;
+    right++;
+  }
+  return -1;
+}
+
 function mapStableHashes(
   oldContent: string,
   oldHashes: string[],
@@ -208,18 +257,8 @@ function mapStableHashes(
     const candidates = contentMap.get(line);
     if (!candidates || candidates.length === 0) continue;
 
-    let bestIdx = 0;
-    let bestDist = Infinity;
-    for (let j = 0; j < candidates.length; j++) {
-      if (removedHashes?.has(candidates[j]!.hash)) continue;
-      const dist = Math.abs(candidates[j]!.index - i);
-      if (dist < bestDist) {
-        bestDist = dist;
-        bestIdx = j;
-      }
-    }
-
-    if (removedHashes?.has(candidates[bestIdx]!.hash)) continue;
+    const bestIdx = findNearestCandidate(candidates, i, removedHashes);
+    if (bestIdx < 0) continue;
     const match = candidates.splice(bestIdx, 1)[0]!;
     newHashes[i] = match.hash;
     const matchIdx = hashToIndex(match.hash);

package/src/hashline/index.ts

@@ -3,8 +3,11 @@ export {
 	ANCHOR_LEN,
 	HASH_SEP,
 	HASH_CLASS,
+	HASH_SPACE,
+	MAX_HASH_LINES,
 	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,15 +2,13 @@ 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";
 import { Type } from "typebox";
 import { loadFileKindAndText } from "./file-kind";
 import { readNormFile } from "./file-reader";
-import { lineHashes, fmtRegion, HASH_SEP } from "./hashline";
+import { lineHashes, fmtRegion, HASH_SEP, MAX_HASH_LINES } from "./hashline";
 import { toCwd } from "./paths";
 import { abortIf } from "./utils";
 import { fileSnap } from "./file-reader";
@@ -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");
@@ -164,7 +159,7 @@ export function regRead(pi: ExtensionAPI): void {
 				return executeBuiltinRead(_toolCallId, params, signal, _onUpdate, ctx);
 			}
       const { normalized, fileHashes, hadUtf8DecodeErrors } = await readNormFile(
-        rawPath, ctx.cwd, { signal, preloadedFile: file },
+        rawPath, ctx.cwd, { signal, preloadedFile: file, maxLines: MAX_HASH_LINES },
       );
 			const preview = await fmtReadPreview(
 				normalized,

package/src/replace.ts

@@ -13,12 +13,11 @@ import {
 import { readNormFile } from "./file-reader";
 import { normReq, normalizeFilePath, tryParseContentLines } from "./replace-normalize";
 import { isRec, has, rejectUnknownFields, abortIf } from "./utils";
-import { MAX_HASH_LINES } from "./constants";
 import { resolveTarget, writeAtomic } from "./fs-write";
-import {
-  applyEdits,
+import { applyEdits,
   lineHashes,
   resEdits,
+  MAX_HASH_LINES,
   type HTEdit,
 } from "./hashline";
 import { toCwd } from "./paths";
@@ -68,7 +67,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 +116,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 +137,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");
 
@@ -159,9 +165,11 @@ export interface ExecPipelineOptions {
 function collectRemovedHashes(
   resolved: { hash_range_inclusive: [{ hash: string }, { hash: string }] }[],
   originalHashes: string[],
+  skipIndices?: Set<number>,
 ): Set<string> {
   const removedHashes = new Set<string>();
-  for (const edit of resolved) {
+  for (const [index, edit] of resolved.entries()) {
+    if (skipIndices?.has(index)) continue;
     const startHash = edit.hash_range_inclusive[0].hash;
     const endHash = edit.hash_range_inclusive[1].hash;
     const startLine = originalHashes.indexOf(startHash);
@@ -227,16 +235,20 @@ export async function execPipeline(
   );
 
   const result = anchorResult.content;
-
-  const removedHashes = collectRemovedHashes(resolved, originalHashes);
+  const isNoop = result === originalNormalized;
 
   const noPersist = options?.noPersist;
-  const resultHashes = await lineHashes(result, absolutePath, {
-    content: originalNormalized,
-    hashes: originalHashes,
-    removedHashes,
-  }, hashStore, noPersist !== true);
-
+  const noopIndices = new Set(anchorResult.noopEdits?.map((n) => n.editIndex) ?? []);
+  const removedHashes = isNoop
+    ? undefined
+    : collectRemovedHashes(resolved, originalHashes, noopIndices);
+  const resultHashes = isNoop
+    ? originalHashes
+    : await lineHashes(result, absolutePath, {
+        content: originalNormalized,
+        hashes: originalHashes,
+        removedHashes,
+      }, hashStore, noPersist !== true);
   const warnings = [...(anchorResult.warnings ?? [])];
 
   const { totalAddedLines, totalRemovedLines } = countLineChanges(
@@ -269,6 +281,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,
@@ -312,25 +329,9 @@ export function reuseMarkdown(context: any, content: string, theme: any): Markdo
 
 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;
@@ -355,6 +356,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);
@@ -363,8 +365,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);