pi-hashline-edit-pro 0.9.3 → 0.9.5

package/README.md

@@ -79,7 +79,7 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 - **Request structure validation.** The request envelope (`path`, `edits`) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_REF]`.
 - **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{old_range: ["<START>", "<END>"], new_lines: [...]}`.
 
-All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so line numbers stay consistent across operations.
+All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so the hashes from a single `read` call remain valid across all edits in the batch.
 
 ### Chained edits
 
@@ -108,6 +108,7 @@ The post-edit diff (with `+`/`-` markers) is exposed to the host UI via `details
 - **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{old_range: ["<START>", "<END>"], new_lines: [...]}`.
 - **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 warnings.** When the last line of a replacement matches the next surviving line (or the first line matches the preceding one), a warning is emitted. This catches a common LLM pattern where closing delimiters like `}`, `});`, or `} else {` are accidentally duplicated. The warning includes the surviving line's post-edit hash so the model can reference it in a follow-up edit. No autocorrection is applied — the duplicate stays in the file and the model decides whether to remove it. Raw line comparison (not trimmed) avoids false positives when indentation differs.
 
 ## Hashing
 

package/index.ts

@@ -6,23 +6,20 @@ import { registerReplaceTool } from "./src/replace";
 import { registerReadTool } from "./src/read";
 import { normalizeToLF } from "./src/replace-diff";
 import { getVisibleLines } from "./src/utils";
+import { AUTO_READ_MAX_LINES } from "./src/constants";
 
 export default function (pi: ExtensionAPI): void {
   registerReadTool(pi);
   registerReplaceTool(pi);
 
-  // Disable the built-in `edit` tool so the model uses `replace` instead.
   pi.on("session_start", async (_event, ctx) => {
     const active = pi.getActiveTools();
     pi.setActiveTools(active.filter((t) => t !== "edit"));
   });
 
-  // Auto-read after write state - controlled by PI_HASHLINE_AUTO_READ env var (default: disabled).
-  // Can be toggled at runtime via /toggle-auto-read command.
   const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;
   let autoReadEnabled = autoReadValue === "1" || autoReadValue === "true";
 
-  // Register toggle-auto-read command
   pi.registerCommand("toggle-auto-read", {
     description: "Toggle automatic hashline anchors after write operations",
     handler: async (_args, ctx) => {
@@ -32,7 +29,6 @@ export default function (pi: ExtensionAPI): void {
     },
   });
 
-  // Auto-read after write handler - always registered, but checks the flag
   pi.on("tool_result", async (event, ctx) => {
     if (!autoReadEnabled) return;
     if (event.toolName !== "write" || event.isError) return;
@@ -44,24 +40,20 @@ export default function (pi: ExtensionAPI): void {
       const absolutePath = isAbsolute(filePath) ? filePath : join(ctx.cwd, filePath);
       const content = await readFile(absolutePath, "utf-8");
 
-      // Normalize and compute hashline output
       const normalized = normalizeToLF(content);
       const visibleLines = getVisibleLines(normalized);
 
       if (visibleLines.length === 0) return;
 
-      // Truncate to a reasonable limit to avoid excessive token usage
-      const MAX_LINES = 2000;
-      const truncated = visibleLines.length > MAX_LINES;
-      const displayLines = truncated ? visibleLines.slice(0, MAX_LINES) : visibleLines;
+      const truncated = visibleLines.length > AUTO_READ_MAX_LINES;
+      const displayLines = truncated ? visibleLines.slice(0, AUTO_READ_MAX_LINES) : visibleLines;
 
       const hashes = computeLineHashes(normalized);
       const selectedHashes = hashes.slice(0, displayLines.length);
       const hashlineOutput = formatHashlineRegion(selectedHashes, displayLines);
 
-      // Add pagination hint if truncated
       const paginationHint = truncated
-        ? `\n\n[Showing lines 1-${MAX_LINES} of ${visibleLines.length}. Use offset=${MAX_LINES + 1} to continue.]`
+        ? `\n\n[Showing lines 1-${AUTO_READ_MAX_LINES} of ${visibleLines.length}. Use offset=${AUTO_READ_MAX_LINES + 1} to continue.]`
         : "";
 
       if (hashlineOutput) {
@@ -73,7 +65,6 @@ export default function (pi: ExtensionAPI): void {
         };
       }
     } catch {
-      // Auto-read failure should not affect write result
     }
   });
 
@@ -83,4 +74,4 @@ export default function (pi: ExtensionAPI): void {
       ctx.ui.notify("Hashline Edit mode active", "info");
     });
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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/src/constants.ts

@@ -0,0 +1,5 @@
+export const AUTO_READ_MAX_LINES = 2000;
+export const CHANGED_ANCHOR_TEXT_BUDGET_BYTES = 50 * 1024;
+export const ANCHOR_CONTEXT_LINES = 0;
+export const ANCHOR_MAX_OUTPUT_LINES = 12;
+export const FILE_TYPE_SNIFF_BYTES = 8192;

package/src/file-kind.ts

@@ -1,5 +1,6 @@
 import { open as fsOpen, stat as fsStat } from "fs/promises";
 import { fileTypeFromBuffer } from "file-type";
+import { FILE_TYPE_SNIFF_BYTES } from "./constants";
 
 const IMAGE_MIME_TYPES = new Set<string>([
 	"image/jpeg",
@@ -18,8 +19,6 @@ function isTextLikeMimeType(mimeType: string): boolean {
 	return mimeType.startsWith("text/") || TEXT_LIKE_MIME_TYPES.has(mimeType);
 }
 
-const FILE_TYPE_SNIFF_BYTES = 8192;
-
 export type FileKind =
 	| { kind: "directory" }
 	| { kind: "image"; mimeType: string }
@@ -84,12 +83,6 @@ export async function loadFileKindAndText(
 			};
 		}
 
-		// Non-fatal decode, matching pi's built-in tools: invalid UTF-8 becomes
-		// U+FFFD rather than rejecting the file. The null-byte guard above is the
-		// only signal we treat as binary, so non-UTF-8 text (CP1251, GBK, …) reads
-		// instead of forcing the model to bypass hashline with raw shell edits.
-		// Track fatal-decoder failures separately so a literal, valid U+FFFD in a
-		// UTF-8 file does not get mistaken for lossy decoding.
 		const decoder = new TextDecoder("utf-8");
 		const fatalDecoder = new TextDecoder("utf-8", { fatal: true });
 		let hadUtf8DecodeErrors = false;
@@ -158,4 +151,4 @@ export async function classifyFileKind(filePath: string): Promise<FileKind> {
 		case "text":
 			return { kind: "text" };
 	}
-}
+}

package/src/hashline/apply.ts

@@ -1,4 +1,3 @@
-
 import { throwIfAborted } from "../runtime";
 import { computeLineHashes } from "./hash";
 import {
@@ -10,9 +9,10 @@ import {
 	type ResolvedHashlineEdit,
 	type NoopEdit,
 	type HashlineEdit,
+	type BoundaryDuplicationWarning,
 } from "./resolve";
 import { countVisibleLines } from "../utils";
-
+import { ANCHOR_CONTEXT_LINES, ANCHOR_MAX_OUTPUT_LINES } from "../constants";
 
 type LineIndex = {
 	fileLines: string[];
@@ -235,7 +235,6 @@ export function applyHashlineEdits(
 			lastChangedLine: undefined,
 		};
 
-	// Normalize new_lines: [""] to new_lines: [] for deletion.
 	edits = edits.map((edit) =>
 		edit.new_lines.length === 1 &&
 		edit.new_lines[0] === ""
@@ -248,7 +247,7 @@ export function applyHashlineEdits(
 	const noopEdits: NoopEdit[] = [];
 	const warnings: string[] = [];
 
-	const { resolved, mismatches } = validateAnchorEdits(
+	const { resolved, mismatches, boundaryWarnings } = validateAnchorEdits(
 		edits,
 		lineIndex.fileLines,
 		fileHashes,
@@ -277,6 +276,31 @@ export function applyHashlineEdits(
 	assertDoesNotEmptyFile(content, result);
 	const changedRange = computeChangedLineRange(content, result);
 
+	const resultLines = result.split("\n");
+	const resultHashes = computeLineHashes(result);
+	for (const bw of boundaryWarnings) {
+		let seen = 0;
+		let matchIndex = -1;
+		for (let i = 0; i < resultLines.length; i++) {
+			if (resultLines[i] === bw.survivingLineContent) {
+				if (seen === bw.occurrence) { matchIndex = i; break; }
+				seen++;
+			}
+		}
+		if (matchIndex >= 0) {
+			const hash = resultHashes[matchIndex];
+			if (bw.kind === "trailing") {
+				warnings.push(
+					`Potential boundary duplication: the last line of the replacement (${JSON.stringify(bw.replacementLineContent)}) matches the next surviving line. Surviving line hash: ${hash}`
+				);
+			} else {
+				warnings.push(
+					`Potential boundary duplication: the first line of the replacement (${JSON.stringify(bw.replacementLineContent)}) matches the preceding surviving line. Surviving line hash: ${hash}`
+				);
+			}
+		}
+	}
+
 	return {
 		content: result,
 		firstChangedLine: changedRange?.firstChangedLine,
@@ -287,9 +311,6 @@ export function applyHashlineEdits(
 }
 
 
-const ANCHOR_CONTEXT_LINES = 0;
-const ANCHOR_MAX_OUTPUT_LINES = 12;
-
 export function computeAffectedLineRange(params: {
 	firstChangedLine: number | undefined;
 	lastChangedLine: number | undefined;
@@ -309,8 +330,6 @@ export function computeAffectedLineRange(params: {
 		return null;
 	}
 
-	// When contextLines is 0, skip the anchor block entirely.
-	// The LLM already knows what it changed and can call read for fresh anchors.
 	if (contextLines === 0) {
 		return null;
 	}
@@ -376,6 +395,7 @@ export function computeChangedLineRange(
 	}
 	if (firstDiff === minLen && original.length === result.length) return null;
 
+
 	let lastOrig = original.length - 1;
 	let lastRes = result.length - 1;
 	while (
@@ -410,5 +430,4 @@ export function computeChangedLineRange(
 	}
 
 	return { firstChangedLine, lastChangedLine };
-}
-
+}

package/src/hashline/hash.ts

@@ -1,11 +1,8 @@
-
 import xxhash from "xxhash-wasm";
 
 
 export const HASH_LENGTH = 3;
-
 export const HASH_PREFIX = "";
-
 export const ANCHOR_LENGTH = HASH_LENGTH;
 
 const HASH_ALPHABET =
@@ -42,27 +39,20 @@ export const HASHLINE_BARE_PREFIX_RE = new RegExp(`^\\s*(${HASH_CHARS_CLASS})│
 
 
 
-// Lazy-initialized xxhash-wasm hasher. Initialization starts at module load
-// time and completes in ~2ms. By the time any tool calls xxh32(), the hasher
-// is ready.
 type Hasher = { h32(input: string, seed?: number): number };
 let hasherPromise: Promise<Hasher> | null = null;
 let hasherSync: Hasher | null = null;
 
 function getHasher(): Hasher {
 	if (hasherSync) return hasherSync;
-	// Fast path won't hit this in practice — the wasm init completes in ~2ms
-	// and no tool call happens at import time. But if it does, throw clearly.
 	throw new Error("xxhash-wasm not initialized yet. This should not happen.");
 }
 
-// Start initialization immediately at module load time.
 hasherPromise = xxhash().then((h) => {
 	hasherSync = h;
 	return h;
 });
 
-// Export for tests that need to await readiness.
 export function ensureHasherReady(): Promise<Hasher> {
 	return hasherPromise!
 }
@@ -108,4 +98,4 @@ export const HASH_FORMAT = {
 };
 
 
-export { HASH_ALPHABET_RE };
+export { HASH_ALPHABET_RE };

package/src/hashline/index.ts

@@ -26,6 +26,7 @@ export {
 	type ResolvedHashlineEdit,
 	type HashlineToolEdit,
 	type NoopEdit,
+	type BoundaryDuplicationWarning,
 	describeEdit,
 	resolveEditAnchors,
 	validateAnchorEdits,

package/src/hashline/resolve.ts

@@ -21,6 +21,15 @@ interface HashMismatch {
 	candidates?: number[];
 }
 
+export interface BoundaryDuplicationWarning {
+	kind: "trailing" | "leading";
+	survivingLineContent: string;
+	survivingLineIndex: number;
+	occurrence: number;
+	replacementLineContent: string;
+	editIndex: number;
+}
+
 export interface NoopEdit {
 	editIndex: number;
 	loc: string;
@@ -30,9 +39,7 @@ export interface NoopEdit {
 export type HashlineToolEdit = {
 	old_range?: [string, string];
 	new_lines?: string[];
-	/** @deprecated Legacy field — rejected with [E_LEGACY_SHAPE] at validation time. */
 	oldText?: string;
-	/** @deprecated Legacy field — rejected with [E_LEGACY_SHAPE] at validation time. */
 	newText?: string;
 };
 
@@ -155,7 +162,6 @@ export function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
 	for (const [index, edit] of edits.entries()) {
 		assertEditItem(edit as Record<string, unknown>, index);
 
-		// Normalize new_lines: [""] to new_lines: [] for deletion.
 		const replaceLines = hashlineParseText(edit.new_lines ?? null);
 		const normalizedLines =
 			replaceLines.length === 1 && replaceLines[0] === ""
@@ -220,9 +226,6 @@ export function assertNoBareHashPrefixLines(
 }
 
 
-/**
- * Human-readable label for a resolved edit (used in warnings and conflict errors).
- */
 export function describeEdit(edit: ResolvedHashlineEdit): string {
 	return `replace ${edit.old_range[0].hash}-${edit.old_range[1].hash}`;
 }
@@ -233,7 +236,7 @@ export function validateAnchorEdits(
 	fileHashes: string[],
 	warnings: string[],
 	signal: AbortSignal | undefined,
-): { resolved: ResolvedHashlineEdit[]; mismatches: HashMismatch[] } {
+): { resolved: ResolvedHashlineEdit[]; mismatches: HashMismatch[]; boundaryWarnings: BoundaryDuplicationWarning[] } {
 	if (fileHashes.length !== fileLines.length) {
 		throw new Error(
 			`validateAnchorEdits: fileHashes.length (${fileHashes.length}) must match fileLines.length (${fileLines.length}).`,
@@ -241,6 +244,7 @@ export function validateAnchorEdits(
 	}
 	const resolved: ResolvedHashlineEdit[] = [];
 	const mismatches: HashMismatch[] = [];
+	const boundaryWarnings: BoundaryDuplicationWarning[] = [];
 
 	const tryResolve = (ref: Anchor): ResolvedAnchor | undefined => {
 		const result = resolveAnchor(ref, fileLines, fileHashes);
@@ -266,36 +270,38 @@ export function validateAnchorEdits(
 		}
 		const endLine = endResolved.line;
 		const nextLine = fileLines[endLine];
-		const replacementLastLine = edit.new_lines.at(-1)?.trim();
+		const replacementLastLine = edit.new_lines.at(-1);
 		if (
 			nextLine !== undefined &&
-			replacementLastLine &&
-			/[\p{L}\p{N}]/u.test(replacementLastLine) &&
-			replacementLastLine === nextLine.trim()
+			replacementLastLine !== undefined &&
+			replacementLastLine.length > 0 &&
+			replacementLastLine === nextLine
 		) {
-			const resolvedEdit: ResolvedHashlineEdit = {
-				old_range: [startResolved, endResolved],
-				new_lines: edit.new_lines,
-			};
-			warnings.push(
-				`Potential boundary duplication after ${describeEdit(resolvedEdit)}: the replacement ends with a line that matches the next surviving line after trim.`,
-			);
+			boundaryWarnings.push({
+				kind: "trailing",
+				survivingLineContent: nextLine,
+				survivingLineIndex: endLine,
+				occurrence: fileLines.slice(0, endLine).filter(l => l === nextLine).length,
+				replacementLineContent: replacementLastLine,
+				editIndex: resolved.length,
+			});
 		}
 		const prevLine = fileLines[startResolved.line - 2];
-		const replacementFirstLine = edit.new_lines[0]?.trim();
+		const replacementFirstLine = edit.new_lines[0];
 		if (
 			prevLine !== undefined &&
-			replacementFirstLine &&
-			/[\p{L}\p{N}]/u.test(replacementFirstLine) &&
-			replacementFirstLine === prevLine.trim()
+			replacementFirstLine !== undefined &&
+			replacementFirstLine.length > 0 &&
+			replacementFirstLine === prevLine
 		) {
-			const resolvedEdit: ResolvedHashlineEdit = {
-				old_range: [startResolved, endResolved],
-				new_lines: edit.new_lines,
-			};
-			warnings.push(
-				`Potential boundary duplication before ${describeEdit(resolvedEdit)}: the replacement starts with a line that matches the preceding surviving line after trim.`,
-			);
+			boundaryWarnings.push({
+				kind: "leading",
+				survivingLineContent: prevLine,
+				survivingLineIndex: startResolved.line - 2,
+				occurrence: fileLines.slice(0, startResolved.line - 2).filter(l => l === prevLine).length,
+				replacementLineContent: replacementFirstLine,
+				editIndex: resolved.length,
+			});
 		}
 		resolved.push({
 			old_range: [startResolved, endResolved],
@@ -303,7 +309,7 @@ export function validateAnchorEdits(
 		});
 	}
 
-	return { resolved, mismatches };
+	return { resolved, mismatches, boundaryWarnings };
 }
 
 export { maybeWarnSuspiciousUnicodeEscapePlaceholder };

package/src/prompts.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "fs";
+
+export function loadPrompt(relativePath: string, replacements?: Record<string, string>): string {
+	let content = readFileSync(new URL(relativePath, import.meta.url), "utf-8").trim();
+	if (replacements) {
+		for (const [key, value] of Object.entries(replacements)) {
+			content = content.replaceAll(`{{${key}}}`, value);
+		}
+	}
+	return content;
+}
+
+export function loadPromptGuidelines(relativePath: string): string[] {
+	return readFileSync(new URL(relativePath, import.meta.url), "utf-8")
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.startsWith("- "))
+		.map((line) => line.slice(2));
+}

package/src/read.ts

@@ -8,9 +8,6 @@ import {
 	type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { readFileSync } from "fs";
-import { access as fsAccess } from "fs/promises";
-import { constants } from "fs";
 import { normalizeToLF, stripBom } from "./replace-diff";
 import { loadFileKindAndText } from "./file-kind";
 import { computeLineHashes, formatHashlineRegion } from "./hashline";
@@ -18,28 +15,16 @@ import { resolveToCwd } from "./path-utils";
 import { throwIfAborted } from "./runtime";
 import { getFileSnapshot } from "./snapshot";
 import { getVisibleLines } from "./utils";
+import { loadPrompt, loadPromptGuidelines } from "./prompts";
+import { validateFileAccess, validateFileKind, isTextFile } from "./validation";
 
-const READ_DESC = readFileSync(
-	new URL("../prompts/read.md", import.meta.url),
-	"utf-8",
-)
-	.replaceAll("{{DEFAULT_MAX_LINES}}", String(DEFAULT_MAX_LINES))
-	.replaceAll("{{DEFAULT_MAX_BYTES}}", formatSize(DEFAULT_MAX_BYTES))
-	.trim();
-
-const READ_PROMPT_SNIPPET = readFileSync(
-	new URL("../prompts/read-snippet.md", import.meta.url),
-	"utf-8",
-).trim();
-
-const READ_PROMPT_GUIDELINES = readFileSync(
-	new URL("../prompts/read-guidelines.md", import.meta.url),
-	"utf-8",
-)
-	.split("\n")
-	.map((line) => line.trim())
-	.filter((line) => line.startsWith("- "))
-	.map((line) => line.slice(2));
+const READ_DESC = loadPrompt("../prompts/read.md", {
+	DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
+	DEFAULT_MAX_BYTES: formatSize(DEFAULT_MAX_BYTES),
+});
+
+const READ_PROMPT_SNIPPET = loadPrompt("../prompts/read-snippet.md");
+const READ_PROMPT_GUIDELINES = loadPromptGuidelines("../prompts/read-guidelines.md");
 
 function normalizePositiveInteger(
 	value: number | undefined,
@@ -151,35 +136,11 @@ export function registerReadTool(pi: ExtensionAPI): void {
 			const absolutePath = resolveToCwd(rawPath, ctx.cwd);
 
 			throwIfAborted(signal);
-			try {
-				await fsAccess(absolutePath, constants.R_OK);
-			} catch (error: unknown) {
-				const code =
-					error instanceof Error
-						? (error as NodeJS.ErrnoException).code
-						: undefined;
-				if (code === "ENOENT") {
-					throw new Error(`File not found: ${rawPath}`);
-				}
-				if (code === "EACCES" || code === "EPERM") {
-					throw new Error(`File is not readable: ${rawPath}`);
-				}
-				throw new Error(`Cannot access file: ${rawPath}`);
-			}
+			await validateFileAccess(absolutePath, rawPath);
 
 			throwIfAborted(signal);
 			const file = await loadFileKindAndText(absolutePath);
-			if (file.kind === "directory") {
-				throw new Error(
-					`Path is a directory: ${rawPath}. Use ls to inspect directories.`,
-				);
-			}
-
-			if (file.kind === "binary") {
-				throw new Error(
-					`Path is a binary file: ${rawPath} (${file.description}). Hashline read only supports text files and supported images.`,
-				);
-			}
+			validateFileKind(file, rawPath);
 
 			if (file.kind === "image") {
 				const builtinRead = createReadTool(ctx.cwd);
@@ -195,9 +156,6 @@ export function registerReadTool(pi: ExtensionAPI): void {
 
 			throwIfAborted(signal);
 			const normalized = normalizeToLF(stripBom(file.text).text);
-			// Compute hashes once for the whole file so the per-line anchors the
-			// model sees here are byte-identical to what the replace tool will
-			// compute when it later validates against this file.
 			const fileHashes = computeLineHashes(normalized);
 			const preview = formatHashlineReadPreview(
 				normalized,
@@ -209,9 +167,6 @@ export function registerReadTool(pi: ExtensionAPI): void {
 			);
 			const snapshot = await getFileSnapshot(absolutePath);
 
-			// Invalid UTF-8 bytes are decoded as U+FFFD, matching Pi's built-in
-			// tools. Warn only when the decoder reported invalid bytes; a literal,
-			// valid U+FFFD in a UTF-8 file should not be treated as lossy decoding.
 			const previewText =
 				file.hadUtf8DecodeErrors === true
 					? `${preview.text}\n\n[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]`
@@ -221,14 +176,10 @@ export function registerReadTool(pi: ExtensionAPI): void {
 				content: [{ type: "text", text: previewText }],
 				details: {
 					truncation: preview.truncation,
-					// snapshotId remains in details for host UI (e.g. "file changed since
-					// last view"). It is NOT echoed in text — the LLM no longer needs it.
 					snapshotId: snapshot.snapshotId,
 					...(preview.nextOffset !== undefined
 						? { nextOffset: preview.nextOffset }
 						: {}),
-					// Phase 2 C — host-only observability. Truncated reads usually mean
-					// a follow-up read with `offset = next_offset` is coming.
 					metrics: {
 						truncated: !!preview.truncation,
 						...(preview.nextOffset !== undefined
@@ -239,4 +190,4 @@ export function registerReadTool(pi: ExtensionAPI): void {
 			};
 		},
 	});
-}
+}

package/src/replace-diff.ts

@@ -85,19 +85,16 @@ export function generateDiffString(
       let linesToShow = raw;
       let skipStart = 0;
       let skipEnd = 0;
-      let skipMiddle = 0; // lines skipped between head and tail context
+      let skipMiddle = 0;
 
       if (!lastWasChange) {
-        // Before a change: show last contextLines only.
         skipStart = Math.max(0, raw.length - contextLines);
         linesToShow = raw.slice(skipStart);
       } else if (nextPartIsChange && raw.length > contextLines * 2) {
-        // Between two changes: show first contextLines + last contextLines with ellipsis in between.
         const tail = raw.slice(-contextLines);
         linesToShow = [...raw.slice(0, contextLines), "__ELLIPSIS__", ...tail];
         skipMiddle = raw.length - contextLines * 2;
       } else if (linesToShow.length > contextLines) {
-        // After a change with no next change nearby: show first contextLines only.
         skipEnd = linesToShow.length - contextLines;
         linesToShow = linesToShow.slice(0, contextLines);
       }
@@ -234,4 +231,4 @@ export function buildCompactHashlineDiffPreview(
     addedLines,
     removedLines,
   };
-}
+}

package/src/replace-normalize.ts

@@ -1,4 +1,3 @@
-
 import { isRecord, hasOwn } from "./utils";
 
 function coerceEditsArray(edits: unknown): unknown {
@@ -21,7 +20,6 @@ export function normalizeReplaceRequest(input: unknown): unknown {
 
 	const record: Record<string, unknown> = { ...input };
 
-	// file_path → path alias.
 	if (typeof record.path !== "string" && typeof record.file_path === "string") {
 		record.path = record.file_path;
 		delete record.file_path;
@@ -29,11 +27,9 @@ export function normalizeReplaceRequest(input: unknown): unknown {
 
 	const hasEditsField = hasOwn(record, "edits");
 
-	// edits-as-JSON-string → array.
 	if (hasEditsField) {
 		record.edits = coerceEditsArray(record.edits);
 	}
 
 	return record;
-}
-
+}

package/src/replace-render.ts

@@ -1,17 +1,9 @@
-/**
- * TUI rendering helpers for the replace tool.
- *
- * Extracted from `src/replace.ts` to separate presentation (color themes, diff
- * formatting, Markdown rendering) from tool execution logic.
- */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { normalizeReplaceRequest } from "./replace-normalize";
 import type { ReplaceRequestParams, HashlineReplaceToolDetails } from "./replace";
 import { isRecord } from "./utils";
 
-// ─── Theme type aliases ─────────────────────────────────────────────────
-
 export type FgTheme = Pick<Theme, "fg">;
 export type CallTheme = Pick<Theme, "fg" | "bold">;
 export type RenderedMarkdownTheme = Pick<
@@ -19,8 +11,6 @@ export type RenderedMarkdownTheme = Pick<
 	"fg" | "bold" | "italic" | "underline" | "strikethrough"
 >;
 
-// ─── Render state ───────────────────────────────────────────────────────
-
 export type ReplacePreview = { diff: string } | { error: string };
 
 export type ReplaceRenderState = {
@@ -29,8 +19,6 @@ export type ReplaceRenderState = {
 	previewGeneration?: number;
 };
 
-// ─── Preview input extraction ───────────────────────────────────────────
-
 
 export function getRenderablePreviewInput(
 	args: unknown,
@@ -53,8 +41,6 @@ export function getRenderablePreviewInput(
 	return request.edits !== undefined ? request : null;
 }
 
-// ─── Diff formatting ────────────────────────────────────────────────────
-
 export function colorDiffLines(lines: string[], theme: FgTheme): string[] {
 	return lines.map((line) => {
 		if (line.startsWith("+") && !line.startsWith("+++")) {
@@ -88,8 +74,6 @@ export function formatResultDiff(diff: string, theme: FgTheme): string {
 	return colorDiffLines(diff.split("\n"), theme).join("\n");
 }
 
-// ─── Edit call formatting ───────────────────────────────────────────────
-
 export function formatEditCall(
 	args: ReplaceRequestParams | undefined,
 	state: ReplaceRenderState,
@@ -118,8 +102,6 @@ export function formatEditCall(
 	return text;
 }
 
-// ─── Result text extraction ─────────────────────────────────────────────
-
 export function getRenderedEditTextContent(result: {
 	content?: Array<{ type: string; text?: string }>;
 }): string | undefined {
@@ -136,8 +118,6 @@ export function extractRenderedWarnings(
 	return text?.match(/(?:^|\n)Warnings:\n[\s\S]*$/)?.[0]?.trimStart();
 }
 
-// ─── Result classification ──────────────────────────────────────────────
-
 export function isAppliedChangedResult(
 	details: HashlineReplaceToolDetails | undefined,
 ): boolean {
@@ -165,7 +145,6 @@ export function buildAppliedChangedResultText(
 
 	return sections.length > 0 ? sections.join("\n\n") : undefined;
 }
-// ─── Markdown rendering ─────────────────────────────────────────────────
 
 function trimEdgeEmptyLines(lines: string[]): string[] {
 	let start = 0;
@@ -272,4 +251,4 @@ export function createRenderedEditMarkdownTheme(theme: RenderedMarkdownTheme) {
 				return theme.fg("mdCodeBlock", line);
 			}),
 	};
-}
+}

package/src/replace-response.ts

@@ -1,4 +1,3 @@
-
 import { generateDiffString } from "./replace-diff";
 import {
 	computeAffectedLineRange,
@@ -6,6 +5,7 @@ import {
 	formatHashlineRegion,
 } from "./hashline";
 import { getVisibleLines } from "./utils";
+import { CHANGED_ANCHOR_TEXT_BUDGET_BYTES } from "./constants";
 
 type ToolResult = {
 	content: Array<{ type: "text"; text: string }>;
@@ -13,9 +13,6 @@ type ToolResult = {
 	details: any;
 };
 
-const CHANGED_ANCHOR_TEXT_BUDGET_BYTES = 50 * 1024;
-
-
 export type ReplaceMetrics = {
 	edits_attempted: number;
 	edits_noop: number;
@@ -45,7 +42,6 @@ type NoopEditEntry = {
 };
 
 
-// ─── Builder inputs ─────────────────────────────────────────────────────
 
 export interface NoopResponseInput {
 	path: string;
@@ -65,7 +61,6 @@ export interface SuccessResponseInput {
 	editMeta: ReplaceMeta;
 }
 
-// ─── Helpers ────────────────────────────────────────────────────────────
 
 
 function countDiffLines(diff: string, marker: "+" | "-"): number {
@@ -118,7 +113,6 @@ function warningsBlockOf(warnings: string[] | undefined): string {
 	return warnings?.length ? `\n\nWarnings:\n${warnings.join("\n")}` : "";
 }
 
-// ─── Builders ───────────────────────────────────────────────────────────
 
 export function buildNoopResponse(input: NoopResponseInput): ToolResult {
 	const {
@@ -190,10 +184,10 @@ export function buildChangedResponse(input: SuccessResponseInput): ToolResult {
 					CHANGED_ANCHOR_TEXT_BUDGET_BYTES
 					? block
 					: "Anchors omitted; use read for subsequent edits.";
-		})()
+			})()
 		: resultLines.length === 0
 			? "File is empty. Use edit to insert content."
-			: ""; // No anchor context → show nothing; LLM can call read for fresh anchors
+			: "";
 	const text = [anchorsBlock, warningsBlock.trimStart()]
 		.filter((section) => section.length > 0)
 		.join("\n\n");
@@ -219,4 +213,4 @@ export function buildChangedResponse(input: SuccessResponseInput): ToolResult {
 			metrics,
 		},
 	};
-}
+}

package/src/replace.ts

@@ -6,8 +6,6 @@ import type {
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { constants } from "fs";
-import { readFileSync } from "fs";
-import { access as fsAccess } from "fs/promises";
 import {
 	detectLineEnding,
 	generateDiffString,
@@ -45,6 +43,8 @@ import {
 	type ReplacePreview,
 	type ReplaceRenderState,
 } from "./replace-render";
+import { loadPrompt, loadPromptGuidelines } from "./prompts";
+import { validateFileAccess, validateFileKind, isTextFile } from "./validation";
 
 
 const hashlineEditNewLinesSchema = Type.Array(Type.String(), {
@@ -87,40 +87,15 @@ export type ReplaceRequestParams = {
 export type HashlineReplaceToolDetails = {
 	diff: string;
 	firstChangedLine?: number;
-	/**
-	 * Post-edit snapshot fingerprint. Surfaced in details only — the LLM no
-	 * longer receives or echoes it. Hosts may use this for UI hints (e.g.
-	 * "file changed since last view"). See plan W2.
-	 */
 	snapshotId?: string;
 	classification?: "noop";
 	structureOutline?: string[];
-	/**
-	 * Phase 2 C — opt-in observability surface for hosts. Never echoed in text.
-	 * Hosts can use it for adoption/regression dashboards.
-	 */
 	metrics?: ReplaceMetrics;
 };
 
-const EDIT_DESC = readFileSync(
-	new URL("../prompts/replace.md", import.meta.url),
-	"utf-8",
-).trim();
-
-const EDIT_PROMPT_SNIPPET = readFileSync(
-	new URL("../prompts/replace-snippet.md", import.meta.url),
-	"utf-8",
-).trim();
-
-
-const EDIT_PROMPT_GUIDELINES = readFileSync(
-	new URL("../prompts/replace-guidelines.md", import.meta.url),
-	"utf-8",
-)
-	.split("\n")
-	.map((line) => line.trim())
-	.filter((line) => line.startsWith("- "))
-	.map((line) => line.slice(2));
+const EDIT_DESC = loadPrompt("../prompts/replace.md");
+const EDIT_PROMPT_SNIPPET = loadPrompt("../prompts/replace-snippet.md");
+const EDIT_PROMPT_GUIDELINES = loadPromptGuidelines("../prompts/replace-guidelines.md");
 const ROOT_KEYS = new Set(["path", "edits"]);
 
 export function assertReplaceRequest(
@@ -190,38 +165,11 @@ async function executeEditPipeline(
 	}
 
 	throwIfAborted(signal);
-	try {
-		await fsAccess(absolutePath, accessMode);
-	} catch (error: unknown) {
-		const code = (error as NodeJS.ErrnoException).code;
-		if (code === "ENOENT") {
-			throw new Error(`File not found: ${path}`);
-		}
-		if (code === "EACCES" || code === "EPERM") {
-			const accessLabel =
-				accessMode & constants.W_OK ? "not writable" : "not readable";
-			throw new Error(`File is ${accessLabel}: ${path}`);
-		}
-		throw new Error(`Cannot access file: ${path}`);
-	}
+	await validateFileAccess(absolutePath, path, accessMode);
 
 	throwIfAborted(signal);
 	const file = await loadFileKindAndText(absolutePath);
-	if (file.kind === "directory") {
-		throw new Error(
-			`Path is a directory: ${path}. Use ls to inspect directories.`,
-		);
-	}
-	if (file.kind === "image") {
-		throw new Error(
-			`Path is an image file: ${path}. Hashline edit only supports text files.`,
-		);
-	}
-	if (file.kind === "binary") {
-		throw new Error(
-			`Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`,
-		);
-	}
+	validateFileKind(file, path);
 
 	throwIfAborted(signal);
 	const { bom, text: rawContent } = stripBom(file.text);
@@ -493,4 +441,4 @@ const editToolDefinition: EditToolDefinition = {
 
 export function registerReplaceTool(pi: ExtensionAPI): void {
 	pi.registerTool(editToolDefinition);
-}
+}

package/src/snapshot.ts

@@ -11,13 +11,6 @@ function formatSnapshotId(canonicalPath: string, info: { mtimeMs: number; size:
   return `v1|${canonicalPath}|${info.mtimeMs}|${info.size}`;
 }
 
-/**
- * Stat the file and return its current snapshot fingerprint.
- *
- * The snapshot is exposed only via `details.snapshotId` for host UIs (e.g.
- * "file changed since last view"). It is no longer used to reject edits or
- * surfaced in tool text — the LLM does not need to track it.
- */
 export async function getFileSnapshot(absolutePath: string): Promise<SnapshotInfo> {
   const canonicalPath = await resolveMutationTargetPath(absolutePath);
   const stats = await stat(canonicalPath);

package/src/utils.ts

@@ -1,6 +1,3 @@
-/**
- * Shared type guards and utility helpers.
- */
 
 export function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -10,18 +7,12 @@ export function hasOwn(record: Record<string, unknown>, key: string): boolean {
 	return Object.hasOwn(record, key);
 }
 
-/**
- * Return the visible lines of a text (excluding the terminal-newline sentinel).
- */
 export function getVisibleLines(text: string): string[] {
 	if (text.length === 0) return [];
 	const lines = text.split("\n");
 	return text.endsWith("\n") ? lines.slice(0, -1) : lines;
 }
 
-/**
- * Count the visible lines of a text (excluding the terminal-newline sentinel).
- */
 export function countVisibleLines(text: string): number {
 	return getVisibleLines(text).length;
 }

package/src/validation.ts

@@ -0,0 +1,46 @@
+import { constants } from "fs";
+import { access as fsAccess } from "fs/promises";
+import type { LoadedFile } from "./file-kind";
+
+export async function validateFileAccess(
+	absolutePath: string,
+	path: string,
+	accessMode: number = constants.R_OK,
+): Promise<void> {
+	try {
+		await fsAccess(absolutePath, accessMode);
+	} catch (error: unknown) {
+		const code = getErrorCode(error);
+		if (code === "ENOENT") {
+			throw new Error(`File not found: ${path}`);
+		}
+		if (code === "EACCES" || code === "EPERM") {
+			const accessLabel = accessMode & constants.W_OK ? "not writable" : "not readable";
+			throw new Error(`File is ${accessLabel}: ${path}`);
+		}
+		throw new Error(`Cannot access file: ${path}`);
+	}
+}
+
+export function validateFileKind(file: LoadedFile, path: string): void {
+	if (file.kind === "directory") {
+		throw new Error(`Path is a directory: ${path}. Use ls to inspect directories.`);
+	}
+	if (file.kind === "binary") {
+		throw new Error(`Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`);
+	}
+	if (file.kind === "image") {
+		throw new Error(`Path is an image file: ${path}. Hashline edit only supports text files.`);
+	}
+}
+
+export function isTextFile(file: LoadedFile): file is { kind: "text"; text: string; hadUtf8DecodeErrors?: true } {
+	return file.kind === "text";
+}
+
+export function getErrorCode(error: unknown): string | undefined {
+	if (error instanceof Error) {
+		return (error as NodeJS.ErrnoException).code;
+	}
+	return undefined;
+}