@oh-my-pi/pi-coding-agent 13.19.0 → 14.0.2

package/src/{patch → edit/modes}/hashline.ts

@@ -12,7 +12,33 @@
  * Reference format: `"LINENUM#HASH"` (e.g. `"5#aa"`)
  */
 
-import type { HashMismatch } from "./types";
+import * as fs from "node:fs/promises";
+import * as nodePath from "node:path";
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import type { BunFile } from "bun";
+import type { WritethroughCallback, WritethroughDeferredHandle } from "../../lsp";
+import type { ToolSession } from "../../tools";
+import { assertEditableFileContent } from "../../tools/auto-generated-guard";
+import {
+	invalidateFsScanAfterDelete,
+	invalidateFsScanAfterRename,
+	invalidateFsScanAfterWrite,
+} from "../../tools/fs-cache-invalidation";
+import { outputMeta } from "../../tools/output-meta";
+import { resolveToCwd } from "../../tools/path-utils";
+import { enforcePlanModeWrite, resolvePlanPath } from "../../tools/plan-mode-guard";
+import { generateDiffString } from "../diff";
+import { computeLineHash, formatLineHash } from "../line-hash";
+import { detectLineEnding, normalizeToLF, restoreLineEndings, stripBom } from "../normalize";
+import type { EditToolDetails, LspBatchRequest } from "../renderer";
+
+export interface HashMismatch {
+	line: number;
+	expected: string;
+	actual: string;
+}
 
 export type Anchor = { line: number; hash: string };
 export type HashlineEdit =
@@ -23,64 +49,188 @@ export type HashlineEdit =
 	| { op: "append_file"; lines: string[] }
 	| { op: "prepend_file"; lines: string[] };
 
-const NIBBLE_STR = "ZPMQVRWSNKTXJBYH";
+const HASHLINE_PREFIX_RE = /^\s*(?:>>>|>>)?\s*(?:\+?\s*(?:\d+\s*#\s*|#\s*)|\+)\s*[ZPMQVRWSNKTXJBYH]{2}:/;
+const HASHLINE_PREFIX_PLUS_RE = /^\s*(?:>>>|>>)?\s*\+\s*(?:\d+\s*#\s*|#\s*)?[ZPMQVRWSNKTXJBYH]{2}:/;
+const DIFF_PLUS_RE = /^[+](?![+])/;
+
+type LinePrefixStats = {
+	nonEmpty: number;
+	hashPrefixCount: number;
+	diffPlusHashPrefixCount: number;
+	diffPlusCount: number;
+};
+
+function collectLinePrefixStats(lines: string[]): LinePrefixStats {
+	const stats: LinePrefixStats = {
+		nonEmpty: 0,
+		hashPrefixCount: 0,
+		diffPlusHashPrefixCount: 0,
+		diffPlusCount: 0,
+	};
 
-const DICT = Array.from({ length: 256 }, (_, i) => {
-	const h = i >>> 4;
-	const l = i & 0x0f;
-	return `${NIBBLE_STR[h]}${NIBBLE_STR[l]}`;
-});
+	for (const line of lines) {
+		if (line.length === 0) continue;
+		stats.nonEmpty++;
+		if (HASHLINE_PREFIX_RE.test(line)) stats.hashPrefixCount++;
+		if (HASHLINE_PREFIX_PLUS_RE.test(line)) stats.diffPlusHashPrefixCount++;
+		if (DIFF_PLUS_RE.test(line)) stats.diffPlusCount++;
+	}
 
-const RE_SIGNIFICANT = /[\p{L}\p{N}]/u;
+	return stats;
+}
 
-/**
- * Compute a short hexadecimal hash of a single line.
- *
- * Uses xxHash32 on a trailing-whitespace-trimmed, CR-stripped line, truncated to 2 chars from
- * {@link NIBBLE_STR}. For lines containing no alphanumeric characters (only
- * punctuation/symbols/whitespace), the line number is mixed in to reduce hash collisions.
- * The line input should not include a trailing newline.
- */
-export function computeLineHash(idx: number, line: string): string {
-	line = line.replace(/\r/g, "").trimEnd();
+export function stripNewLinePrefixes(lines: string[]): string[] {
+	const { nonEmpty, hashPrefixCount, diffPlusHashPrefixCount, diffPlusCount } = collectLinePrefixStats(lines);
+	if (nonEmpty === 0) return lines;
+
+	const stripHash = hashPrefixCount > 0 && hashPrefixCount === nonEmpty;
+	const stripPlus =
+		!stripHash && diffPlusHashPrefixCount === 0 && diffPlusCount > 0 && diffPlusCount >= nonEmpty * 0.5;
+	if (!stripHash && !stripPlus && diffPlusHashPrefixCount === 0) return lines;
+
+	return lines.map(line => {
+		if (stripHash) return line.replace(HASHLINE_PREFIX_RE, "");
+		if (stripPlus) return line.replace(DIFF_PLUS_RE, "");
+		if (diffPlusHashPrefixCount > 0 && HASHLINE_PREFIX_PLUS_RE.test(line)) {
+			return line.replace(HASHLINE_PREFIX_RE, "");
+		}
+		return line;
+	});
+}
+
+export function stripHashlinePrefixes(lines: string[]): string[] {
+	const { nonEmpty, hashPrefixCount } = collectLinePrefixStats(lines);
+	if (nonEmpty === 0 || hashPrefixCount !== nonEmpty) return lines;
+	return lines.map(line => line.replace(HASHLINE_PREFIX_RE, ""));
+}
+
+const linesSchema = Type.Union([
+	Type.Array(Type.String(), { description: "content (preferred format)" }),
+	Type.String(),
+	Type.Null(),
+]);
+
+const locSchema = Type.Union(
+	[
+		Type.Literal("append"),
+		Type.Literal("prepend"),
+		Type.Object({ append: Type.String({ description: "anchor" }) }),
+		Type.Object({ prepend: Type.String({ description: "anchor" }) }),
+		Type.Object({
+			range: Type.Object({
+				pos: Type.String({ description: "first line to edit (inclusive)" }),
+				end: Type.String({ description: "last line to edit (inclusive)" }),
+			}),
+		}),
+	],
+	{ description: "insert location" },
+);
+
+export const hashlineEditSchema = Type.Object(
+	{
+		loc: locSchema,
+		content: linesSchema,
+	},
+	{ additionalProperties: false },
+);
+
+export const hashlineEditParamsSchema = Type.Object(
+	{
+		path: Type.String({ description: "path" }),
+		edits: Type.Array(hashlineEditSchema, { description: "edits over $path" }),
+		delete: Type.Optional(Type.Boolean({ description: "If true, delete $path" })),
+		move: Type.Optional(Type.String({ description: "If set, move $path to $move" })),
+	},
+	{ additionalProperties: false },
+);
+
+export type HashlineToolEdit = Static<typeof hashlineEditSchema>;
+export type HashlineParams = Static<typeof hashlineEditParamsSchema>;
+
+interface ExecuteHashlineModeOptions {
+	session: ToolSession;
+	params: HashlineParams;
+	signal?: AbortSignal;
+	batchRequest?: LspBatchRequest;
+	writethrough: WritethroughCallback;
+	beginDeferredDiagnosticsForPath: (path: string) => WritethroughDeferredHandle;
+}
 
-	let seed = 0;
-	if (!RE_SIGNIFICANT.test(line)) {
-		seed = idx;
+export function hashlineParseText(edit: string[] | string | null): string[] {
+	if (edit === null) return [];
+	if (typeof edit === "string") {
+		const normalizedEdit = edit.endsWith("\n") ? edit.slice(0, -1) : edit;
+		edit = normalizedEdit.replaceAll("\r", "").split("\n");
 	}
-	return DICT[Bun.hash.xxHash32(line, seed) & 0xff];
+	return stripNewLinePrefixes(edit);
 }
 
-/**
- * Formats a tag given the line number and text.
- */
-export function formatLineTag(line: number, lines: string): string {
-	return `${line}#${computeLineHash(line, lines)}`;
+export function isHashlineParams(params: unknown): params is HashlineParams {
+	return (
+		typeof params === "object" &&
+		params !== null &&
+		"edits" in params &&
+		Array.isArray(params.edits) &&
+		(params.edits.length === 0 ||
+			(typeof params.edits[0] === "object" && params.edits[0] !== null && "loc" in params.edits[0]))
+	);
 }
 
-/**
- * Format file text with hashline prefixes for display.
- *
- * Each line becomes `LINENUM#HASH:TEXT` where LINENUM is 1-indexed.
- *
- * @param text - Raw file text string
- * @param startLine - First line number (1-indexed, defaults to 1)
- * @returns Formatted string with one hashline-prefixed line per input line
- *
- * @example
- * ```
- * formatHashLines("function hi() {\n  return;\n}")
- * // "1#HH:function hi() {\n2#HH:  return;\n3#HH:}"
- * ```
- */
-export function formatHashLines(text: string, startLine = 1): string {
-	const lines = text.split("\n");
-	return lines
-		.map((line, i) => {
-			const num = startLine + i;
-			return `${formatLineTag(num, line)}:${line}`;
-		})
-		.join("\n");
+function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
+	return edits.map(resolveEditAnchor);
+}
+
+function tryParseTag(raw: string): Anchor | undefined {
+	try {
+		return parseTag(raw);
+	} catch {
+		return undefined;
+	}
+}
+
+function requireParsedAnchor(raw: string, op: "append" | "prepend"): Anchor {
+	const anchor = tryParseTag(raw);
+	if (!anchor) throw new Error(`${op} requires a valid anchor.`);
+	return anchor;
+}
+
+function requireParsedRange(range: { pos: string; end: string }): { pos: Anchor; end: Anchor } {
+	const pos = tryParseTag(range.pos);
+	const end = tryParseTag(range.end);
+	if (!pos || !end) throw new Error("range requires valid pos and end anchors.");
+	return { pos, end };
+}
+
+function resolveEditAnchor(edit: HashlineToolEdit): HashlineEdit {
+	const lines = hashlineParseText(edit.content);
+	const loc = edit.loc;
+
+	if (loc === "append") {
+		return { op: "append_file", lines };
+	}
+
+	if (loc === "prepend") {
+		return { op: "prepend_file", lines };
+	}
+
+	if (typeof loc !== "object") {
+		throw new Error(`Invalid loc value: ${JSON.stringify(loc)}`);
+	}
+
+	if ("append" in loc) {
+		return { op: "append_at", pos: requireParsedAnchor(loc.append, "append"), lines };
+	}
+
+	if ("prepend" in loc) {
+		return { op: "prepend_at", pos: requireParsedAnchor(loc.prepend, "prepend"), lines };
+	}
+
+	if ("range" in loc) {
+		const { pos, end } = requireParsedRange(loc.range);
+		return { op: "replace_range", pos, end, lines };
+	}
+
+	throw new Error("Unknown loc shape. Expected append, prepend, or range.");
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -96,6 +246,77 @@ export interface HashlineStreamOptions {
 	maxChunkBytes?: number;
 }
 
+interface ResolvedHashlineStreamOptions {
+	startLine: number;
+	maxChunkLines: number;
+	maxChunkBytes: number;
+}
+
+type HashlineLineFormatter = (lineNumber: number, line: string) => string;
+
+interface HashlineChunkEmitter {
+	pushLine: (line: string) => string[];
+	flush: () => string | undefined;
+}
+
+function resolveHashlineStreamOptions(options: HashlineStreamOptions): ResolvedHashlineStreamOptions {
+	return {
+		startLine: options.startLine ?? 1,
+		maxChunkLines: options.maxChunkLines ?? 200,
+		maxChunkBytes: options.maxChunkBytes ?? 64 * 1024,
+	};
+}
+
+function createHashlineChunkEmitter(
+	options: ResolvedHashlineStreamOptions,
+	formatLine: HashlineLineFormatter,
+): HashlineChunkEmitter {
+	let lineNumber = options.startLine;
+	let outLines: string[] = [];
+	let outBytes = 0;
+
+	const flush = (): string | undefined => {
+		if (outLines.length === 0) return undefined;
+		const chunk = outLines.join("\n");
+		outLines = [];
+		outBytes = 0;
+		return chunk;
+	};
+
+	const pushLine = (line: string): string[] => {
+		const formatted = formatLine(lineNumber, line);
+		lineNumber++;
+
+		const chunksToYield: string[] = [];
+		const sepBytes = outLines.length === 0 ? 0 : 1;
+		const lineBytes = Buffer.byteLength(formatted, "utf-8");
+
+		if (
+			outLines.length > 0 &&
+			(outLines.length >= options.maxChunkLines || outBytes + sepBytes + lineBytes > options.maxChunkBytes)
+		) {
+			const flushed = flush();
+			if (flushed) chunksToYield.push(flushed);
+		}
+
+		outLines.push(formatted);
+		outBytes += (outLines.length === 1 ? 0 : 1) + lineBytes;
+
+		if (outLines.length >= options.maxChunkLines || outBytes >= options.maxChunkBytes) {
+			const flushed = flush();
+			if (flushed) chunksToYield.push(flushed);
+		}
+
+		return chunksToYield;
+	};
+
+	return { pushLine, flush };
+}
+
+function formatHashlineStreamLine(lineNumber: number, line: string): string {
+	return `${formatLineHash(lineNumber, line)}:${line}`;
+}
+
 function isReadableStream(value: unknown): value is ReadableStream<Uint8Array> {
 	return (
 		typeof value === "object" &&
@@ -129,52 +350,13 @@ export async function* streamHashLinesFromUtf8(
 	source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
 	options: HashlineStreamOptions = {},
 ): AsyncGenerator<string> {
-	const startLine = options.startLine ?? 1;
-	const maxChunkLines = options.maxChunkLines ?? 200;
-	const maxChunkBytes = options.maxChunkBytes ?? 64 * 1024;
+	const resolvedOptions = resolveHashlineStreamOptions(options);
 	const decoder = new TextDecoder("utf-8");
 	const chunks = isReadableStream(source) ? bytesFromReadableStream(source) : source;
-	let lineNum = startLine;
 	let pending = "";
 	let sawAnyText = false;
 	let endedWithNewline = false;
-	let outLines: string[] = [];
-	let outBytes = 0;
-
-	const flush = (): string | undefined => {
-		if (outLines.length === 0) return undefined;
-		const chunk = outLines.join("\n");
-		outLines = [];
-		outBytes = 0;
-		return chunk;
-	};
-
-	const pushLine = (line: string): string[] => {
-		const formatted = `${lineNum}#${computeLineHash(lineNum, line)}:${line}`;
-		lineNum++;
-
-		const chunksToYield: string[] = [];
-		const sepBytes = outLines.length === 0 ? 0 : 1; // "\n"
-		const lineBytes = Buffer.byteLength(formatted, "utf-8");
-
-		if (
-			outLines.length > 0 &&
-			(outLines.length >= maxChunkLines || outBytes + sepBytes + lineBytes > maxChunkBytes)
-		) {
-			const flushed = flush();
-			if (flushed) chunksToYield.push(flushed);
-		}
-
-		outLines.push(formatted);
-		outBytes += (outLines.length === 1 ? 0 : 1) + lineBytes;
-
-		if (outLines.length >= maxChunkLines || outBytes >= maxChunkBytes) {
-			const flushed = flush();
-			if (flushed) chunksToYield.push(flushed);
-		}
-
-		return chunksToYield;
-	};
+	const emitter = createHashlineChunkEmitter(resolvedOptions, formatHashlineStreamLine);
 
 	const consumeText = (text: string): string[] => {
 		if (text.length === 0) return [];
@@ -187,7 +369,7 @@ export async function* streamHashLinesFromUtf8(
 			const line = pending.slice(0, idx);
 			pending = pending.slice(idx + 1);
 			endedWithNewline = true;
-			chunksToYield.push(...pushLine(line));
+			chunksToYield.push(...emitter.pushLine(line));
 		}
 		if (pending.length > 0) endedWithNewline = false;
 		return chunksToYield;
@@ -203,17 +385,17 @@ export async function* streamHashLinesFromUtf8(
 	}
 	if (!sawAnyText) {
 		// Mirror `"".split("\n")` behavior: one empty line.
-		for (const out of pushLine("")) {
+		for (const out of emitter.pushLine("")) {
 			yield out;
 		}
 	} else if (pending.length > 0 || endedWithNewline) {
 		// Emit the final line (may be empty if the file ended with a newline).
-		for (const out of pushLine(pending)) {
+		for (const out of emitter.pushLine(pending)) {
 			yield out;
 		}
 	}
 
-	const last = flush();
+	const last = emitter.flush();
 	if (last) yield last;
 }
 
@@ -226,72 +408,34 @@ export async function* streamHashLinesFromLines(
 	lines: Iterable<string> | AsyncIterable<string>,
 	options: HashlineStreamOptions = {},
 ): AsyncGenerator<string> {
-	const startLine = options.startLine ?? 1;
-	const maxChunkLines = options.maxChunkLines ?? 200;
-	const maxChunkBytes = options.maxChunkBytes ?? 64 * 1024;
-
-	let lineNum = startLine;
-	let outLines: string[] = [];
-	let outBytes = 0;
+	const resolvedOptions = resolveHashlineStreamOptions(options);
+	const emitter = createHashlineChunkEmitter(resolvedOptions, formatHashlineStreamLine);
 	let sawAnyLine = false;
-	const flush = (): string | undefined => {
-		if (outLines.length === 0) return undefined;
-		const chunk = outLines.join("\n");
-		outLines = [];
-		outBytes = 0;
-		return chunk;
-	};
-
-	const pushLine = (line: string): string[] => {
-		sawAnyLine = true;
-		const formatted = `${lineNum}#${computeLineHash(lineNum, line)}:${line}`;
-		lineNum++;
-
-		const chunksToYield: string[] = [];
-		const sepBytes = outLines.length === 0 ? 0 : 1;
-		const lineBytes = Buffer.byteLength(formatted, "utf-8");
-
-		if (
-			outLines.length > 0 &&
-			(outLines.length >= maxChunkLines || outBytes + sepBytes + lineBytes > maxChunkBytes)
-		) {
-			const flushed = flush();
-			if (flushed) chunksToYield.push(flushed);
-		}
-
-		outLines.push(formatted);
-		outBytes += (outLines.length === 1 ? 0 : 1) + lineBytes;
-
-		if (outLines.length >= maxChunkLines || outBytes >= maxChunkBytes) {
-			const flushed = flush();
-			if (flushed) chunksToYield.push(flushed);
-		}
-
-		return chunksToYield;
-	};
 
 	const asyncIterator = (lines as AsyncIterable<string>)[Symbol.asyncIterator];
 	if (typeof asyncIterator === "function") {
 		for await (const line of lines as AsyncIterable<string>) {
-			for (const out of pushLine(line)) {
+			sawAnyLine = true;
+			for (const out of emitter.pushLine(line)) {
 				yield out;
 			}
 		}
 	} else {
 		for (const line of lines as Iterable<string>) {
-			for (const out of pushLine(line)) {
+			sawAnyLine = true;
+			for (const out of emitter.pushLine(line)) {
 				yield out;
 			}
 		}
 	}
 	if (!sawAnyLine) {
 		// Mirror `"".split("\n")` behavior: one empty line.
-		for (const out of pushLine("")) {
+		for (const out of emitter.pushLine("")) {
 			yield out;
 		}
 	}
 
-	const last = flush();
+	const last = emitter.flush();
 	if (last) yield last;
 }
 
@@ -454,124 +598,48 @@ function maybeWarnSuspiciousUnicodeEscapePlaceholder(edits: HashlineEdit[], warn
 		);
 	}
 }
-// ═══════════════════════════════════════════════════════════════════════════
-// Edit Application
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Apply an array of hashline edits to file content.
- *
- * Each edit operation identifies target lines directly (`replace`,
- * `append`, `prepend`). Line references are resolved via {@link parseTag}
- * and hashes validated before any mutation.
- *
- * Edits are sorted bottom-up (highest effective line first) so earlier
- * splices don't invalidate later line numbers.
- *
- * @returns The modified content and the 1-indexed first changed line number
- */
-export function applyHashlineEdits(
-	text: string,
-	edits: HashlineEdit[],
-): {
-	lines: string;
-	firstChangedLine: number | undefined;
-	warnings?: string[];
-	noopEdits?: Array<{ editIndex: number; loc: string; current: string }>;
-} {
-	if (edits.length === 0) {
-		return { lines: text, firstChangedLine: undefined };
-	}
 
-	const fileLines = text.split("\n");
-	const originalFileLines = [...fileLines];
-	let firstChangedLine: number | undefined;
-	const noopEdits: Array<{ editIndex: number; loc: string; current: string }> = [];
-	const warnings: string[] = [];
+function runHashlinePreflightSanitizers(edits: HashlineEdit[], warnings: string[]): void {
+	maybeAutocorrectEscapedTabIndentation(edits, warnings);
+	maybeWarnSuspiciousUnicodeEscapePlaceholder(edits, warnings);
+}
 
-	// Pre-validate: collect all hash mismatches before mutating
-	const mismatches: HashMismatch[] = [];
-	function validateRef(ref: { line: number; hash: string }): boolean {
-		if (ref.line < 1 || ref.line > fileLines.length) {
-			throw new Error(`Line ${ref.line} does not exist (file has ${fileLines.length} lines)`);
-		}
-		const actualHash = computeLineHash(ref.line, fileLines[ref.line - 1]);
-		if (actualHash === ref.hash) {
-			return true;
-		}
-		mismatches.push({ line: ref.line, expected: ref.hash, actual: actualHash });
-		return false;
+function ensureHashlineEditHasContent(edit: HashlineEdit): void {
+	if (edit.lines.length === 0) {
+		edit.lines = [""];
 	}
-	for (const edit of edits) {
-		switch (edit.op) {
-			case "replace_line": {
-				if (!validateRef(edit.pos)) continue;
-				break;
-			}
-			case "replace_range": {
-				const startValid = validateRef(edit.pos);
-				const endValid = validateRef(edit.end);
-				if (!startValid || !endValid) continue;
-				if (edit.pos.line > edit.end.line) {
-					throw new Error(`Range start line ${edit.pos.line} must be <= end line ${edit.end.line}`);
-				}
-				break;
-			}
-			case "append_at":
-			case "prepend_at": {
-				if (!validateRef(edit.pos)) continue;
-				if (edit.lines.length === 0) {
-					edit.lines = [""]; // insert an empty line
-				}
-				break;
-			}
-			case "append_file":
-			case "prepend_file": {
-				if (edit.lines.length === 0) {
-					edit.lines = [""]; // insert an empty line
-				}
-				break;
-			}
-		}
+}
+
+function collectBoundaryDuplicationWarning(edit: HashlineEdit, originalFileLines: string[], warnings: string[]): void {
+	let endLine: number;
+	switch (edit.op) {
+		case "replace_line":
+			endLine = edit.pos.line;
+			break;
+		case "replace_range":
+			endLine = edit.end.line;
+			break;
+		default:
+			return;
 	}
-	if (mismatches.length > 0) {
-		throw new HashlineMismatchError(mismatches, fileLines);
+
+	if (edit.lines.length === 0) return;
+	const nextSurvivingIdx = endLine;
+	if (nextSurvivingIdx >= originalFileLines.length) return;
+	const nextSurvivingLine = originalFileLines[nextSurvivingIdx];
+	const lastInsertedLine = edit.lines[edit.lines.length - 1];
+	const trimmedNext = nextSurvivingLine.trim();
+	const trimmedLast = lastInsertedLine.trim();
+	if (trimmedLast.length > 0 && trimmedLast === trimmedNext) {
+		const tag = formatLineHash(endLine + 1, nextSurvivingLine);
+		warnings.push(
+			`Possible boundary duplication: your last replacement line \`${trimmedLast}\` is identical to the next surviving line ${tag}. ` +
+				`If you meant to replace the entire block, set \`end\` to ${tag} instead.`,
+		);
 	}
-	maybeAutocorrectEscapedTabIndentation(edits, warnings);
-	maybeWarnSuspiciousUnicodeEscapePlaceholder(edits, warnings);
+}
 
-	// Warn when a replace_range/replace_line's last inserted line duplicates the next surviving line.
-	// This catches the common boundary-overreach pattern where the agent includes a closing delimiter
-	// in the replacement but sets `end` to the line before the delimiter, causing duplication.
-	for (const edit of edits) {
-		let endLine: number;
-		switch (edit.op) {
-			case "replace_line":
-				endLine = edit.pos.line;
-				break;
-			case "replace_range":
-				endLine = edit.end.line;
-				break;
-			default:
-				continue;
-		}
-		if (edit.lines.length === 0) continue;
-		const nextSurvivingIdx = endLine; // 0-indexed: endLine (1-indexed) is the next line after `end`
-		if (nextSurvivingIdx >= originalFileLines.length) continue;
-		const nextSurvivingLine = originalFileLines[nextSurvivingIdx];
-		const lastInsertedLine = edit.lines[edit.lines.length - 1];
-		const trimmedNext = nextSurvivingLine.trim();
-		const trimmedLast = lastInsertedLine.trim();
-		// Only warn for non-trivial lines to avoid false positives on blank lines or bare punctuation
-		if (trimmedLast.length > 0 && trimmedLast === trimmedNext) {
-			const tag = formatLineTag(endLine + 1, nextSurvivingLine);
-			warnings.push(
-				`Possible boundary duplication: your last replacement line \`${trimmedLast}\` is identical to the next surviving line ${tag}. ` +
-					`If you meant to replace the entire block, set \`end\` to ${tag} instead.`,
-			);
-		}
-	}
-	// Deduplicate identical edits targeting the same line(s)
+function dedupeHashlineEdits(edits: HashlineEdit[]): void {
 	const seenEditKeys = new Map<string, number>();
 	const dedupIndices = new Set<number>();
 	for (let i = 0; i < edits.length; i++) {
@@ -604,137 +672,234 @@ export function applyHashlineEdits(
 			seenEditKeys.set(dstKey, i);
 		}
 	}
-	if (dedupIndices.size > 0) {
-		for (let i = edits.length - 1; i >= 0; i--) {
-			if (dedupIndices.has(i)) edits.splice(i, 1);
-		}
+	if (dedupIndices.size === 0) return;
+	for (let i = edits.length - 1; i >= 0; i--) {
+		if (dedupIndices.has(i)) edits.splice(i, 1);
 	}
+}
 
-	// Compute sort key (descending) — bottom-up application
-	const annotated = edits.map((edit, idx) => {
-		let sortLine: number;
-		let precedence: number;
-		switch (edit.op) {
-			case "replace_line":
-				sortLine = edit.pos.line;
-				precedence = 0;
-				break;
-			case "replace_range":
-				sortLine = edit.end.line;
-				precedence = 0;
-				break;
-			case "append_at":
-				sortLine = edit.pos.line;
-				precedence = 1;
-				break;
-			case "prepend_at":
-				sortLine = edit.pos.line;
-				precedence = 2;
-				break;
-			case "append_file":
-				sortLine = fileLines.length + 1;
-				precedence = 1;
-				break;
-			case "prepend_file":
-				sortLine = 0;
-				precedence = 2;
-				break;
-		}
-		return { edit, idx, sortLine, precedence };
-	});
-
-	annotated.sort((a, b) => b.sortLine - a.sortLine || a.precedence - b.precedence || a.idx - b.idx);
+function getHashlineEditSortKey(edit: HashlineEdit, fileLineCount: number): { sortLine: number; precedence: number } {
+	switch (edit.op) {
+		case "replace_line":
+			return { sortLine: edit.pos.line, precedence: 0 };
+		case "replace_range":
+			return { sortLine: edit.end.line, precedence: 0 };
+		case "append_at":
+			return { sortLine: edit.pos.line, precedence: 1 };
+		case "prepend_at":
+			return { sortLine: edit.pos.line, precedence: 2 };
+		case "append_file":
+			return { sortLine: fileLineCount + 1, precedence: 1 };
+		case "prepend_file":
+			return { sortLine: 0, precedence: 2 };
+	}
+}
 
-	// Apply edits bottom-up
-	for (const { edit, idx } of annotated) {
-		switch (edit.op) {
-			case "replace_line": {
-				const origLines = originalFileLines.slice(edit.pos.line - 1, edit.pos.line);
-				const newLines = edit.lines;
-				if (origLines.length === newLines.length && origLines.every((line, i) => line === newLines[i])) {
-					noopEdits.push({
-						editIndex: idx,
-						loc: `${edit.pos.line}#${edit.pos.hash}`,
-						current: origLines.join("\n"),
-					});
-					break;
-				}
-				fileLines.splice(edit.pos.line - 1, 1, ...newLines);
-				trackFirstChanged(edit.pos.line);
-				break;
-			}
-			case "replace_range": {
-				const count = edit.end.line - edit.pos.line + 1;
-				fileLines.splice(edit.pos.line - 1, count, ...edit.lines);
-				trackFirstChanged(edit.pos.line);
+function applyHashlineEditToLines(
+	edit: HashlineEdit,
+	fileLines: string[],
+	originalFileLines: string[],
+	editIndex: number,
+	noopEdits: Array<{ editIndex: number; loc: string; current: string }>,
+	trackFirstChanged: (line: number) => void,
+): void {
+	switch (edit.op) {
+		case "replace_line": {
+			const origLines = originalFileLines.slice(edit.pos.line - 1, edit.pos.line);
+			const newLines = edit.lines;
+			if (origLines.length === newLines.length && origLines.every((line, i) => line === newLines[i])) {
+				noopEdits.push({
+					editIndex,
+					loc: `${edit.pos.line}#${edit.pos.hash}`,
+					current: origLines.join("\n"),
+				});
 				break;
 			}
-			case "append_at": {
-				const inserted = edit.lines;
-				if (inserted.length === 0) {
-					noopEdits.push({
-						editIndex: idx,
-						loc: `${edit.pos.line}#${edit.pos.hash}`,
-						current: originalFileLines[edit.pos.line - 1],
-					});
-					break;
-				}
-				fileLines.splice(edit.pos.line, 0, ...inserted);
-				trackFirstChanged(edit.pos.line + 1);
+			fileLines.splice(edit.pos.line - 1, 1, ...newLines);
+			trackFirstChanged(edit.pos.line);
+			break;
+		}
+		case "replace_range": {
+			const count = edit.end.line - edit.pos.line + 1;
+			fileLines.splice(edit.pos.line - 1, count, ...edit.lines);
+			trackFirstChanged(edit.pos.line);
+			break;
+		}
+		case "append_at": {
+			const inserted = edit.lines;
+			if (inserted.length === 0) {
+				noopEdits.push({
+					editIndex,
+					loc: `${edit.pos.line}#${edit.pos.hash}`,
+					current: originalFileLines[edit.pos.line - 1],
+				});
 				break;
 			}
-			case "prepend_at": {
-				const inserted = edit.lines;
-				if (inserted.length === 0) {
-					noopEdits.push({
-						editIndex: idx,
-						loc: `${edit.pos.line}#${edit.pos.hash}`,
-						current: originalFileLines[edit.pos.line - 1],
-					});
-					break;
-				}
-				fileLines.splice(edit.pos.line - 1, 0, ...inserted);
-				trackFirstChanged(edit.pos.line);
+			fileLines.splice(edit.pos.line, 0, ...inserted);
+			trackFirstChanged(edit.pos.line + 1);
+			break;
+		}
+		case "prepend_at": {
+			const inserted = edit.lines;
+			if (inserted.length === 0) {
+				noopEdits.push({
+					editIndex,
+					loc: `${edit.pos.line}#${edit.pos.hash}`,
+					current: originalFileLines[edit.pos.line - 1],
+				});
 				break;
 			}
-			case "append_file": {
-				const inserted = edit.lines;
-				if (inserted.length === 0) {
-					noopEdits.push({ editIndex: idx, loc: "EOF", current: "" });
-					break;
-				}
-				if (fileLines.length === 1 && fileLines[0] === "") {
-					fileLines.splice(0, 1, ...inserted);
-					trackFirstChanged(1);
-				} else {
-					fileLines.splice(fileLines.length, 0, ...inserted);
-					trackFirstChanged(fileLines.length - inserted.length + 1);
-				}
+			fileLines.splice(edit.pos.line - 1, 0, ...inserted);
+			trackFirstChanged(edit.pos.line);
+			break;
+		}
+		case "append_file": {
+			const inserted = edit.lines;
+			if (inserted.length === 0) {
+				noopEdits.push({ editIndex, loc: "EOF", current: "" });
 				break;
 			}
-			case "prepend_file": {
-				const inserted = edit.lines;
-				if (inserted.length === 0) {
-					noopEdits.push({ editIndex: idx, loc: "BOF", current: "" });
-					break;
-				}
-				if (fileLines.length === 1 && fileLines[0] === "") {
-					fileLines.splice(0, 1, ...inserted);
-				} else {
-					fileLines.splice(0, 0, ...inserted);
-				}
+			if (fileLines.length === 1 && fileLines[0] === "") {
+				fileLines.splice(0, 1, ...inserted);
 				trackFirstChanged(1);
+			} else {
+				fileLines.splice(fileLines.length, 0, ...inserted);
+				trackFirstChanged(fileLines.length - inserted.length + 1);
+			}
+			break;
+		}
+		case "prepend_file": {
+			const inserted = edit.lines;
+			if (inserted.length === 0) {
+				noopEdits.push({ editIndex, loc: "BOF", current: "" });
 				break;
 			}
+			if (fileLines.length === 1 && fileLines[0] === "") {
+				fileLines.splice(0, 1, ...inserted);
+			} else {
+				fileLines.splice(0, 0, ...inserted);
+			}
+			trackFirstChanged(1);
+			break;
 		}
 	}
+}
 
+function buildHashlineEditResult(params: {
+	fileLines: string[];
+	firstChangedLine: number | undefined;
+	warnings: string[];
+	noopEdits: Array<{ editIndex: number; loc: string; current: string }>;
+}): {
+	lines: string;
+	firstChangedLine: number | undefined;
+	warnings?: string[];
+	noopEdits?: Array<{ editIndex: number; loc: string; current: string }>;
+} {
+	const { fileLines, firstChangedLine, warnings, noopEdits } = params;
 	return {
 		lines: fileLines.join("\n"),
 		firstChangedLine,
 		...(warnings.length > 0 ? { warnings } : {}),
 		...(noopEdits.length > 0 ? { noopEdits } : {}),
 	};
+}
+
+function validateHashlineEditRefs(edits: HashlineEdit[], fileLines: string[]): HashMismatch[] {
+	const mismatches: HashMismatch[] = [];
+	for (const edit of edits) {
+		switch (edit.op) {
+			case "replace_line":
+				validateHashlineRef(edit.pos);
+				break;
+			case "replace_range":
+				validateHashlineRef(edit.pos);
+				validateHashlineRef(edit.end);
+				if (edit.pos.line > edit.end.line) {
+					throw new Error(`Range start line ${edit.pos.line} must be <= end line ${edit.end.line}`);
+				}
+				break;
+			case "append_at":
+			case "prepend_at":
+				validateHashlineRef(edit.pos);
+				ensureHashlineEditHasContent(edit);
+				break;
+			case "append_file":
+			case "prepend_file":
+				ensureHashlineEditHasContent(edit);
+				break;
+		}
+	}
+	return mismatches;
+
+	function validateHashlineRef(ref: { line: number; hash: string }): void {
+		if (ref.line < 1 || ref.line > fileLines.length) {
+			throw new Error(`Line ${ref.line} does not exist (file has ${fileLines.length} lines)`);
+		}
+		const actualHash = computeLineHash(ref.line, fileLines[ref.line - 1]);
+		if (actualHash === ref.hash) {
+			return;
+		}
+		mismatches.push({ line: ref.line, expected: ref.hash, actual: actualHash });
+	}
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Edit Application
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Apply an array of hashline edits to file content.
+ *
+ * Each edit operation identifies target lines directly (`replace`,
+ * `append`, `prepend`). Line references are resolved via {@link parseTag}
+ * and hashes validated before any mutation.
+ *
+ * Edits are sorted bottom-up (highest effective line first) so earlier
+ * splices don't invalidate later line numbers.
+ *
+ * @returns The modified content and the 1-indexed first changed line number
+ */
+export function applyHashlineEdits(
+	text: string,
+	edits: HashlineEdit[],
+): {
+	lines: string;
+	firstChangedLine: number | undefined;
+	warnings?: string[];
+	noopEdits?: Array<{ editIndex: number; loc: string; current: string }>;
+} {
+	if (edits.length === 0) {
+		return { lines: text, firstChangedLine: undefined };
+	}
+
+	const fileLines = text.split("\n");
+	const originalFileLines = [...fileLines];
+	let firstChangedLine: number | undefined;
+	const noopEdits: Array<{ editIndex: number; loc: string; current: string }> = [];
+	const warnings: string[] = [];
+
+	const mismatches = validateHashlineEditRefs(edits, fileLines);
+	if (mismatches.length > 0) {
+		throw new HashlineMismatchError(mismatches, fileLines);
+	}
+	runHashlinePreflightSanitizers(edits, warnings);
+	for (const edit of edits) {
+		collectBoundaryDuplicationWarning(edit, originalFileLines, warnings);
+	}
+	dedupeHashlineEdits(edits);
+
+	const annotated = edits
+		.map((edit, idx) => {
+			const { sortLine, precedence } = getHashlineEditSortKey(edit, fileLines.length);
+			return { edit, idx, sortLine, precedence };
+		})
+		.sort((a, b) => b.sortLine - a.sortLine || a.precedence - b.precedence || a.idx - b.idx);
+
+	for (const { edit, idx } of annotated) {
+		applyHashlineEditToLines(edit, fileLines, originalFileLines, idx, noopEdits, trackFirstChanged);
+	}
+
+	return buildHashlineEditResult({ fileLines, firstChangedLine, warnings, noopEdits });
 
 	function trackFirstChanged(line: number): void {
 		if (firstChangedLine === undefined || line < firstChangedLine) {
@@ -959,3 +1124,218 @@ export function buildCompactHashlineDiffPreview(
 
 	return { preview: out.join("\n"), addedLines, removedLines };
 }
+
+export async function computeHashlineDiff(
+	input: { path: string; edits: HashlineEdit[]; move?: string },
+	cwd: string,
+): Promise<
+	| {
+			diff: string;
+			firstChangedLine: number | undefined;
+	  }
+	| {
+			error: string;
+	  }
+> {
+	const { path, edits, move } = input;
+	const absolutePath = resolveToCwd(path, cwd);
+	const movePath = move ? resolveToCwd(move, cwd) : undefined;
+	const isMoveOnly = Boolean(movePath) && movePath !== absolutePath && edits.length === 0;
+
+	try {
+		const file = Bun.file(absolutePath);
+
+		if (movePath === absolutePath) {
+			return { error: "move path is the same as source path" };
+		}
+		if (isMoveOnly) {
+			return { diff: "", firstChangedLine: undefined };
+		}
+
+		const rawContent = await readHashlineFileText(file, path);
+
+		const { text: content } = stripBom(rawContent);
+		const normalizedContent = normalizeToLF(content);
+		const result = applyHashlineEdits(normalizedContent, edits);
+		if (normalizedContent === result.lines && !move) {
+			return { error: `No changes would be made to ${path}. The edits produce identical content.` };
+		}
+
+		return generateDiffString(normalizedContent, result.lines);
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+async function readHashlineFileText(file: BunFile, path: string): Promise<string> {
+	try {
+		return await file.text();
+	} catch (error) {
+		if (isEnoent(error)) {
+			throw new Error(`File not found: ${path}`);
+		}
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(message || `Unable to read ${path}`);
+	}
+}
+
+export async function executeHashlineMode(
+	options: ExecuteHashlineModeOptions,
+): Promise<AgentToolResult<EditToolDetails, typeof hashlineEditParamsSchema>> {
+	const { session, params, signal, batchRequest, writethrough, beginDeferredDiagnosticsForPath } = options;
+	const { path, edits, delete: deleteFile, move } = params;
+
+	enforcePlanModeWrite(session, path, { op: deleteFile ? "delete" : "update", move });
+
+	if (path.endsWith(".ipynb") && edits?.length > 0) {
+		throw new Error("Cannot edit Jupyter notebooks with the Edit tool. Use the NotebookEdit tool instead.");
+	}
+
+	const absolutePath = resolvePlanPath(session, path);
+	const resolvedMove = move ? resolvePlanPath(session, move) : undefined;
+	if (resolvedMove === absolutePath) {
+		throw new Error("move path is the same as source path");
+	}
+
+	const sourceFile = Bun.file(absolutePath);
+	const sourceExists = await sourceFile.exists();
+	const isMoveOnly = Boolean(resolvedMove) && edits.length === 0;
+
+	if (deleteFile) {
+		if (sourceExists) {
+			await sourceFile.unlink();
+		}
+		invalidateFsScanAfterDelete(absolutePath);
+		return {
+			content: [{ type: "text", text: `Deleted ${path}` }],
+			details: {
+				diff: "",
+				op: "delete",
+				meta: outputMeta().get(),
+			},
+		};
+	}
+
+	if (isMoveOnly && resolvedMove) {
+		if (!sourceExists) {
+			throw new Error(`File not found: ${path}`);
+		}
+		const parentDir = nodePath.dirname(resolvedMove);
+		if (parentDir && parentDir !== ".") {
+			await fs.mkdir(parentDir, { recursive: true });
+		}
+		await fs.rename(absolutePath, resolvedMove);
+		invalidateFsScanAfterRename(absolutePath, resolvedMove);
+		return {
+			content: [{ type: "text", text: `Moved ${path} to ${move}` }],
+			details: {
+				diff: "",
+				op: "update",
+				move,
+				meta: outputMeta().get(),
+			},
+		};
+	}
+
+	if (!sourceExists) {
+		const lines: string[] = [];
+		for (const edit of edits) {
+			if (edit.loc === "append") {
+				lines.push(...hashlineParseText(edit.content));
+			} else if (edit.loc === "prepend") {
+				lines.unshift(...hashlineParseText(edit.content));
+			} else {
+				throw new Error(`File not found: ${path}`);
+			}
+		}
+
+		await Bun.write(absolutePath, lines.join("\n"));
+		invalidateFsScanAfterWrite(absolutePath);
+		return {
+			content: [{ type: "text", text: `Created ${path}` }],
+			details: {
+				diff: "",
+				op: "create",
+				meta: outputMeta().get(),
+			},
+		};
+	}
+
+	const anchorEdits = resolveEditAnchors(edits);
+	const rawContent = await sourceFile.text();
+	assertEditableFileContent(rawContent, path);
+
+	const { bom, text } = stripBom(rawContent);
+	const originalEnding = detectLineEnding(text);
+	const originalNormalized = normalizeToLF(text);
+	let normalizedText = originalNormalized;
+
+	const anchorResult = applyHashlineEdits(normalizedText, anchorEdits);
+	normalizedText = anchorResult.lines;
+
+	const result = {
+		text: normalizedText,
+		firstChangedLine: anchorResult.firstChangedLine,
+		warnings: anchorResult.warnings,
+		noopEdits: anchorResult.noopEdits,
+	};
+	if (originalNormalized === result.text && !move) {
+		let diagnostic = `No changes made to ${path}. The edits produced identical content.`;
+		if (result.noopEdits && result.noopEdits.length > 0) {
+			const details = result.noopEdits
+				.map(
+					edit =>
+						`Edit ${edit.editIndex}: replacement for ${edit.loc} is identical to current content:\n  ${edit.loc}| ${edit.current}`,
+				)
+				.join("\n");
+			diagnostic += `\n${details}`;
+			if (result.noopEdits.length === 1 && result.noopEdits[0]?.current) {
+				const preview = result.noopEdits[0].current.trimEnd();
+				if (preview.length > 0) {
+					diagnostic += `\nThe file currently contains these lines:\n${preview}\nYour edits were normalized back to the original content (whitespace-only differences are preserved as-is). Ensure your replacement changes actual code, not just formatting.`;
+				}
+			}
+		}
+		throw new Error(diagnostic);
+	}
+
+	const writePath = resolvedMove ?? absolutePath;
+	const finalContent = bom + restoreLineEndings(result.text, originalEnding);
+	const diagnostics = await writethrough(writePath, finalContent, signal, Bun.file(writePath), batchRequest, dst =>
+		dst === writePath ? beginDeferredDiagnosticsForPath(writePath) : undefined,
+	);
+	if (resolvedMove && resolvedMove !== absolutePath) {
+		await sourceFile.unlink();
+		invalidateFsScanAfterRename(absolutePath, resolvedMove);
+	} else {
+		invalidateFsScanAfterWrite(absolutePath);
+	}
+
+	const diffResult = generateDiffString(originalNormalized, result.text);
+	const meta = outputMeta()
+		.diagnostics(diagnostics?.summary ?? "", diagnostics?.messages ?? [])
+		.get();
+
+	const resultText = move ? `Moved ${path} to ${move}` : `Updated ${path}`;
+	const preview = buildCompactHashlineDiffPreview(diffResult.diff);
+	const summaryLine = `Changes: +${preview.addedLines} -${preview.removedLines}${preview.preview ? "" : " (no textual diff preview)"}`;
+	const warningsBlock = result.warnings?.length ? `\n\nWarnings:\n${result.warnings.join("\n")}` : "";
+	const previewBlock = preview.preview ? `\n\nDiff preview:\n${preview.preview}` : "";
+
+	return {
+		content: [
+			{
+				type: "text",
+				text: `${resultText}\n${summaryLine}${previewBlock}${warningsBlock}`,
+			},
+		],
+		details: {
+			diff: diffResult.diff,
+			firstChangedLine: result.firstChangedLine ?? diffResult.firstChangedLine,
+			diagnostics,
+			op: "update",
+			move,
+			meta,
+		},
+	};
+}