pi-hashline-edit-pro 0.16.11 → 0.16.12

package/index.ts

@@ -1,28 +1,31 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { readFile } from "fs/promises";
-import { join, isAbsolute } from "path";
 import { initHasher } from "./src/hashline";
-import { regReplace } from "./src/replace";
-import { regReplaceFlat } from "./src/replace-flat";
+import { regReplace, regReplaceFlat } from "./src/replace";
 import { regReplaceUndo } from "./src/replace-undo";
 import { regRead, fmtReadPreview } from "./src/read";
-import { toLF, stripBOM } from "./src/replace-diff";
-import { resolveTarget } from "./src/fs-write";
 import { visLines } from "./src/utils";
 import { AUTO_READ_MAX } from "./src/constants";
 import {
-  readReplaceMode,
+  readConfig,
   toggleReplaceMode,
-  readAutoRead,
   toggleAutoRead,
 } from "./src/config";
 import { loadHashStore, pruneHashStore } from "./src/hash-store";
+import { readNormFile } from "./src/file-reader";
 
 export default function (pi: ExtensionAPI): void {
   regRead(pi);
 
   regReplace(pi);
   regReplaceUndo(pi);
+
+function registerReplaceTool(pi: ExtensionAPI, mode: string, autoRead?: boolean): void {
+  if (mode === "flat") {
+    regReplaceFlat(pi, autoRead);
+  } else {
+    regReplace(pi, autoRead);
+  }
+}
   const debugValue = process.env.PI_HASHLINE_DEBUG;
   const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;
   let autoRead = autoReadValue === "1" || autoReadValue === "true";
@@ -37,14 +40,11 @@ export default function (pi: ExtensionAPI): void {
     } catch (err) {
       console.error("Failed to load or prune hash store:", err);
     }
-    const mode = await readReplaceMode();
-    if (mode === "flat") {
-      regReplaceFlat(pi);
-    } else {
-      regReplace(pi);
-    }
+    const config = await readConfig();
+    const mode = config.replaceMode;
+    autoRead = config.autoRead;
+    registerReplaceTool(pi, mode, autoRead);
 
-    autoRead = await readAutoRead();
 
     if (debugValue === "1" || debugValue === "true") {
       ctx.ui.notify(`Hashline Edit mode active (${mode} replace)`, "info");
@@ -55,11 +55,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();
-      if (mode === "flat") {
-        regReplaceFlat(pi);
-      } else {
-        regReplace(pi);
-      }
+      registerReplaceTool(pi, mode, autoRead);
       ctx.ui.notify(`Replace mode switched to: ${mode}`, "info");
     },
   });
@@ -68,12 +64,8 @@ export default function (pi: ExtensionAPI): void {
     description: "Toggle automatic hashline anchors after write and replace operations",
     handler: async (_args, ctx) => {
       autoRead = await toggleAutoRead();
-      const mode = await readReplaceMode();
-      if (mode === "flat") {
-        regReplaceFlat(pi);
-      } else {
-        regReplace(pi);
-      }
+      const mode = (await readConfig()).replaceMode;
+      registerReplaceTool(pi, mode, autoRead);
       const state = autoRead ? "enabled" : "disabled";
       ctx.ui.notify(`Auto-read after write/replace: ${state}`, "info");
     },
@@ -88,15 +80,11 @@ export default function (pi: ExtensionAPI): void {
     if (typeof filePath !== "string") return;
 
     try {
-      const absolutePath = isAbsolute(filePath) ? filePath : join(ctx.cwd, filePath);
-      const resolvedPath = await resolveTarget(absolutePath);
-      const content = await readFile(resolvedPath, "utf-8");
-      const { text: rawContent } = stripBOM(content);
-      const normalized = toLF(rawContent);
+      const { normalized, fileHashes, absolutePath } = await readNormFile(filePath, ctx.cwd, undefined);
 
       if (visLines(normalized).length === 0) return;
 
-      const preview = await fmtReadPreview(normalized, { limit: AUTO_READ_MAX }, undefined, resolvedPath);
+      const preview = await fmtReadPreview(normalized, { limit: AUTO_READ_MAX }, fileHashes, absolutePath);
 
       return {
         content: [

package/package.json

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

package/prompts/read.md

@@ -1,5 +1,7 @@
 Read a text file. Each line is returned as `HASH│content`.
 
+Key rule: line numbers are NOT part of the output. Use the 3-char HASH to reference lines in replace calls. A HASH may change when the line content changes.
+
 HASH format:
 - The HASH is 3 characters from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `aB3`, `4yN`, `-qk`).
 - The content after the `│` separator is the line verbatim.

package/prompts/replace-guidelines.md

@@ -0,0 +1,6 @@
+{{MODE_PREFIX}}
+- After a successful replace, the response shows the change summary. {{AUTO_READ_GUIDANCE}}
+- On [E_STALE_ANCHOR], call read to get fresh anchors, copy the 3-character HASH of the start and end of the range into hash_range_inclusive, and retry.
+- hash_range_inclusive replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put replacement lines in content_lines — do not include lines that already exist outside the range.
+- Preserve leading whitespace exactly. The content after │ in read output includes all leading spaces and tabs — copy them into content_lines unchanged.
+- content_lines must be a native JSON array of strings, not a JSON string.

package/prompts/replace-snippet.md

@@ -0,0 +1 @@
+Replace lines in a text file via HASH anchors from read, {{MODE_PREFIX}}

package/prompts/replace.md

@@ -0,0 +1,33 @@
+Replace lines in a text file using HASH anchors from `read`.{{MODE_DESCRIPTION}}
+
+Workflow:
+1. Call `read` to get `HASH│content` lines for the file.
+2. Identify the range to replace using the 3-char hashes from the read output.
+3. Call `replace` with `hash_range_inclusive` (the two hashes) and `content_lines` (the new lines).
+4. On `[E_STALE_ANCHOR]`, call `read` again for fresh anchors, then retry.
+5. On success, call `read` to get fresh anchors for follow-up edits.
+
+Request structure:
+{{MODE_REQUEST_STRUCTURE}}
+
+Fields:
+- content_lines — replacement lines as a JSON array of strings. File content only — no HASH│ prefix.
+- hash_range_inclusive — [start_hash, end_hash] from read output. 3-char base64 hash only — no │ or line content.
+- path — file to edit.
+
+Examples:
+{{MODE_EXAMPLES}}
+
+Rules:
+- Anchors must be 3-char base64 hashes from the most recent read. Stale anchors fail with [E_STALE_ANCHOR].
+- The range is inclusive: every line from start_hash through end_hash is deleted.
+- Those lines are replaced with content_lines — nothing is inserted, nothing is appended.
+- content_lines is literal file content. Never include the HASH│ prefix — that goes in hash_range_inclusive.
+- content_lines must be a native JSON array of strings, not a serialized string.
+- Preserve leading whitespace exactly as it appears after │ in read output.
+- To delete lines, use content_lines: [].
+- If content_lines matches current content, the edit is a noop (file unchanged).
+{{MODE_RULES}}
+On success, the response shows the change summary. {{AUTO_READ_GUIDANCE}}
+
+Recovery: If a replace produces incorrect results, call undo_last_replace with the file path to revert.

package/src/config.ts

@@ -1,10 +1,8 @@
-import { readFileSync } from "fs";
 import { readFile, writeFile, mkdir } from "fs/promises";
 import { configDir, configPath } from "./paths";
-import { errCode } from "./validation";
+import { errCode } from "./utils";
 
 export type ReplaceMode = "bulk" | "flat";
-
 export interface Config {
   replaceMode: ReplaceMode;
   autoRead: boolean;
@@ -15,14 +13,17 @@ const DEFAULT_CONFIG: Config = {
   autoRead: false
 };
 
+function parseConfig(content: string): Config {
+  const parsed = JSON.parse(content) as Partial<Config>;
+  return {
+    replaceMode: parsed.replaceMode === "flat" ? "flat" : "bulk",
+    autoRead: parsed.autoRead === true,
+  };
+}
 export async function readConfig(): Promise<Config> {
   try {
     const content = await readFile(configPath(), "utf-8");
-    const parsed = JSON.parse(content) as Partial<Config>;
-    return {
-      replaceMode: parsed.replaceMode === "flat" ? "flat" : "bulk",
-      autoRead: parsed.autoRead === true,
-    };
+    return parseConfig(content);
   } catch (error: unknown) {
     if (errCode(error) !== "ENOENT") {
       console.error("Config file corrupted, using defaults:", error);
@@ -30,38 +31,11 @@ export async function readConfig(): Promise<Config> {
     return { ...DEFAULT_CONFIG };
   }
 }
-
-export function readConfigSync(): Config {
-  try {
-    const content = readFileSync(configPath(), "utf-8");
-    const parsed = JSON.parse(content) as Partial<Config>;
-    return {
-      replaceMode: parsed.replaceMode === "flat" ? "flat" : "bulk",
-      autoRead: parsed.autoRead === true,
-    };
-  } catch (error: unknown) {
-    if (errCode(error) !== "ENOENT") {
-      console.error("Config file corrupted, using defaults:", error);
-    }
-    return { ...DEFAULT_CONFIG };
-  }
-}
-
 export async function writeConfig(config: Config): Promise<void> {
   await mkdir(configDir(), { recursive: true });
   await writeFile(configPath(), JSON.stringify(config, null, 2), "utf-8");
 }
 
-export async function readReplaceMode(): Promise<ReplaceMode> {
-  const config = await readConfig();
-  return config.replaceMode;
-}
-
-export async function writeReplaceMode(mode: ReplaceMode): Promise<void> {
-  const config = await readConfig();
-  config.replaceMode = mode;
-  await writeConfig(config);
-}
 
 export async function toggleReplaceMode(): Promise<ReplaceMode> {
   const config = await readConfig();
@@ -70,21 +44,6 @@ export async function toggleReplaceMode(): Promise<ReplaceMode> {
   return config.replaceMode;
 }
 
-export async function readAutoRead(): Promise<boolean> {
-  const config = await readConfig();
-  return config.autoRead;
-}
-
-export function readAutoReadSync(): boolean {
-  const config = readConfigSync();
-  return config.autoRead;
-}
-
-export async function writeAutoRead(value: boolean): Promise<void> {
-  const config = await readConfig();
-  config.autoRead = value;
-  await writeConfig(config);
-}
 
 export async function toggleAutoRead(): Promise<boolean> {
   const config = await readConfig();

package/src/file-reader.ts

@@ -1,12 +1,14 @@
 import { constants } from "fs";
+import { stat } from "fs/promises";
 import { lineHashes } from "./hashline";
 import { loadFileKindAndText, type LFile } from "./file-kind";
 import { resolveTarget } from "./fs-write";
-import { toCwd } from "./path-utils";
+import { toCwd } from "./paths";
 import { detectEnding, toLF, stripBOM } from "./replace-diff";
-import { abortIf } from "./runtime";
-import { assertText, valAccess } from "./validation";
+import { abortIf } from "./utils";
+import { valKind, valAccess } from "./validation";
 import { visLines } from "./utils";
+import type { HashStore } from "./hash-store";
 export interface NormFile {
   absolutePath: string;
   normalized: string;
@@ -16,6 +18,26 @@ export interface NormFile {
   hadUtf8DecodeErrors: boolean;
 }
 
+export type SnapInfo = {
+  snapshotId: string;
+  mtimeMs: number;
+  size: number;
+};
+
+function fmtSnapId(canonicalPath: string, info: { mtimeMs: number; size: number }): string {
+  return `v1|${canonicalPath}|${info.mtimeMs}|${info.size}`;
+}
+
+export async function fileSnap(absolutePath: string): Promise<SnapInfo> {
+  const canonicalPath = await resolveTarget(absolutePath);
+  const stats = await stat(canonicalPath);
+  return {
+    snapshotId: fmtSnapId(canonicalPath, stats),
+    mtimeMs: stats.mtimeMs,
+    size: stats.size,
+  };
+}
+
 export async function readNormFile(
   path: string,
   cwd: string,
@@ -23,6 +45,7 @@ export async function readNormFile(
   accessMode: number = constants.R_OK,
   preloadedFile?: LFile,
   maxLines?: number,
+  store?: HashStore,
 ): Promise<NormFile> {
   const absolutePath = toCwd(path, cwd);
   const resolvedPath = await resolveTarget(absolutePath);
@@ -32,7 +55,7 @@ export async function readNormFile(
 
   abortIf(signal);
   const file = preloadedFile ?? (await loadFileKindAndText(resolvedPath));
-  assertText(file, path);
+  valKind(file, path);
 
   abortIf(signal);
   const { bom, text: rawContent } = stripBOM(file.text);
@@ -48,7 +71,7 @@ export async function readNormFile(
     }
   }
 
-  const fileHashes = await lineHashes(normalized, resolvedPath);
+  const fileHashes = await lineHashes(normalized, resolvedPath, undefined, store);
   return {
     absolutePath: resolvedPath,
     normalized,

package/src/fs-write.ts

@@ -11,7 +11,7 @@ import {
 	copyFile,
 } from "fs/promises";
 import { dirname, join, parse, resolve, sep } from "path";
-import { errCode } from "./validation";
+import { errCode } from "./utils";
 
 export async function resolveTarget(path: string): Promise<string> {
   const absolutePath = resolve(path);

package/src/hash-store.ts

@@ -1,7 +1,7 @@
 import { readFile, mkdir } from "fs/promises";
 import { stat } from "fs/promises";
 import { hashStorePath, hashStoreDir } from "./paths";
-import { errCode } from "./validation";
+import { errCode } from "./utils";
 import { writeAtomic } from "./fs-write";
 function isValidSnapshot(value: unknown): value is FileSnapshot {
   if (typeof value !== "object" || value === null) return false;

package/src/hashline/apply.ts

@@ -1,4 +1,4 @@
-import { abortIf } from "../runtime";
+import { abortIf } from "../utils";
 import { _lineHashesPure, HASH_SEP } from "./hash";
 import {
 	valEdits,
@@ -12,7 +12,7 @@ import {
 	type BDupWarn,
 	type AutoFix,
 } from "./resolve";
-import { cntLines } from "../utils";
+import { visLines } from "../utils";
 
 type LIdx = {
 	fileLines: string[];
@@ -377,14 +377,14 @@ export function changedRange(
 	if (original.length === 0) {
 		return {
 			firstChangedLine: 1,
-			lastChangedLine: cntLines(result),
+			lastChangedLine: visLines(result).length,
 		};
 	}
 
 	if (result.startsWith(original) && original.endsWith("\n")) {
 		return {
-			firstChangedLine: cntLines(original) + 1,
-			lastChangedLine: cntLines(result),
+			firstChangedLine: visLines(original).length + 1,
+			lastChangedLine: visLines(result).length,
 		};
 	}
 
@@ -417,7 +417,7 @@ export function changedRange(
 	const firstChangedLine = idxToLine(firstDiff + 1, result);
 	let lastChangedLine: number;
 	if (lastRes < firstDiff) {
-		lastChangedLine = result.length === 0 ? 1 : cntLines(result);
+		lastChangedLine = result.length === 0 ? 1 : visLines(result).length;
 	} else if (
 		firstDiff === 0 &&
 		original.length > 0 &&

package/src/hashline/hash.ts

@@ -1,6 +1,6 @@
 import xxhash from "xxhash-wasm";
 import * as Diff from "diff";
-import { loadHashStore, saveHashStore } from "../hash-store";
+import { loadHashStore, saveHashStore, type HashStore } from "../hash-store";
 import { MAX_HASH_RETRIES } from "../constants";
 
 export const HASH_LEN = 3;
@@ -70,20 +70,25 @@ 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;
+}
+
 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]!);
-		let hash = h2s(xxh32(c));
-		let retry = 0;
-		while (assigned.has(hash)) {
-			retry++;
-			if (retry > MAX_HASH_RETRIES) throw new Error("Hash space exhausted");
-			hash = h2s(xxh32(`${c}:R${retry}`));
-		}
-		assigned.add(hash);
+		const hash = nextUniqueHash(c, assigned);
 		hashes[i] = hash;
 	}
 	return hashes;
@@ -93,12 +98,13 @@ export async function lineHashes(
   content: string,
   path?: string,
   previous?: { content: string; hashes: string[]; removedHashes?: Set<string> },
+  store?: HashStore,
 ): Promise<string[]> {
   if (!path) {
     return _lineHashesPure(content);
   }
 
-  const store = await loadHashStore();
+  const hashStore = store ?? await loadHashStore();
 
   if (previous) {
     const newHashes = mapStableHashes(
@@ -106,19 +112,19 @@ export async function lineHashes(
       content,
       previous.removedHashes,
     );
-    store.snapshots[path] = { content, hashes: newHashes };
-    await saveHashStore(store);
+    hashStore.snapshots[path] = { content, hashes: newHashes };
+    await saveHashStore(hashStore);
     return newHashes;
   }
 
-  const snapshot = store.snapshots[path];
+  const snapshot = hashStore.snapshots[path];
   if (snapshot && snapshot.content === content) {
     return snapshot.hashes;
   }
 
   const newHashes = _lineHashesPure(content);
-  store.snapshots[path] = { content, hashes: newHashes };
-  await saveHashStore(store);
+  hashStore.snapshots[path] = { content, hashes: newHashes };
+  await saveHashStore(hashStore);
   return newHashes;
 }
 
@@ -168,14 +174,7 @@ function mapStableHashes(
   for (let i = 0; i < newLines.length; i++) {
     if (newHashes[i]) continue;
     const c = canon(newLines[i]!);
-    let retry = 0;
-    let hash = h2s(xxh32(c));
-    while (used.has(hash)) {
-      retry++;
-      if (retry > MAX_HASH_RETRIES) throw new Error("Hash space exhausted");
-      hash = h2s(xxh32(`${c}:R${retry}`));
-    }
-    used.add(hash);
+    const hash = nextUniqueHash(c, used);
     newHashes[i] = hash;
   }
   return newHashes;

package/src/hashline/resolve.ts

@@ -1,4 +1,4 @@
-import { abortIf } from "../runtime";
+import { abortIf } from "../utils";
 import { rejectUnknownFields } from "../utils";
 import { HL_BARE_PREFIX_RE } from "./hash";
 import { parseHashRef, parseText, type Anchor } from "./parse";

package/src/paths.ts

@@ -1,5 +1,5 @@
 import { homedir } from "os";
-import { join, dirname } from "path";
+import { isAbsolute, resolve as resolvePath, join, dirname } from "path";
 
 
 export function configDir(): string {
@@ -17,3 +17,14 @@ export function hashStorePath(): string {
 export function hashStoreDir(): string {
   return dirname(hashStorePath());
 }
+
+function expand(filePath: string): string {
+  if (filePath === "~") return homedir();
+  if (filePath.startsWith("~/")) return homedir() + filePath.slice(1);
+  return filePath;
+}
+
+export function toCwd(filePath: string, cwd: string): string {
+  const expanded = expand(filePath);
+  return isAbsolute(expanded) ? expanded : resolvePath(cwd, expanded);
+}

package/src/read.ts

@@ -11,9 +11,9 @@ import { Type } from "typebox";
 import { loadFileKindAndText } from "./file-kind";
 import { readNormFile } from "./file-reader";
 import { lineHashes, fmtRegion, HASH_SEP } from "./hashline";
-import { toCwd } from "./path-utils";
-import { abortIf } from "./runtime";
-import { fileSnap } from "./snapshot";
+import { toCwd } from "./paths";
+import { abortIf } from "./utils";
+import { fileSnap } from "./file-reader";
 import { visLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { valAccess } from "./validation";

package/src/replace-undo.ts

@@ -2,13 +2,32 @@ import { readFile } from "fs/promises";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { getUndo, clearUndo } from "./undo-store";
 import { loadHashStore, saveHashStore } from "./hash-store";
 import { resolveTarget, writeAtomic } from "./fs-write";
-import { toCwd } from "./path-utils";
+import { toCwd } from "./paths";
 import { toLF, stripBOM, genDiff, restoreEndings } from "./replace-diff";
 import { cntDiff } from "./utils";
 import { loadP, loadGuide } from "./prompts";
+export interface UndoEntry {
+  content: string;
+  bom: string;
+  originalEnding: "\r\n" | "\n";
+  hashes: string[];
+}
+
+const undoMap = new Map<string, UndoEntry>();
+
+export function saveUndo(path: string, entry: UndoEntry): void {
+  undoMap.set(path, entry);
+}
+
+export function getUndo(path: string): UndoEntry | undefined {
+  return undoMap.get(path);
+}
+
+export function clearUndo(path: string): void {
+  undoMap.delete(path);
+}
 
 
 export function regReplaceUndo(pi: ExtensionAPI): void {

package/src/replace.ts

@@ -12,7 +12,7 @@ import {
 } from "./replace-diff";
 import { readNormFile } from "./file-reader";
 import { normReq, normalizeFilePath } from "./replace-normalize";
-import { isRec, has, rejectUnknownFields } from "./utils";
+import { isRec, has, rejectUnknownFields, abortIf } from "./utils";
 import { MAX_HASH_LINES } from "./constants";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import {
@@ -21,9 +21,8 @@ import {
   resEdits,
   type HTEdit,
 } from "./hashline";
-import { toCwd } from "./path-utils";
-import { abortIf } from "./runtime";
-import { fileSnap } from "./snapshot";
+import { toCwd } from "./paths";
+import { fileSnap } from "./file-reader";
 import {
   buildChanged,
   buildNoop,
@@ -42,8 +41,8 @@ import {
   type RRState,
 } from "./replace-render";
 import { loadP, loadGuide } from "./prompts";
-import { readAutoReadSync } from "./config";
-import { saveUndo } from "./undo-store";
+import { saveUndo } from "./replace-undo";
+import { loadHashStore, type HashStore } from "./hash-store";
 
 const contentLinesSchema = Type.Array(Type.String(), {
   description:
@@ -147,6 +146,7 @@ export async function execPipeline(
   cwd: string,
   accessMode: number,
   signal?: AbortSignal,
+  store?: HashStore,
 ): Promise<PipelineResult> {
 
   const path = params.path;
@@ -158,8 +158,10 @@ export async function execPipeline(
     throw new Error('[E_BAD_SHAPE] Edit request requires a non-empty "changes" array.');
   }
 
+  const hashStore = store ?? await loadHashStore();
+
   const { normalized: originalNormalized, bom, originalEnding, fileHashes: originalHashes, hadUtf8DecodeErrors } = await readNormFile(
-    path, cwd, signal, accessMode, undefined, MAX_HASH_LINES,
+    path, cwd, signal, accessMode, undefined, MAX_HASH_LINES, hashStore,
   );
 
   const absolutePath = toCwd(path, cwd);
@@ -192,7 +194,7 @@ export async function execPipeline(
     content: originalNormalized,
     hashes: originalHashes,
     removedHashes,
-  });
+  }, hashStore);
 
   const warnings = [...(anchorResult.warnings ?? [])];
   return {
@@ -259,17 +261,56 @@ export function reuseMarkdown(context: any, content: string, theme: any): Markdo
   return m;
 }
 
-export function buildToolDef(opts: { flat: boolean }): ToolDef {
-  const autoRead = readAutoReadSync();
+export function buildToolDef(opts: { flat: boolean; autoRead?: boolean }): ToolDef {
+  const autoRead = opts.autoRead ?? false;
   const readGuidance = autoRead
     ? "Anchors are provided automatically after write and replace operations when auto-read is enabled."
     : "Call `read` to get fresh anchors for follow-up edits.";
 
-  const E_DESC = loadP(opts.flat ? "../prompts/replace-flat.md" : "../prompts/replace-bulk.md", {
+  const modeDesc = opts.flat
+    ? " Only one edit per call. The `hash_range_inclusive` and `content_lines` fields sit at the top level of the request object."
+    : "\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.";
+
+  const modeExamples = opts.flat
+    ? [
+        "", "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")
+    : [
+        "", "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")
+
+  const modeRules = opts.flat
+    ? ""
+    : "- Multiple edits in one call must not overlap. Overlapping ranges are rejected with [E_EDIT_CONFLICT]."
+
+  const modeRequestStructure = opts.flat
+    ? [
+        "Flat mode:", "```json", "{ \"content_lines\": [...], \"hash_range_inclusive\": [\"aB3\", \"xY7\"], \"path\": \"...\" }", "```",
+      ].join("\n")
+    : [
+        "Bulk mode (default):", "```json", "{ \"changes\": [{ \"content_lines\": [...], \"hash_range_inclusive\": [\"aB3\", \"xY7\"] }], \"path\": \"...\" }", "```",
+      ].join("\n")
+
+  const modePrefix = opts.flat
+    ? "one edit per call (flat mode)"
+    : "batching all changes to a file in one call"
+
+  const modeGuidePrefix = opts.flat
+    ? "- Use `replace` with HASH anchors for all file changes. Only one edit per call."
+    : "- Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call."
+
+  const E_DESC = loadP("../prompts/replace.md", {
+    MODE_DESCRIPTION: modeDesc,
+    MODE_EXAMPLES: modeExamples,
+    MODE_RULES: modeRules,
+    MODE_REQUEST_STRUCTURE: modeRequestStructure,
     AUTO_READ_GUIDANCE: readGuidance,
   });
-  const E_SNIPPET = loadP(opts.flat ? "../prompts/replace-flat-snippet.md" : "../prompts/replace-bulk-snippet.md");
-  const E_GUIDE = loadGuide(opts.flat ? "../prompts/replace-flat-guidelines.md" : "../prompts/replace-bulk-guidelines.md", {
+  const E_SNIPPET = loadP("../prompts/replace-snippet.md", {
+    MODE_PREFIX: modePrefix,
+  });
+  const E_GUIDE = loadGuide("../prompts/replace-guidelines.md", {
+    MODE_PREFIX: modeGuidePrefix,
     AUTO_READ_GUIDANCE: readGuidance,
   });
 
@@ -472,6 +513,14 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
   };
 }
 
-export function regReplace(pi: ExtensionAPI): void {
-  pi.registerTool(buildToolDef({ flat: false }));
+export function regReplace(pi: ExtensionAPI, autoRead?: boolean): void {
+  pi.registerTool(buildToolDef({ flat: false, autoRead }));
+}
+
+export function buildToolDefFlat(autoRead?: boolean) {
+  return buildToolDef({ flat: true, autoRead });
+}
+
+export function regReplaceFlat(pi: ExtensionAPI, autoRead?: boolean): void {
+  pi.registerTool(buildToolDef({ flat: true, autoRead }));
 }

package/src/utils.ts

@@ -12,9 +12,6 @@ export function visLines(text: string): string[] {
   return text.endsWith("\n") ? lines.slice(0, -1) : lines;
 }
 
-export function cntLines(text: string): number {
-	return visLines(text).length;
-}
 
 export function rejectUnknownFields(
   obj: Record<string, unknown>,
@@ -44,3 +41,14 @@ export function cntDiff(diff: string, marker: "+" | "-"): number {
   }
   return count;
 }
+
+export function abortIf(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new Error("Operation aborted");
+}
+
+export function errCode(error: unknown): string | undefined {
+	if (error instanceof Error) {
+		return (error as NodeJS.ErrnoException).code;
+	}
+	return undefined;
+}

package/src/validation.ts

@@ -1,6 +1,7 @@
 import { constants } from "fs";
 import { access as fsAccess } from "fs/promises";
 import type { LFile } from "./file-kind";
+import { errCode } from "./utils";
 
 export async function valAccess(
 	absolutePath: string,
@@ -34,17 +35,8 @@ export function valKind(file: LFile, path: string): asserts file is { kind: "tex
 	}
 }
 
-export function assertText(file: LFile, path: string): asserts file is { kind: "text"; text: string; hadUtf8DecodeErrors?: true } {
-	valKind(file, path);
-}
 
 export function isText(file: LFile): file is { kind: "text"; text: string; hadUtf8DecodeErrors?: true } {
 	return file.kind === "text";
 }
 
-export function errCode(error: unknown): string | undefined {
-	if (error instanceof Error) {
-		return (error as NodeJS.ErrnoException).code;
-	}
-	return undefined;
-}

package/prompts/replace-bulk-guidelines.md

@@ -1,6 +0,0 @@
-- Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
-- After a successful `replace`, the response shows the change summary. {{AUTO_READ_GUIDANCE}}
-- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
-- `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
-- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
-- **`content_lines` must be a native JSON array of strings**, not a JSON string. Do NOT serialize it: `"content_lines": "[\"line1\", \"line2\"]"` is WRONG. Use `"content_lines": ["line1", "line2"]` instead.

package/prompts/replace-bulk-snippet.md

@@ -1 +0,0 @@
-Replace lines in a text file via HASH anchors from read, batching all changes to a file in one call

package/prompts/replace-bulk.md

@@ -1,105 +0,0 @@
-Replace lines in a text file using HASH anchors from `read`.
-
-Put 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:
-
-1. Single line replace:
-```json
-{ "changes": [
-  { "content_lines": ["const x = 1;"], "hash_range_inclusive": ["MQX", "MQX"] }
-], "path": "src/main.ts" }
-```
-
-2. Range replace (3 lines → 3 new lines):
-```json
-{ "changes": [
-  { "content_lines": [
-    "function greet(name) {",
-    "  return `Hello, ${name}`;",
-    "}"
-  ], "hash_range_inclusive": ["ZPM", "VRW"] }
-], "path": "src/main.ts" }
-```
-
-3. Multiple regions in one call (delete two non-adjacent ranges):
-```json
-{ "changes": [
-  { "content_lines": [], "hash_range_inclusive": ["aB3", "xY7"] },
-  { "content_lines": [], "hash_range_inclusive": ["MQX", "ZPM"] }
-], "path": "src/server.ts" }
-```
-
-4. Append after the last line (include the old last line so the new line is added after it):
-```json
-{ "changes": [
-  { "content_lines": ["old last line", "new line"], "hash_range_inclusive": ["ZPM", "ZPM"] }
-], "path": "src/main.ts" }
-```
-
-⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
-
-Wrong:
-```json
-{ "content_lines": ["F4T│import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
-
-Right:
-```json
-{ "content_lines": ["import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
-
-`hash_range_inclusive` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
-
-⚠️ Common mistake: `hash_range_inclusive` is only the 3-character HASH, not the full `HASH│content` line.
-
-Wrong:
-```json
-{ "content_lines": [...], "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"] }
-
-Right:
-```json
-{ "content_lines": [...], "hash_range_inclusive": ["F4T", "F4T"] }
-
-⚠️ Common mistake: do not serialize `content_lines` as a JSON string.
-
-Wrong:
-```json
-{ "changes": [{ "content_lines": "[\"line1\", \"line2\"]", "hash_range_inclusive": ["F4T", "F4T"] }], "path": "src/main.ts" }
-
-Right:
-```json
-{ "changes": [{ "content_lines": ["line1", "line2"], "hash_range_inclusive": ["F4T", "F4T"] }], "path": "src/main.ts" }
-
-`content_lines` must be a native JSON array of strings, not a string that looks like an array. Pass it as a proper JSON array value.
-
-Rules:
-- `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
-- To delete a range, use `content_lines: []`.
-- `hash_range_inclusive` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
-- `content_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix. A line that happens to start with `+` or `-` is written as-is; the only rejected form is the diff preview's `+HASH│…` row (see `[E_INVALID_PATCH]`).
-- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged. Dropping indentation will produce broken code.
-- Don't add `""` for spacing unless you actually want a new blank line.
-- `changes`, `hash_range_inclusive`, and `content_lines` must be native JSON values, not JSON strings. Do not serialize them — pass them as proper arrays and strings.
-- Copy anchors from the most recent `read` of the file. Do not guess or construct them.
-- All changes in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
-- If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
-On success, the response text shows the line change summary (e.g. "Added 3 line(s), removed 1 line(s).") plus any warnings if present. {{AUTO_READ_GUIDANCE}}
-⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
-
-Wrong: To replace lines 2-3 in this function:
-```
-function greet() {
-  const x = 1;
-  return x;
-}
-```
-A model might write:
-```json
-{ "content_lines": ["  const y = 2;", "  return y;", "}"], "hash_range_inclusive": ["X", "Y"] }
-This produces `function greet() {\n  const y = 2;\n  return y;\n}\n}` — the `}` appears twice because it was already on line 4 (outside the range) AND in `content_lines`.
-
-Right: Only include the new lines that belong in the range:
-```json
-{ "content_lines": ["  const y = 2;", "  return y;"], "hash_range_inclusive": ["X", "Y"] }
-The `}` on line 4 is outside the range and stays in place.
-
-**Undo:** If a replace produced incorrect results, call `undo_last_replace` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/prompts/replace-flat-guidelines.md

@@ -1,6 +0,0 @@
-- Use `replace` with HASH anchors for all file changes. Only one edit per call (flat mode — no `changes` array).
-- After a successful `replace`, the response shows the change summary. {{AUTO_READ_GUIDANCE}}
-- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
-- `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
-- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
-- **`content_lines` must be a native JSON array of strings**, not a JSON string. Do NOT serialize it: `"content_lines": "[\"line1\", \"line2\"]"` is WRONG. Use `"content_lines": ["line1", "line2"]` instead.

package/prompts/replace-flat-snippet.md

@@ -1 +0,0 @@
-Replace lines in a text file via HASH anchors from read, one edit per call (flat mode)

package/prompts/replace-flat.md

@@ -1,95 +0,0 @@
-Replace lines in a text file using HASH anchors from `read`. Only one edit per call (no bulk `changes` array — `hash_range_inclusive` and `content_lines` sit at the top level).
-
-Examples:
-
-1. Single line replace:
-```json
-{ "content_lines": ["const x = 1;"], "hash_range_inclusive": ["MQX", "MQX"], "path": "src/main.ts" }
-```
-
-2. Range replace (3 lines → 3 new lines):
-```json
-{ "content_lines": [
-    "function greet(name) {",
-    "  return `Hello, ${name}`;",
-    "}"
-  ], "hash_range_inclusive": ["ZPM", "VRW"], "path": "src/main.ts" }
-```
-
-3. Delete a range:
-```json
-{ "content_lines": [], "hash_range_inclusive": ["aB3", "xY7"], "path": "src/server.ts" }
-```
-
-4. Append after the last line (include the old last line so the new line is added after it):
-```json
-{ "content_lines": ["old last line", "new line"], "hash_range_inclusive": ["ZPM", "ZPM"], "path": "src/main.ts" }
-```
-
-⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
-
-Wrong:
-```json
-{ "content_lines": ["F4T│import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
-
-Right:
-```json
-{ "content_lines": ["import { x } from \"./x\";"], "hash_range_inclusive": ["F4T", "F4T"] }
-
-`hash_range_inclusive` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
-
-⚠️ Common mistake: `hash_range_inclusive` is only the 3-character HASH, not the full `HASH│content` line.
-
-Wrong:
-```json
-{ "content_lines": [...], "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"] }
-
-Right:
-```json
-{ "content_lines": [...], "hash_range_inclusive": ["F4T", "F4T"] }
-
-⚠️ Common mistake: do not serialize `content_lines` as a JSON string.
-
-Wrong:
-```json
-{ "content_lines": "[\"line1\", \"line2\"]", "hash_range_inclusive": ["F4T", "F4T"], "path": "src/main.ts" }
-
-Right:
-```json
-{ "content_lines": ["line1", "line2"], "hash_range_inclusive": ["F4T", "F4T"], "path": "src/main.ts" }
-
-`content_lines` must be a native JSON array of strings, not a string that looks like an array. Pass it as a proper JSON array value.
-
-Rules:
-- `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
-- To delete a range, use `content_lines: []`.
-- `hash_range_inclusive` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
-- `content_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix. A line that happens to start with `+` or `-` is written as-is; the only rejected form is the diff preview's `+HASH│…` row (see `[E_INVALID_PATCH]`).
-- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged. Dropping indentation will produce broken code.
-- Don't add `""` for spacing unless you actually want a new blank line.
-- Copy anchors from the most recent `read` of the file. Do not guess or construct them.
-- If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
-- The `hash_range_inclusive` is inclusive — the entire span from the first anchor through the second anchor is deleted and replaced with `content_lines`. The old lines in that span are gone. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
-- `hash_range_inclusive` and `content_lines` must be native JSON values, not JSON strings. Do not serialize them — pass them as a proper array and array of strings respectively.
-On success, the response text shows the line change summary (e.g. "Added 3 line(s), removed 1 line(s).") plus any warnings if present. {{AUTO_READ_GUIDANCE}}
-
-⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
-
-Wrong: To replace lines 2-3 in this function:
-```
-function greet() {
-  const x = 1;
-  return x;
-}
-```
-A model might write:
-```json
-{ "content_lines": ["  const y = 2;", "  return y;", "}"], "hash_range_inclusive": ["X", "Y"] }
-This produces `function greet() {\n  const y = 2;\n  return y;\n}\n}` — the `}` appears twice because it was already on line 4 (outside the range) AND in `content_lines`.
-
-Right: Only include the new lines that belong in the range:
-```json
-{ "content_lines": ["  const y = 2;", "  return y;"], "hash_range_inclusive": ["X", "Y"] }
-The `}` on line 4 is outside the range and stays in place.
-
-**Undo:** If a replace produced incorrect results, call `undo_last_replace` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/src/path-utils.ts

@@ -1,13 +0,0 @@
-import * as os from "os";
-import { isAbsolute, resolve as resolvePath } from "path";
-
-function expand(filePath: string): string {
-  if (filePath === "~") return os.homedir();
-  if (filePath.startsWith("~/")) return os.homedir() + filePath.slice(1);
-  return filePath;
-}
-
-export function toCwd(filePath: string, cwd: string): string {
-  const expanded = expand(filePath);
-  return isAbsolute(expanded) ? expanded : resolvePath(cwd, expanded);
-}

package/src/replace-flat.ts

@@ -1,17 +0,0 @@
-import type {
-  ExtensionAPI,
-} from "@earendil-works/pi-coding-agent";
-import {
-  buildToolDef,
-  flatEditToolSchema,
-} from "./replace";
-
-export { flatEditToolSchema };
-
-export function buildToolDefFlat() {
-  return buildToolDef({ flat: true });
-}
-
-export function regReplaceFlat(pi: ExtensionAPI): void {
-  pi.registerTool(buildToolDef({ flat: true }));
-}

package/src/runtime.ts

@@ -1,3 +0,0 @@
-export function abortIf(signal?: AbortSignal): void {
-  if (signal?.aborted) throw new Error("Operation aborted");
-}

package/src/snapshot.ts

@@ -1,22 +0,0 @@
-import { stat } from "fs/promises";
-import { resolveTarget } from "./fs-write";
-
-export type SnapInfo = {
-  snapshotId: string;
-  mtimeMs: number;
-  size: number;
-};
-
-function fmtSnapId(canonicalPath: string, info: { mtimeMs: number; size: number }): string {
-  return `v1|${canonicalPath}|${info.mtimeMs}|${info.size}`;
-}
-
-export async function fileSnap(absolutePath: string): Promise<SnapInfo> {
-  const canonicalPath = await resolveTarget(absolutePath);
-  const stats = await stat(canonicalPath);
-  return {
-    snapshotId: fmtSnapId(canonicalPath, stats),
-    mtimeMs: stats.mtimeMs,
-    size: stats.size,
-  };
-}

package/src/undo-store.ts

@@ -1,21 +0,0 @@
-
-export interface UndoEntry {
-  content: string;
-  bom: string;
-  originalEnding: "\r\n" | "\n";
-  hashes: string[];
-}
-
-const undoMap = new Map<string, UndoEntry>();
-
-export function saveUndo(path: string, entry: UndoEntry): void {
-  undoMap.set(path, entry);
-}
-
-export function getUndo(path: string): UndoEntry | undefined {
-  return undoMap.get(path);
-}
-
-export function clearUndo(path: string): void {
-  undoMap.delete(path);
-}