pi-readseek 0.4.28 → 0.4.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.4.28",
+  "version": "0.4.30",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.4.32",
+    "@jarkkojs/readseek": "^0.4.34",
     "diff": "^8.0.3",
     "xxhash-wasm": "^1.1.0"
   },

package/src/edit-classify.ts

@@ -1,8 +1,4 @@
 import * as Diff from "diff";
-import { execFile } from "node:child_process";
-import { writeFileSync, mkdtempSync, rmSync } from "node:fs";
-import { resolve } from "node:path";
-import { tmpdir } from "node:os";
 
 export type EditClassification = "no-op" | "whitespace-only" | "semantic" | "mixed";
 
@@ -60,126 +56,3 @@ export function classifyEdit(oldContent: string, newContent: string): EditClassi
   return { classification: "semantic" };
 }
 
-let difftCachedResult: boolean | null = null;
-
-
-export async function isDifftAvailable(): Promise<boolean> {
-  if (difftCachedResult !== null) return difftCachedResult;
-
-  return new Promise<boolean>((resolve) => {
-    execFile("which", ["difft"], (err) => {
-      difftCachedResult = !err;
-      resolve(difftCachedResult);
-    });
-  });
-}
-
-export interface DifftClassifyResult {
-  classification: EditClassification;
-  movedBlocks: number;
-}
-
-function getChunkSideText(side: any): string {
-  if (!side || typeof side !== "object") return "";
-  if (!Array.isArray(side.changes)) return "";
-  return side.changes
-    .map((change: any) => (change && typeof change.content === "string" ? change.content : ""))
-    .join("");
-}
-
-function getChunkOnlySideSignature(chunk: any[]): { side: "lhs" | "rhs"; text: string } | null {
-  let hasLhs = false;
-  let hasRhs = false;
-  let text = "";
-
-  for (const entry of chunk) {
-    if (entry?.lhs) {
-      hasLhs = true;
-      text += getChunkSideText(entry.lhs);
-    }
-    if (entry?.rhs) {
-      hasRhs = true;
-      text += getChunkSideText(entry.rhs);
-    }
-  }
-
-  if (hasLhs === hasRhs) return null;
-  return { side: hasLhs ? "lhs" : "rhs", text };
-}
-
-export function parseDifftJson(json: any): DifftClassifyResult | null {
-  if (!json || typeof json !== "object" || !("status" in json)) return null;
-
-  if (json.status === "unchanged") {
-    return { classification: "whitespace-only", movedBlocks: 0 };
-  }
-
-  if (json.status !== "changed" || !Array.isArray(json.chunks)) {
-    return null;
-  }
-
-  const lhsOnlyChunkTexts: string[] = [];
-  const rhsOnlyChunkTexts: string[] = [];
-  for (const chunk of json.chunks) {
-    if (!Array.isArray(chunk)) continue;
-    const signature = getChunkOnlySideSignature(chunk);
-    if (!signature) continue;
-    if (signature.side === "lhs") lhsOnlyChunkTexts.push(signature.text);
-    if (signature.side === "rhs") rhsOnlyChunkTexts.push(signature.text);
-  }
-
-  const remainingRhs = new Map<string, number>();
-  for (const text of rhsOnlyChunkTexts) {
-    remainingRhs.set(text, (remainingRhs.get(text) ?? 0) + 1);
-  }
-
-  let movedBlocks = 0;
-  for (const text of lhsOnlyChunkTexts) {
-    const count = remainingRhs.get(text) ?? 0;
-    if (count <= 0) continue;
-    movedBlocks++;
-    if (count === 1) remainingRhs.delete(text);
-    else remainingRhs.set(text, count - 1);
-  }
-
-  return { classification: "semantic", movedBlocks };
-}
-
-export async function runDifftastic(
-  oldContent: string,
-  newContent: string,
-  fileExtension: string,
-): Promise<DifftClassifyResult | null> {
-  const available = await isDifftAvailable();
-  if (!available) return null;
-
-  let tempDir: string | null = null;
-  try {
-    tempDir = mkdtempSync(resolve(tmpdir(), "pi-difft-"));
-    const oldPath = resolve(tempDir, `old.${fileExtension}`);
-    const newPath = resolve(tempDir, `new.${fileExtension}`);
-    writeFileSync(oldPath, oldContent, "utf-8");
-    writeFileSync(newPath, newContent, "utf-8");
-
-    const stdout = await new Promise<string>((resolve, reject) => {
-      execFile(
-        "difft",
-        ["--display=json", oldPath, newPath],
-        { env: { ...process.env, DFT_UNSTABLE: "yes" }, timeout: 10_000 },
-        (err, stdout) => {
-          if (err) return reject(err);
-          resolve(stdout);
-        },
-      );
-    });
-
-    const json = JSON.parse(stdout);
-    return parseDifftJson(json);
-  } catch {
-    return null;
-  } finally {
-    if (tempDir) {
-      try { rmSync(tempDir, { recursive: true, force: true }); } catch { /* ignore */ }
-    }
-  }
-}

package/src/edit-output.ts

@@ -76,14 +76,8 @@ function formatWhitespaceOnlyWarning(semanticSummary: SemanticSummary | undefine
   if (!extractNewTextValues(edits).some((text) => /\S/.test(text))) return undefined;
   return "⚠ Edit classified as whitespace-only — if you intended a behavior change, re-read to verify.";
 }
-function formatSemanticSuffix(semanticSummary: SemanticSummary | undefined): string {
-  if (!semanticSummary) return "";
-
-  const movedBlocks = semanticSummary.movedBlocks ?? 0;
-  if (movedBlocks <= 0) return "";
-
-  const blockWord = movedBlocks === 1 ? "block" : "blocks";
-  return ` [semantic: ${semanticSummary.classification}, ${movedBlocks} ${blockWord} moved]`;
+function formatSemanticSuffix(_semanticSummary: SemanticSummary | undefined): string {
+  return "";
 }
 function formatReplaceHint(edits: unknown[] | undefined, noopEdits: unknown[]): string | undefined {
   if ((noopEdits ?? []).length > 0) return undefined;

package/src/edit-syntax-validate.ts

@@ -41,12 +41,13 @@ const EMPTY: ReadSeekCheckOutput = { errorCount: 0, missingCount: 0, diagnostics
  */
 export async function validateSyntaxRegression(
   input: ValidateInput,
+  options: { signal?: AbortSignal } = {},
 ): Promise<ValidateResult | null> {
   let before: ReadSeekCheckOutput;
   let after: ReadSeekCheckOutput;
   try {
-    before = input.before === undefined ? EMPTY : await readseekCheck(input.filePath, input.before);
-    after = await readseekCheck(input.filePath, input.after);
+    before = input.before === undefined ? EMPTY : await readseekCheck(input.filePath, input.before, { signal: options.signal });
+    after = await readseekCheck(input.filePath, input.after, { signal: options.signal });
   } catch {
     return null;
   }

package/src/edit.ts

@@ -14,7 +14,7 @@ import { looksLikeBinary } from "./binary-detect.js";
 import { throwIfAborted } from "./runtime.js";
 import { formatFsError } from "./fs-error.js";
 import { buildEditOutput } from "./edit-output.js";
-import { classifyEdit, isDifftAvailable, runDifftastic } from "./edit-classify.js";
+import { classifyEdit } from "./edit-classify.js";
 import type { SemanticSummary } from "./readseek-value.js";
 import { buildReadSeekError } from "./readseek-value.js";
 import { classifyReadSeekFailure } from "./readseek-client.js";
@@ -454,7 +454,7 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 			filePath: absolutePath,
 			before: originalNormalized,
 			after: result,
-		});
+		}, { signal });
 		if (regression) {
 			const lines = regression.errorLines.join(", ");
 			const message = `syntax-regression: lines ${lines}`;
@@ -516,23 +516,9 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 	if (syntaxWarning) warnings.push(syntaxWarning);
 	// Semantic classification
 	const internalClassification = classifyEdit(originalNormalized, result);
-	const difftAvailable = await isDifftAvailable();
-	let semanticSummary: SemanticSummary = {
+	const semanticSummary: SemanticSummary = {
 		classification: internalClassification.classification,
-		difftasticAvailable: difftAvailable,
 	};
-
-	if (difftAvailable) {
-		const ext = path.split(".").pop() ?? "txt";
-		const difftResult = await runDifftastic(originalNormalized, result, ext);
-		if (difftResult) {
-			semanticSummary = {
-				classification: difftResult.classification,
-				difftasticAvailable: true,
-				...(difftResult.movedBlocks > 0 ? { movedBlocks: difftResult.movedBlocks } : {}),
-			};
-		}
-	}
 	const builtOutput = buildEditOutput({
 		path: absolutePath,
 		displayPath: path,

package/src/read.ts

@@ -74,8 +74,8 @@ function hasReadAnchors(result: AgentToolResult<any>): boolean {
 function formatImageAnalysis(detection: ReadSeekDetection): string | undefined {
 	if (detection.kind !== "image") return undefined;
 	const sections: string[] = [];
-	const transcript = detection.transcribe?.text?.trim();
-	if (transcript) sections.push(`Transcribed text from image:\n${transcript}`);
+	const ocr = detection.ocr?.trim();
+	if (ocr) sections.push(`OCR text from image:\n${ocr}`);
 	const caption = detection.caption?.trim();
 	if (caption) sections.push(`Image caption:\n${caption}`);
 	if (detection.objects?.length) {
@@ -178,13 +178,13 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 			const builtinRead = createReadTool(cwd);
 			const builtinResult = await builtinRead.execute(toolCallId, p, signal, onUpdate);
 			const ocrMode = resolveReadSeekOcrMode();
-			const shouldTranscribe = ocrMode === "on" || (ocrMode === "auto" && !opts.modelSupportsImages);
-			if (!shouldTranscribe) return succeed(builtinResult);
+			const shouldRunVision = ocrMode === "on" || (ocrMode === "auto" && !opts.modelSupportsImages);
+			if (!shouldRunVision) return succeed(builtinResult);
 
 			let ocrFailed = false;
 			try {
 				const ocrDetection = await readseekDetect(absolutePath, {
-					transcribe: true,
+					ocr: true,
 					caption: true,
 					objects: true,
 					signal,
@@ -359,8 +359,8 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 	let readseekOutput: Awaited<ReturnType<typeof readseekRead>>;
 	try {
 		readseekOutput = total === 0
-			? await readseekRead(absolutePath)
-			: await readseekRead(absolutePath, startLine, endIdx);
+			? await readseekRead(absolutePath, undefined, undefined, { signal })
+			: await readseekRead(absolutePath, startLine, endIdx, { signal });
 	} catch (err: any) {
 		const detail = err?.message ? ` — ${err.message}` : "";
 		const message = `readseek failed while reading ${rawPath}${detail}`;

package/src/readseek-client.ts

@@ -108,15 +108,7 @@ export interface ReadSeekCheckOutput {
 	diagnostics: ReadSeekDiagnostic[];
 }
 
-export interface ReadSeekTranscriptRegion {
-	text: string;
-	quad: [number, number, number, number, number, number, number, number];
-}
-
-export interface ReadSeekTranscript {
-	text: string;
-	regions: ReadSeekTranscriptRegion[];
-}
+export type ReadSeekOcrText = string;
 
 export interface ReadSeekDetectedObject {
 	label: string;
@@ -143,7 +135,7 @@ export type ReadSeekDetection =
 			width: number;
 			height: number;
 			animated: boolean;
-			transcribe?: ReadSeekTranscript;
+			ocr?: ReadSeekOcrText;
 			caption?: string;
 			objects?: ReadSeekDetectedObject[];
 		}
@@ -163,7 +155,7 @@ interface ReadSeekSearchOptions {
 }
 
 interface ReadSeekDetectOptions {
-	transcribe?: boolean;
+	ocr?: boolean;
 	caption?: boolean;
 	objects?: boolean;
 	signal?: AbortSignal;
@@ -556,11 +548,16 @@ function parseSearchOutput(value: unknown): ReadSeekSearchOutput {
 	};
 }
 
-export async function readseekRead(filePath: string, startLine?: number, endLine?: number): Promise<ReadSeekReadOutput> {
+export async function readseekRead(
+	filePath: string,
+	startLine?: number,
+	endLine?: number,
+	options: { signal?: AbortSignal } = {},
+): Promise<ReadSeekReadOutput> {
 	const args = ["read", filePath];
 	if (startLine !== undefined) args.push("--start", String(startLine));
 	if (endLine !== undefined) args.push("--end", String(endLine));
-	return parseReadOutput(await runReadSeek(args));
+	return parseReadOutput(await runReadSeek(args, { signal: options.signal }));
 }
 
 function fileMapFromReadSeekOutput(output: ReadSeekMapOutput, filePath: string, totalBytes: number): FileMap | null {
@@ -688,24 +685,8 @@ export async function readseekCheck(
 	);
 }
 
-function parseTranscript(value: unknown): ReadSeekTranscript | undefined {
-	if (value === undefined || value === null) return undefined;
-	if (typeof value !== "object") throw new Error("invalid readseek detect transcribe");
-	const transcribe = value as Record<string, unknown>;
-	if (!Array.isArray(transcribe.regions)) throw new Error("invalid readseek detect transcribe.regions");
-	return {
-		text: requireString(transcribe.text, "transcribe.text"),
-		regions: transcribe.regions.map((region) => {
-			if (!region || typeof region !== "object") throw new Error("invalid readseek detect transcribe region");
-			const item = region as Record<string, unknown>;
-			const quad = item.quad;
-			if (!Array.isArray(quad) || quad.length !== 8) throw new Error("invalid readseek detect transcribe quad");
-			return {
-				text: requireString(item.text, "transcribe.region.text"),
-				quad: quad.map((n, i) => requireNumber(n, `transcribe.region.quad[${i}]`)) as ReadSeekTranscriptRegion["quad"],
-			};
-		}),
-	};
+function parseOcrText(value: unknown): ReadSeekOcrText | undefined {
+	return optionalString(value, "ocr");
 }
 
 function parseDetectedObjects(value: unknown): ReadSeekDetectedObject[] | undefined {
@@ -745,7 +726,7 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 			width: requireNumber(output.width, "width"),
 			height: requireNumber(output.height, "height"),
 			animated: requireBoolean(output.animated, "animated"),
-			transcribe: parseTranscript(output.transcribe),
+			ocr: parseOcrText(output.ocr),
 			caption: optionalString(output.caption, "caption"),
 			objects: parseDetectedObjects(output.objects),
 		};
@@ -770,7 +751,7 @@ export async function readseekDetect(
 	options: ReadSeekDetectOptions = {},
 ): Promise<ReadSeekDetection> {
 	const args = ["detect"];
-	if (options.transcribe) args.push("--transcribe");
+	if (options.ocr) args.push("--ocr");
 	if (options.caption) args.push("--caption");
 	if (options.objects) args.push("--objects");
 	args.push(filePath);
@@ -831,9 +812,44 @@ interface RenameOptions {
 	signal?: AbortSignal;
 }
 
+function parseRenameConflicts(value: unknown, field: string): RenameConflict[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) throw new Error(`invalid readseek ${field}`);
+	return value.map((item) => {
+		if (!item || typeof item !== "object") throw new Error(`invalid readseek ${field} entry`);
+		const c = item as Record<string, unknown>;
+		return {
+			line: requireNumber(c.line, `${field}.line`),
+			column: requireNumber(c.column, `${field}.column`),
+			reason: requireString(c.reason, `${field}.reason`),
+		};
+	});
+}
+
+function parseRenameEdits(value: unknown, field: string): RenameEdit[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) throw new Error(`invalid readseek ${field}`);
+	return value.map((item) => {
+		if (!item || typeof item !== "object") throw new Error(`invalid readseek ${field} entry`);
+		const e = item as Record<string, unknown>;
+		return {
+			line: requireNumber(e.line, `${field}.line`),
+			start_column: requireNumber(e.start_column, `${field}.start_column`),
+			end_column: requireNumber(e.end_column, `${field}.end_column`),
+			start_byte: requireNumber(e.start_byte, `${field}.start_byte`),
+			end_byte: requireNumber(e.end_byte, `${field}.end_byte`),
+			occurrence: requireString(e.occurrence, `${field}.occurrence`),
+			line_hash: requireString(e.line_hash, `${field}.line_hash`),
+			text: requireString(e.text, `${field}.text`),
+		};
+	});
+}
+
 function parseRenameOutput(value: unknown): RenameOutput {
 	if (!value || typeof value !== "object") throw new Error("invalid readseek rename output");
 	const output = value as Record<string, unknown>;
+	const others = output.others;
+	if (others !== undefined && !Array.isArray(others)) throw new Error("invalid readseek others");
 	return {
 		file: requireString(output.file, "file"),
 		language: requireString(output.language, "language"),
@@ -842,42 +858,20 @@ function parseRenameOutput(value: unknown): RenameOutput {
 		old_name: requireString(output.old_name, "old_name"),
 		new_name: requireString(output.new_name, "new_name"),
 		applied: requireBoolean(output.applied, "applied"),
-		conflicts: (output.conflicts as any[] | undefined)?.map((c: Record<string, unknown>) => ({
-			line: requireNumber(c.line, "conflict.line"),
-			column: requireNumber(c.column, "conflict.column"),
-			reason: requireString(c.reason, "conflict.reason"),
-		})) ?? [],
-		edits: (output.edits as any[] | undefined)?.map((e: Record<string, unknown>) => ({
-			line: requireNumber(e.line, "edit.line"),
-			start_column: requireNumber(e.start_column, "edit.start_column"),
-			end_column: requireNumber(e.end_column, "edit.end_column"),
-			start_byte: requireNumber(e.start_byte, "edit.start_byte"),
-			end_byte: requireNumber(e.end_byte, "edit.end_byte"),
-			occurrence: requireString(e.occurrence, "edit.occurrence"),
-			line_hash: requireString(e.line_hash, "edit.line_hash"),
-			text: requireString(e.text, "edit.text"),
-		})) ?? [],
-		others: (output.others as any[] | undefined)?.map((o: Record<string, unknown>) => ({
-			file: requireString(o.file, "other.file"),
-			language: requireString(o.language, "other.language"),
-			engine: optionalString(o.engine, "other.engine"),
-			file_hash: requireString(o.file_hash, "other.file_hash"),
-			conflicts: (o.conflicts as any[] | undefined)?.map((c: Record<string, unknown>) => ({
-				line: requireNumber(c.line, "conflict.line"),
-				column: requireNumber(c.column, "conflict.column"),
-				reason: requireString(c.reason, "conflict.reason"),
-			})) ?? [],
-			edits: (o.edits as any[] | undefined)?.map((e: Record<string, unknown>) => ({
-				line: requireNumber(e.line, "edit.line"),
-				start_column: requireNumber(e.start_column, "edit.start_column"),
-				end_column: requireNumber(e.end_column, "edit.end_column"),
-				start_byte: requireNumber(e.start_byte, "edit.start_byte"),
-				end_byte: requireNumber(e.end_byte, "edit.end_byte"),
-				occurrence: requireString(e.occurrence, "edit.occurrence"),
-				line_hash: requireString(e.line_hash, "edit.line_hash"),
-				text: requireString(e.text, "edit.text"),
-			})) ?? [],
-		})) ?? [],
+		conflicts: parseRenameConflicts(output.conflicts, "conflicts"),
+		edits: parseRenameEdits(output.edits, "edits"),
+		others: (others as unknown[] | undefined)?.map((entry) => {
+			if (!entry || typeof entry !== "object") throw new Error("invalid readseek other");
+			const o = entry as Record<string, unknown>;
+			return {
+				file: requireString(o.file, "other.file"),
+				language: requireString(o.language, "other.language"),
+				engine: optionalString(o.engine, "other.engine"),
+				file_hash: requireString(o.file_hash, "other.file_hash"),
+				conflicts: parseRenameConflicts(o.conflicts, "other.conflicts"),
+				edits: parseRenameEdits(o.edits, "other.edits"),
+			};
+		}) ?? [],
 	};
 }
 

package/src/readseek-value.ts

@@ -39,8 +39,6 @@ export interface ReadSeekRange {
 
 export interface SemanticSummary {
   classification: "no-op" | "whitespace-only" | "semantic" | "mixed";
-  difftasticAvailable: boolean;
-  movedBlocks?: number;
 }
 export interface ReadSeekEditResult {
   tool: "edit";

package/src/write.ts

@@ -1,13 +1,13 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, relative } from "node:path";
 
-import { withFileMutationQueue, type ExtensionAPI, type ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue, truncateHead, type ExtensionAPI, type ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 
 import { resolveToCwd } from "./path-utils.js";
 import { ensureHashInit, formatHashlineDisplay } from "./hashline.js";
-import { buildReadSeekError, buildReadSeekLine, buildReadSeekWarning, buildToolErrorResult, type ReadSeekLine, type ReadSeekWarning } from "./readseek-value.js";
+import { buildReadSeekLine, buildReadSeekWarning, buildToolErrorResult, type ReadSeekLine, type ReadSeekWarning, type ToolErrorResult } from "./readseek-value.js";
 import { looksLikeBinary } from "./binary-detect.js";
 import { formatFsError } from "./fs-error.js";
 import { getOrGenerateMap } from "./file-map.js";
@@ -66,8 +66,6 @@ function pendingWritePreviewParts(summary: string, preview: PendingDiffPreviewRe
   return { lines: [summary, headerLine], diffData: expanded ? diffData : undefined };
 }
 
-const MAX_LINES = 2000;
-const MAX_BYTES = 50 * 1024;
 const WRITE_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/write.md", import.meta.url),
   promptSnippet: "Create or overwrite a complete file and return edit anchors",
@@ -93,6 +91,13 @@ export interface WriteResult extends WriteDiffFields {
   };
 }
 
+
+type ExecuteWriteResult = WriteResult | ToolErrorResult;
+
+function isToolErrorResult(result: ExecuteWriteResult): result is ToolErrorResult {
+  return "isError" in result;
+}
+
 async function readPreviousTextForDiff(filePath: string): Promise<string> {
   try {
     const previous = await readFile(filePath);
@@ -133,7 +138,7 @@ export async function executeWrite(opts: {
   content: string;
   map?: boolean;
   cwd?: string;
-}): Promise<WriteResult> {
+}): Promise<ExecuteWriteResult> {
   await ensureHashInit();
 
   const { path: filePath, content, map: requestMap, cwd } = opts;
@@ -144,30 +149,19 @@ export async function executeWrite(opts: {
     const message = "File content contains bare CR (\\r) line endings; write refuses to emit anchors that read/edit would normalize differently.";
     warnings.push(message);
     readseekWarnings.push(buildReadSeekWarning("bare-cr", message));
-    return {
-      text: `Cannot write ${filePath}\n⚠️ ${message}`,
-      warnings,
-      readseekValue: {
-        tool: "write",
-        path: filePath,
-        lines: [],
-        warnings: readseekWarnings,
-      },
-    };
+    return buildToolErrorResult("write", "bare-cr", `Cannot write ${filePath}\n⚠️ ${message}`, {
+      path: filePath,
+      extra: { lines: [], warnings: readseekWarnings },
+    });
   }
   if (looksLikeBinary(Buffer.from(content, "utf-8"))) {
-    warnings.push("File content appears to be binary.");
-    readseekWarnings.push(buildReadSeekWarning("binary-content", "File content appears to be binary."));
-    return {
-      text: `Cannot write ${filePath}\n⚠️ File content appears to be binary — refusing to write.`,
-      warnings,
-      readseekValue: {
-        tool: "write",
-        path: filePath,
-        lines: [],
-        warnings: readseekWarnings,
-      },
-    };
+    const message = "File content appears to be binary.";
+    warnings.push(message);
+    readseekWarnings.push(buildReadSeekWarning("binary-content", message));
+    return buildToolErrorResult("write", "binary-content", `Cannot write ${filePath}\n⚠️ ${message} — refusing to write.`, {
+      path: filePath,
+      extra: { lines: [], warnings: readseekWarnings },
+    });
   }
 
   const previousContent = await readPreviousTextForDiff(filePath);
@@ -189,15 +183,15 @@ export async function executeWrite(opts: {
     displayLines.push(formatHashlineDisplay(lineNum, rawLines[i]));
   }
 
-  let text = displayLines.join("\n");
-  if (rawLines.length > MAX_LINES) {
-    text = displayLines.slice(0, MAX_LINES).join("\n");
-    text += `\n[… ${rawLines.length - MAX_LINES} more lines not shown — full anchors in readseekValue]`;
-  }
-  const bytes = Buffer.byteLength(text, "utf8");
-  if (bytes > MAX_BYTES) {
-    text = Buffer.from(text, "utf8").subarray(0, MAX_BYTES).toString("utf8");
-    text += "\n[… output truncated at 50 KB — full anchors in readseekValue]";
+  const fullText = displayLines.join("\n");
+  const truncated = truncateHead(fullText);
+  let text = truncated.content;
+  if (truncated.truncated) {
+    if (truncated.truncatedBy === "lines") {
+      text += `\n[… ${truncated.totalLines - truncated.outputLines} more lines not shown — full anchors in readseekValue]`;
+    } else {
+      text += "\n[… output truncated at 50 KB — full anchors in readseekValue]";
+    }
   }
 
   // Optional structural map
@@ -267,7 +261,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       const absolutePath = resolveToCwd(params.path, cwd);
       try {
         return await withFileMutationQueue(absolutePath, async () => {
-          let result: WriteResult;
+          let result: ExecuteWriteResult;
           try {
             result = await executeWrite({
               path: absolutePath,
@@ -279,32 +273,12 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
             return buildWriteFsErrorResult(err, absolutePath);
           }
 
+          if (isToolErrorResult(result)) return result;
+
           if (result.readseekValue.lines.length > 0) {
             options.onFileAnchored?.(absolutePath);
           }
 
-          // Lift binary-content signal into a fatal readseekValue.error envelope so
-          // downstream consumers get the same taxonomy shape as every other tool.
-          // The existing ReadSeekWarning entry is preserved on readseekValue.warnings for
-          // backward compatibility.
-          for (const code of ["binary-content", "bare-cr"] as const) {
-            const warning = result.readseekValue.warnings.find((w) => w.code === code);
-            if (warning) {
-              return {
-                content: [{ type: "text" as const, text: result.text }],
-                isError: true,
-                details: {
-                  readseekValue: {
-                    ...result.readseekValue,
-                    ok: false,
-                    error: buildReadSeekError(code, warning.message),
-                  },
-                  warnings: result.warnings,
-                },
-              };
-            }
-          }
-
           return {
             content: [{ type: "text" as const, text: result.text }],
             details: {