pi-readseek 0.4.26 → 0.4.28

package/README.md

@@ -24,8 +24,9 @@ npm install --save-dev @jarkkojs/readseek
 ## Tools
 
 - **read** — reads text files with `LINE:HASH` anchors for later `edit` calls;
-  images are returned as attachments. Supports `symbol`, `map`, and `bundle`
-  options powered by `@jarkkojs/readseek`.
+  images are returned as attachments and may include local OCR, caption, and
+  object text. Supports `symbol`, `map`, and `bundle` options powered by
+  `@jarkkojs/readseek`.
 - **edit** — changes existing text files using fresh anchors from `read`,
   `grep`, `search`, or `write`. Variants: `set_line`, `replace_lines`,
   `insert_after`, `replace_symbol`, `replace`. Set `new_text` to `""` to
@@ -40,6 +41,38 @@ npm install --save-dev @jarkkojs/readseek
 - **write** — creates or overwrites whole files and returns anchors for
   immediate follow-up edits.
 
+## Settings
+
+`pi-readseek` reads optional JSON settings from:
+
+| Location | Scope |
+| --- | --- |
+| `~/.pi/agent/readseek/settings.json` | Global |
+| `.pi/readseek/settings.json` | Project |
+
+Project settings override global settings. Image OCR behavior is controlled by
+`read.ocrMode`:
+
+```json
+{
+  "read": {
+    "ocrMode": "on"
+  }
+}
+```
+
+Modes:
+
+- `"on"` — always run local image OCR/caption/object analysis. This is the
+  default.
+- `"off"` — return only the image attachment. Use this as a workaround if the
+  local readseek image-analysis path crashes.
+- `"auto"` — run local image analysis only when the active model does not
+  support native image input.
+
+`READSEEK_READ_OCR_MODE=on|off|auto` overrides the JSON setting for one
+process.
+
 ## Related
 
 - [readseek.vim](https://github.com/jarkkojs/readseek.vim) — Vim 9 plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {

package/prompts/read.md

@@ -1,4 +1,4 @@
-Read files through readseek. Text output uses `LINE:HASH|content` anchors that can be copied directly into `edit`; supported images return attachments instead of anchors. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
+Read files through readseek. Text output uses `LINE:HASH|content` anchors that can be copied directly into `edit`; supported images return attachments and may append OCR/caption/object text depending on `read.ocrMode`. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
 
 ## Choose the right read
 

package/src/edit.ts

@@ -12,7 +12,7 @@ import { HashlineMismatchError, applyHashlineEdits, computeLineHash, ensureHashI
 import { resolveToCwd } from "./path-utils.js";
 import { looksLikeBinary } from "./binary-detect.js";
 import { throwIfAborted } from "./runtime.js";
-import { classifyFsError } from "./fs-error.js";
+import { formatFsError } from "./fs-error.js";
 import { buildEditOutput } from "./edit-output.js";
 import { classifyEdit, isDifftAvailable, runDifftastic } from "./edit-classify.js";
 import type { SemanticSummary } from "./readseek-value.js";
@@ -104,19 +104,9 @@ function buildEditError(
 	};
 }
 
-function mapEditFileError(err: any, filePath: string, displayPath: string, phase: "read" | "write"): ReturnType<typeof buildEditError> {
-	const code = err?.code;
-	if (code === "ENOENT" && phase === "write") {
-		return buildEditError(filePath, "file-not-found", `Failed to write file: ${displayPath}`);
-	}
-	const fsError = classifyFsError(err, displayPath);
-	if (fsError) {
-		return buildEditError(filePath, fsError.code, fsError.message, fsError.hint);
-	}
-	const prefix = phase === "write" ? "Failed to write file" : "File not readable";
-	const message = `${prefix}: ${displayPath}${err?.message ? ` — ${err.message}` : ""}`;
-	return buildEditError(filePath, "fs-error", message, undefined,
-		{ fsCode: code, fsMessage: err?.message });
+function mapEditFileError(err: any, filePath: string, _displayPath: string, _phase: "read" | "write"): ReturnType<typeof buildEditError> {
+	const { code, message } = formatFsError(err, "edit-error");
+	return buildEditError(filePath, code, message);
 }
 
 export interface EditToolOptions {

package/src/fs-error.ts

@@ -1,30 +1,33 @@
-export type FsErrorCode = "path-is-directory" | "permission-denied" | "file-not-found";
+const SYSLOG_PATH_SUFFIX = /,\s+[a-z]+(\s+'.*')?$/;
 
-export interface FsErrorInfo {
-  code: FsErrorCode;
-  message: string;
-  hint?: string;
+/**
+ * Derive the canonical OS strerror from a Node {@link err.message} by
+ * stripping the trailing syscall and optional path suffix so the result
+ * is portable and never duplicates information already carried in the
+ * error-envelope `path` field.
+ */
+function strerror(err: { message?: unknown }): string {
+	const raw = String(err?.message ?? String(err));
+	return raw.replace(SYSLOG_PATH_SUFFIX, "");
 }
 
 /**
- * Translate a Node `fs` errno into the shared readseek error taxonomy with a
- * canonical message. Returns null for errno values without a dedicated code so
- * callers fall back to their own `fs-error` handling.
+ * Build a readseek error from a Node `fs` errno exception.
+ *
+ * Every errno maps to its own canonical code automatically — no
+ * hand-curated switch, no `"fs-error"` catch-all.
+ *
+ * @param err  The caught exception (carries `err.code` and `err.message`).
+ * @param domain  Tool-level prefix for the message: `"read-error"`,
+ *                `"edit-error"`, `"write-error"`, `"stat-error"`.
  */
-export function classifyFsError(err: { code?: unknown }, path: string): FsErrorInfo | null {
-  switch (err?.code) {
-    case "EISDIR":
-      return {
-        code: "path-is-directory",
-        message: `Path is a directory: ${path}`,
-        hint: `Use ls(${JSON.stringify(path)}) to inspect directories.`,
-      };
-    case "EACCES":
-    case "EPERM":
-      return { code: "permission-denied", message: `Permission denied: ${path}` };
-    case "ENOENT":
-      return { code: "file-not-found", message: `File not found: ${path}` };
-    default:
-      return null;
-  }
+export function formatFsError(
+	err: { code?: unknown; message?: string },
+	domain: string,
+): { code: string; message: string } {
+	const errno = typeof err.code === "string" ? err.code : "EIO";
+	return {
+		code: errno,
+		message: `${domain}: ${errno}: ${strerror(err)}`,
+	};
 }

package/src/hover.ts

@@ -7,6 +7,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildToolErrorResult } from "./readseek-value.js";
 import { resolveToCwd } from "./path-utils.js";
+import { formatFsError } from "./fs-error.js";
 import { classifyReadSeekFailure, readseekIdentify } from "./readseek-client.js";
 import { filePathParam, registerReadSeekTool } from "./register-tool.js";
 
@@ -48,8 +49,9 @@ export async function executeHover(opts: ExecuteHoverOptions): Promise<any> {
 	let content: string;
 	try {
 		content = await readFile(filePath, "utf-8");
-	} catch {
-		return buildToolErrorResult("hover", "file-not-found", `hover could not read ${p.path}`);
+	} catch (err: any) {
+		const { code, message } = formatFsError(err, "hover-error");
+		return buildToolErrorResult("hover", code, message, { path: p.path });
 	}
 
 	try {

package/src/read.ts

@@ -17,7 +17,7 @@ import { buildReadSeekWarning, buildToolErrorResult, renderReadSeekLines, type R
 import { looksLikeBinary } from "./binary-detect.js";
 import { resolveToCwd } from "./path-utils.js";
 import { throwIfAborted } from "./runtime.js";
-import { classifyFsError } from "./fs-error.js";
+import { formatFsError } from "./fs-error.js";
 import { getOrGenerateMap } from "./file-map.js";
 import { formatFileMapWithBudget } from "./readseek/formatter.js";
 import { findSymbol, type SymbolMatch } from "./readseek/symbol-lookup.js";
@@ -28,7 +28,8 @@ import { buildLocalBundle } from "./read-local-bundle.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { readseekRead, readseekDetect, type ReadSeekDetection } from "./readseek-client.js";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
+import { resolveReadSeekOcrMode } from "./readseek-settings.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidthCached } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
 import { filePathParam, mapParam, optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
 
@@ -57,6 +58,8 @@ export interface ExecuteReadOptions {
 	onUpdate: any;
 	cwd: string;
 	onSuccessfulRead?: FileAnchoredCallback;
+	/** Whether the active model accepts image input natively. Used when OCR mode is auto. */
+	modelSupportsImages?: boolean;
 }
 
 function hasReadAnchors(result: AgentToolResult<any>): boolean {
@@ -68,6 +71,20 @@ function hasReadAnchors(result: AgentToolResult<any>): boolean {
 	return Array.isArray(lines) && lines.length > 0;
 }
 
+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 caption = detection.caption?.trim();
+	if (caption) sections.push(`Image caption:\n${caption}`);
+	if (detection.objects?.length) {
+		const lines = detection.objects.map((object) => `- ${object.label} [${object.bbox.join(", ")}]`);
+		sections.push(`Detected objects:\n${lines.join("\n")}`);
+	}
+	return sections.length > 0 ? sections.join("\n\n") : undefined;
+}
+
 export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolResult<any>> {
 	const { toolCallId, params, signal, onUpdate, cwd, onSuccessfulRead } = opts;
 	await ensureHashInit();
@@ -144,37 +161,53 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 	try {
 		rawBuffer = await fsReadFile(absolutePath);
 	} catch (err: any) {
-		const code = err?.code;
-		const fsError = classifyFsError(err, rawPath);
-		if (fsError) {
-			return buildToolErrorResult("read", fsError.code, fsError.message, {
-				path: rawParams.path,
-				...(fsError.hint ? { hint: fsError.hint } : {}),
-			});
-		}
-		const message = `File not readable: ${rawPath}${err?.message ? ` — ${err.message}` : ""}`;
-		return buildToolErrorResult("read", "fs-error", message, { path: rawParams.path, details: { fsCode: code, fsMessage: err?.message } });
+		const { code, message } = formatFsError(err, "read-error");
+		return buildToolErrorResult("read", code, message, {
+			path: rawParams.path,
+		});
 	}
 
 	const hasBinaryContent = looksLikeBinary(rawBuffer);
 	if (hasBinaryContent) {
-		// Images are always binary; classify and transcribe in a single readseek detect call.
 		let detection: ReadSeekDetection | undefined;
 		try {
-			detection = await readseekDetect(absolutePath, { transcribe: true, signal });
+			detection = await readseekDetect(absolutePath, { signal });
 		} catch {
-			// detect unavailable — fall through to binary-as-text handling below
 		}
 		if (detection?.kind === "image") {
 			const builtinRead = createReadTool(cwd);
 			const builtinResult = await builtinRead.execute(toolCallId, p, signal, onUpdate);
-			const transcript = detection.transcribe?.text?.trim();
-			if (transcript) {
+			const ocrMode = resolveReadSeekOcrMode();
+			const shouldTranscribe = ocrMode === "on" || (ocrMode === "auto" && !opts.modelSupportsImages);
+			if (!shouldTranscribe) return succeed(builtinResult);
+
+			let ocrFailed = false;
+			try {
+				const ocrDetection = await readseekDetect(absolutePath, {
+					transcribe: true,
+					caption: true,
+					objects: true,
+					signal,
+				});
+				const imageAnalysis = formatImageAnalysis(ocrDetection);
+				if (imageAnalysis) {
+					return succeed({
+						...builtinResult,
+						content: [
+							...(builtinResult.content ?? []),
+							{ type: "text" as const, text: imageAnalysis },
+						],
+					});
+				}
+			} catch {
+				ocrFailed = true;
+			}
+			if (ocrFailed) {
 				return succeed({
 					...builtinResult,
 					content: [
 						...(builtinResult.content ?? []),
-						{ type: "text" as const, text: `Transcribed text from image:\n${transcript}` },
+						{ type: "text" as const, text: "[Warning: local image analysis (OCR) unavailable — showing image attachment only]" },
 					],
 				});
 			}
@@ -465,6 +498,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				onUpdate,
 				cwd: ctx.cwd,
 				onSuccessfulRead: options.onSuccessfulRead,
+				modelSupportsImages: ctx.model?.input.includes("image") ?? false,
 			});
 		},
 		renderCall(args: any, theme: any, ...rest: any[]) {
@@ -509,7 +543,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			for (const badge of info.badges) summaryParts.push(badge);
 			const summary = summaryParts.join(" • ");
 			let text = summaryLine(summary, { hidden: !!textContent && !expanded });
-			if (expanded && textContent) text += "\n" + wrapReadHashlinesForWidth(textContent, width);
+			if (expanded && textContent) text += "\n" + wrapReadHashlinesForWidthCached(content, textContent, width);
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
 	});

package/src/readseek-client.ts

@@ -118,6 +118,11 @@ export interface ReadSeekTranscript {
 	regions: ReadSeekTranscriptRegion[];
 }
 
+export interface ReadSeekDetectedObject {
+	label: string;
+	bbox: [number, number, number, number];
+}
+
 export type ReadSeekDetection =
 	| {
 			kind: "source";
@@ -139,6 +144,8 @@ export type ReadSeekDetection =
 			height: number;
 			animated: boolean;
 			transcribe?: ReadSeekTranscript;
+			caption?: string;
+			objects?: ReadSeekDetectedObject[];
 		}
 	| {
 			kind: "text";
@@ -155,6 +162,13 @@ interface ReadSeekSearchOptions {
 	signal?: AbortSignal;
 }
 
+interface ReadSeekDetectOptions {
+	transcribe?: boolean;
+	caption?: boolean;
+	objects?: boolean;
+	signal?: AbortSignal;
+}
+
 function normalizeLanguage(language: string): string {
 	return language === "java" ? "Java" : language;
 }
@@ -272,23 +286,36 @@ function directoryExists(dirPath: string): boolean {
 	}
 }
 
+const ownRepositoryByDir = new Map<string, boolean>();
+
 function isOwnReadSeekRepository(cwd = process.cwd()): boolean {
-	let dir = path.resolve(cwd);
+	const start = path.resolve(cwd);
+	const cached = ownRepositoryByDir.get(start);
+	if (cached !== undefined) return cached;
+
+	let dir = start;
+	let result = false;
 	while (true) {
 		const packageJsonPath = path.join(dir, "package.json");
 		if (existsSync(packageJsonPath)) {
 			try {
 				const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { name?: unknown };
-				if (typeof packageJson.name === "string" && READSEEK_REPO_PACKAGE_NAMES.has(packageJson.name)) return true;
+				if (typeof packageJson.name === "string" && READSEEK_REPO_PACKAGE_NAMES.has(packageJson.name)) {
+					result = true;
+					break;
+				}
 			} catch {
 				// Ignore unreadable or invalid package manifests while walking up.
 			}
 		}
 
 		const parent = path.dirname(dir);
-		if (parent === dir) return false;
+		if (parent === dir) break;
 		dir = parent;
 	}
+
+	ownRepositoryByDir.set(start, result);
+	return result;
 }
 
 function defaultReadSeekDir(): string | null {
@@ -296,23 +323,43 @@ function defaultReadSeekDir(): string | null {
 	return home ? path.join(home, ".pi", "readseek") : null;
 }
 
+const DEFAULT_READSEEK_TIMEOUT_MS = 120_000;
+
+function readseekTimeoutMs(): number {
+	const raw = process.env.READSEEK_TIMEOUT_MS;
+	if (raw !== undefined && raw !== "") {
+		const parsed = Number(raw);
+		if (Number.isFinite(parsed) && parsed > 0) return parsed;
+	}
+	return DEFAULT_READSEEK_TIMEOUT_MS;
+}
+
 async function spawnReadSeekRaw(args: string[], options: RunReadSeekOptions = {}): Promise<string> {
 	return new Promise<string>((resolve, reject) => {
 		let settled = false;
+		let timeout: ReturnType<typeof setTimeout> | undefined;
 		const fail = (error: Error): void => {
 			if (settled) return;
 			settled = true;
+			if (timeout !== undefined) clearTimeout(timeout);
 			reject(error);
 		};
 		const succeed = (value: string): void => {
 			if (settled) return;
 			settled = true;
+			if (timeout !== undefined) clearTimeout(timeout);
 			resolve(value);
 		};
 
 		const stdin = options.stdin;
 		const stdio: StdioOptions = [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"];
 		const child = spawn(readseekBinaryPath(), args, { stdio, signal: options.signal });
+		const timeoutMs = options.timeoutMs ?? readseekTimeoutMs();
+		timeout = setTimeout(() => {
+			child.kill("SIGKILL");
+			fail(new Error(`readseek timed out after ${timeoutMs} ms`));
+		}, timeoutMs);
+		timeout.unref?.();
 		const childStdout = child.stdout;
 		const childStderr = child.stderr;
 		const childStdin = child.stdin;
@@ -348,10 +395,11 @@ async function spawnReadSeekRaw(args: string[], options: RunReadSeekOptions = {}
 			});
 			childStdin.end(stdin, "utf-8");
 		}
-		child.on("close", (code) => {
+		child.on("close", (code, signal) => {
 			const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
 			const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
 			if (code === 0) succeed(stdout);
+			else if (signal) fail(new Error((stderr || `readseek killed by signal ${signal}`).replace(/^error:\s*/i, "")));
 			else fail(new Error((stderr || `readseek exited with status ${code}`).replace(/^error:\s*/i, "")));
 		});
 	});
@@ -381,6 +429,7 @@ async function readseekInvocationArgs(args: string[]): Promise<string[]> {
 interface RunReadSeekOptions {
 	signal?: AbortSignal;
 	stdin?: string;
+	timeoutMs?: number;
 }
 
 async function runReadSeekRaw(args: string[], options: RunReadSeekOptions = {}): Promise<string> {
@@ -659,6 +708,21 @@ function parseTranscript(value: unknown): ReadSeekTranscript | undefined {
 	};
 }
 
+function parseDetectedObjects(value: unknown): ReadSeekDetectedObject[] | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (!Array.isArray(value)) throw new Error("invalid readseek detect objects");
+	return value.map((object) => {
+		if (!object || typeof object !== "object") throw new Error("invalid readseek detect object");
+		const item = object as Record<string, unknown>;
+		const bbox = item.bbox;
+		if (!Array.isArray(bbox) || bbox.length !== 4) throw new Error("invalid readseek detect object.bbox");
+		return {
+			label: requireString(item.label, "object.label"),
+			bbox: bbox.map((n, i) => requireNumber(n, `object.bbox[${i}]`)) as ReadSeekDetectedObject["bbox"],
+		};
+	});
+}
+
 function parseDetectOutput(value: unknown): ReadSeekDetection {
 	if (!value || typeof value !== "object") throw new Error("invalid readseek detect output");
 	const output = value as Record<string, unknown>;
@@ -682,6 +746,8 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 			height: requireNumber(output.height, "height"),
 			animated: requireBoolean(output.animated, "animated"),
 			transcribe: parseTranscript(output.transcribe),
+			caption: optionalString(output.caption, "caption"),
+			objects: parseDetectedObjects(output.objects),
 		};
 	}
 	if (output.language !== undefined) {
@@ -701,10 +767,12 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 
 export async function readseekDetect(
 	filePath: string,
-	options: { transcribe?: boolean; signal?: AbortSignal } = {},
+	options: ReadSeekDetectOptions = {},
 ): Promise<ReadSeekDetection> {
 	const args = ["detect"];
 	if (options.transcribe) args.push("--transcribe");
+	if (options.caption) args.push("--caption");
+	if (options.objects) args.push("--objects");
 	args.push(filePath);
 	return parseDetectOutput(await runReadSeek(args, { signal: options.signal }));
 }

package/src/readseek-settings.ts

@@ -1,10 +1,11 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync, statSync, type Stats } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 interface ReadSeekJsonSettings {
   grep?: { maxLines?: number; maxBytes?: number };
   edit?: { diffDisplay?: "collapsed" | "expanded" };
+  read?: { ocrMode?: "on" | "off" | "auto" };
 }
 
 interface ReadSeekSettingsWarning {
@@ -75,19 +76,55 @@ function validateSettings(raw: unknown, source: string): ReadSeekSettingsResult
     if (Object.keys(edit).length > 0) settings.edit = edit;
   }
 
+  if (isRecord(raw.read)) {
+    const read: NonNullable<ReadSeekJsonSettings["read"]> = {};
+    if ("ocrMode" in raw.read) {
+      const value = raw.read.ocrMode;
+      if (value === "on" || value === "off" || value === "auto") read.ocrMode = value;
+      else warnings.push(invalid(source, "read.ocrMode"));
+    }
+    if (Object.keys(read).length > 0) settings.read = read;
+  }
+
   return { settings, warnings };
 }
 
+interface SettingsFileCacheEntry {
+  mtimeMs: number;
+  size: number;
+  result: ReadSeekSettingsResult;
+}
+
+const settingsFileCache = new Map<string, SettingsFileCacheEntry>();
+
+function statFileOrNull(path: string): Stats | null {
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+}
+
 function readSettingsFile(path: string): ReadSeekSettingsResult {
-  if (!existsSync(path)) return { settings: {}, warnings: [] };
+  const stats = statFileOrNull(path);
+  if (!stats) {
+    settingsFileCache.delete(path);
+    return { settings: {}, warnings: [] };
+  }
 
+  const cached = settingsFileCache.get(path);
+  if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) return cached.result;
+
+  let result: ReadSeekSettingsResult;
   try {
     const text = readFileSync(path, "utf8");
-    return validateSettings(JSON.parse(text) as unknown, path);
+    result = validateSettings(JSON.parse(text) as unknown, path);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    return { settings: {}, warnings: [{ source: path, message: `Invalid JSON: ${message}` }] };
+    result = { settings: {}, warnings: [{ source: path, message: `Invalid JSON: ${message}` }] };
   }
+  settingsFileCache.set(path, { mtimeMs: stats.mtimeMs, size: stats.size, result });
+  return result;
 }
 
 function mergeSettings(base: ReadSeekJsonSettings, override: ReadSeekJsonSettings): ReadSeekJsonSettings {
@@ -96,6 +133,8 @@ function mergeSettings(base: ReadSeekJsonSettings, override: ReadSeekJsonSetting
   if (Object.keys(grep).length > 0) merged.grep = grep;
   const edit = { ...(base.edit ?? {}), ...(override.edit ?? {}) };
   if (Object.keys(edit).length > 0) merged.edit = edit;
+  const read = { ...(base.read ?? {}), ...(override.read ?? {}) };
+  if (Object.keys(read).length > 0) merged.read = read;
   return merged;
 }
 
@@ -118,3 +157,14 @@ export function resolveEditDiffDisplay(env: NodeJS.ProcessEnv = process.env): "c
   if (json === "expanded" || json === "collapsed") return json;
   return "collapsed";
 }
+
+export function resolveReadSeekOcrMode(env: NodeJS.ProcessEnv = process.env): "on" | "off" | "auto" {
+  const raw = env.READSEEK_READ_OCR_MODE;
+  if (typeof raw === "string") {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "on" || normalized === "off" || normalized === "auto") return normalized;
+  }
+  const json = resolveReadSeekJsonSettings().settings.read?.ocrMode;
+  if (json === "on" || json === "off" || json === "auto") return json;
+  return "on";
+}

package/src/stat-search-path.ts

@@ -2,6 +2,7 @@ import { stat as fsStat } from "node:fs/promises";
 import type { Stats } from "node:fs";
 
 import { buildToolErrorResult, type ToolErrorResult } from "./readseek-value.js";
+import { formatFsError } from "./fs-error.js";
 
 export type StatSearchPathResult =
   | { ok: true; stats: Stats }
@@ -22,13 +23,7 @@ export async function statSearchPathOrError(
   } catch (err: any) {
     const display = rawPath ?? ".";
     const path = rawPath ?? searchPath;
-    if (err?.code === "ENOENT") {
-      return { ok: false, error: buildToolErrorResult(tool, "path-not-found", `Path '${display}' does not exist`, { path }) };
-    }
-    if (err?.code === "EACCES" || err?.code === "EPERM") {
-      return { ok: false, error: buildToolErrorResult(tool, "permission-denied", `Permission denied for path '${display}'`, { path }) };
-    }
-    const message = `Could not access path '${display}': ${err?.message ?? String(err)}`;
-    return { ok: false, error: buildToolErrorResult(tool, "fs-error", message, { path, details: { fsCode: err?.code, fsMessage: err?.message } }) };
+    const { code, message } = formatFsError(err, "stat-error");
+    return { ok: false, error: buildToolErrorResult(tool, code, message, { path }) };
   }
 }

package/src/tui-render-utils.ts

@@ -149,6 +149,26 @@ export function wrapReadHashlinesForWidth(text: string, width: number | undefine
   return output.join("\n");
 }
 
+const wrappedHashlinesCache = new WeakMap<object, { text: string; width: number | undefined; wrapped: string }>();
+
+/**
+ * Memoized {@link wrapReadHashlinesForWidth} for render paths that re-run on
+ * every TUI frame: the wrapped output is cached per result content object so
+ * an expanded read result is only re-wrapped when its text or the terminal
+ * width changes.
+ */
+export function wrapReadHashlinesForWidthCached(
+  cacheKey: object,
+  text: string,
+  width: number | undefined,
+): string {
+  const cached = wrappedHashlinesCache.get(cacheKey);
+  if (cached && cached.text === text && cached.width === width) return cached.wrapped;
+  const wrapped = wrapReadHashlinesForWidth(text, width);
+  wrappedHashlinesCache.set(cacheKey, { text, width, wrapped });
+  return wrapped;
+}
+
 /**
  * Render the `isPartial` placeholder line shared by every tool's `renderResult`.
  */

package/src/write.ts

@@ -9,7 +9,7 @@ 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 { looksLikeBinary } from "./binary-detect.js";
-import { classifyFsError, type FsErrorCode } from "./fs-error.js";
+import { formatFsError } from "./fs-error.js";
 import { getOrGenerateMap } from "./file-map.js";
 import { formatFileMapWithBudget } from "./readseek/formatter.js";
 
@@ -120,57 +120,12 @@ export interface WriteToolOptions {
   onFileAnchored?: FileAnchoredCallback;
 }
 
-type MappedFsError = {
-  code: FsErrorCode | "fs-error";
-  message: string;
-  hint?: string;
-  includeMeta: boolean;
-};
-
-function mapFsWriteError(err: any, path: string): MappedFsError {
-  const phase: "mkdir" | "write" | undefined = err?.__phase;
-  const fsCode = err?.code as string | undefined;
-
-  if (fsCode === "ENOENT" && phase === "mkdir") {
-    return {
-      code: "fs-error",
-      message: `Cannot create parent directories for ${path}: ${err?.message ?? String(err)}`,
-      includeMeta: true,
-    };
-  }
-  if (fsCode === "ENOSPC") {
-    return {
-      code: "fs-error",
-      message: `No space left on device — cannot write: ${path}`,
-      includeMeta: true,
-    };
-  }
-  if (fsCode === "EROFS") {
-    return {
-      code: "fs-error",
-      message: `Read-only filesystem — cannot write: ${path}`,
-      includeMeta: true,
-    };
-  }
-  const fsError = classifyFsError(err, path);
-  if (fsError) {
-    return { code: fsError.code, message: fsError.message, hint: fsError.hint, includeMeta: false };
-  }
-  return {
-    code: "fs-error",
-    message: `Error writing ${path}: ${err?.message ?? String(err)}`,
-    includeMeta: true,
-  };
-}
-
 function buildWriteFsErrorResult(err: any, absolutePath: string) {
-  const mapped = mapFsWriteError(err, absolutePath);
-  return buildToolErrorResult("write", mapped.code, mapped.message, {
-    path: absolutePath,
-    hint: mapped.hint,
-    extra: { lines: [], warnings: [] },
-    details: mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
-  });
+	const { code, message } = formatFsError(err, "write-error");
+	return buildToolErrorResult("write", code, message, {
+		path: absolutePath,
+		extra: { lines: [], warnings: [] },
+	});
 }
 
 export async function executeWrite(opts: {
@@ -218,21 +173,10 @@ export async function executeWrite(opts: {
   const previousContent = await readPreviousTextForDiff(filePath);
   const existedBeforeWrite = await access(filePath).then(() => true, () => false);
 
-  // Create parent directories
-  try {
-    await mkdir(dirname(filePath), { recursive: true });
-  } catch (err: any) {
-    err.__phase = "mkdir";
-    throw err;
-  }
-  // Write file
-  try {
-    await writeFile(filePath, content, "utf-8");
-  } catch (err: any) {
-    err.__phase = "write";
-    throw err;
-  }
-
+	// Create parent directories
+	await mkdir(dirname(filePath), { recursive: true });
+	// Write file
+	await writeFile(filePath, content, "utf-8");
   // Compute hashlines
   const rawLines = content.split("\n");
   const readseekLines: ReadSeekLine[] = [];