refactor(agent): add result-based execution env

packages/agent/src/harness/env/nodejs.ts

@@ -1,33 +1,59 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { access, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import {
+	access,
+	appendFile,
+	lstat,
+	mkdir,
+	mkdtemp,
+	readdir,
+	readFile,
+	realpath,
+	rm,
+	writeFile,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
-import { type ExecutionEnv, FileError, type FileInfo, type FileKind } from "../types.js";
+import {
+	type ExecutionEnv,
+	ExecutionError,
+	err,
+	FileError,
+	type FileInfo,
+	type FileKind,
+	ok,
+	type Result,
+} from "../types.js";
 
 function resolvePath(cwd: string, path: string): string {
 	return isAbsolute(path) ? path : resolve(cwd, path);
 }
 
-function fileKindFromStats(stats: { isFile(): boolean; isDirectory(): boolean; isSymbolicLink(): boolean }): FileKind {
+function fileKindFromStats(stats: {
+	isFile(): boolean;
+	isDirectory(): boolean;
+	isSymbolicLink(): boolean;
+}): FileKind | undefined {
 	if (stats.isFile()) return "file";
 	if (stats.isDirectory()) return "directory";
 	if (stats.isSymbolicLink()) return "symlink";
-	throw new FileError("invalid", "Unsupported file type");
+	return undefined;
 }
 
 function fileInfoFromStats(
 	path: string,
 	stats: { isFile(): boolean; isDirectory(): boolean; isSymbolicLink(): boolean; size: number; mtimeMs: number },
-): FileInfo {
-	return {
+): Result<FileInfo, FileError> {
+	const kind = fileKindFromStats(stats);
+	if (!kind) return err(new FileError("invalid", "Unsupported file type", path));
+	return ok({
 		name: path.replace(/\/+$/, "").split("/").pop() ?? path,
 		path,
-		kind: fileKindFromStats(stats),
+		kind,
 		size: stats.size,
 		mtimeMs: stats.mtimeMs,
-	};
+	});
 }
 
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
@@ -39,20 +65,26 @@ function toFileError(error: unknown, path?: string): FileError {
 	if (isNodeError(error)) {
 		const message = error.message;
 		switch (error.code) {
+			case "ABORT_ERR":
+				return new FileError("aborted", message, path, error);
 			case "ENOENT":
-				return new FileError("not_found", message, path, { cause: error });
+				return new FileError("not_found", message, path, error);
 			case "EACCES":
 			case "EPERM":
-				return new FileError("permission_denied", message, path, { cause: error });
+				return new FileError("permission_denied", message, path, error);
 			case "ENOTDIR":
-				return new FileError("not_directory", message, path, { cause: error });
+				return new FileError("not_directory", message, path, error);
 			case "EISDIR":
-				return new FileError("is_directory", message, path, { cause: error });
+				return new FileError("is_directory", message, path, error);
 			case "EINVAL":
-				return new FileError("invalid", message, path, { cause: error });
+				return new FileError("invalid", message, path, error);
 		}
 	}
-	return new FileError("unknown", error instanceof Error ? error.message : String(error), path, { cause: error });
+	return new FileError("unknown", error instanceof Error ? error.message : String(error), path, error);
+}
+
+function abortResult<TValue>(signal: AbortSignal | undefined, path?: string): Result<TValue, FileError> | undefined {
+	return signal?.aborted ? err(new FileError("aborted", "aborted", path)) : undefined;
 }
 
 async function pathExists(path: string): Promise<boolean> {
@@ -71,7 +103,13 @@ async function runCommand(
 ): Promise<{ stdout: string; status: number | null }> {
 	return await new Promise((resolve) => {
 		let stdout = "";
-		const child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"] });
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"] });
+		} catch {
+			resolve({ stdout: "", status: null });
+			return;
+		}
 		const timeout = setTimeout(() => {
 			if (child.pid) killProcessTree(child.pid);
 		}, timeoutMs);
@@ -100,12 +138,14 @@ async function findBashOnPath(): Promise<string | null> {
 	return firstMatch && (await pathExists(firstMatch)) ? firstMatch : null;
 }
 
-async function getShellConfig(customShellPath?: string): Promise<{ shell: string; args: string[] }> {
+async function getShellConfig(
+	customShellPath?: string,
+): Promise<Result<{ shell: string; args: string[] }, ExecutionError>> {
 	if (customShellPath) {
 		if (await pathExists(customShellPath)) {
-			return { shell: customShellPath, args: ["-c"] };
+			return ok({ shell: customShellPath, args: ["-c"] });
 		}
-		throw new Error(`Custom shell path not found: ${customShellPath}`);
+		return err(new ExecutionError("shell_unavailable", `Custom shell path not found: ${customShellPath}`));
 	}
 	if (process.platform === "win32") {
 		const candidates: string[] = [];
@@ -115,24 +155,24 @@ async function getShellConfig(customShellPath?: string): Promise<{ shell: string
 		if (programFilesX86) candidates.push(`${programFilesX86}\\Git\\bin\\bash.exe`);
 		for (const candidate of candidates) {
 			if (await pathExists(candidate)) {
-				return { shell: candidate, args: ["-c"] };
+				return ok({ shell: candidate, args: ["-c"] });
 			}
 		}
 		const bashOnPath = await findBashOnPath();
 		if (bashOnPath) {
-			return { shell: bashOnPath, args: ["-c"] };
+			return ok({ shell: bashOnPath, args: ["-c"] });
 		}
-		throw new Error("No bash shell found");
+		return err(new ExecutionError("shell_unavailable", "No bash shell found"));
 	}
 
 	if (await pathExists("/bin/bash")) {
-		return { shell: "/bin/bash", args: ["-c"] };
+		return ok({ shell: "/bin/bash", args: ["-c"] });
 	}
 	const bashOnPath = await findBashOnPath();
 	if (bashOnPath) {
-		return { shell: bashOnPath, args: ["-c"] };
+		return ok({ shell: bashOnPath, args: ["-c"] });
 	}
-	return { shell: "sh", args: ["-c"] };
+	return ok({ shell: "sh", args: ["-c"] });
 }
 
 function getShellEnv(baseEnv?: NodeJS.ProcessEnv, extraEnv?: Record<string, string>): NodeJS.ProcessEnv {
@@ -184,46 +224,69 @@ export class NodeExecutionEnv implements ExecutionEnv {
 			cwd?: string;
 			env?: Record<string, string>;
 			timeout?: number;
-			signal?: AbortSignal;
+			abortSignal?: AbortSignal;
 			onStdout?: (chunk: string) => void;
 			onStderr?: (chunk: string) => void;
 		},
-	): Promise<{ stdout: string; stderr: string; exitCode: number }> {
-		const cwd = options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd;
-		const { shell, args } = await getShellConfig(this.shellPath);
+	): Promise<Result<{ stdout: string; stderr: string; exitCode: number }, ExecutionError>> {
+		if (options?.abortSignal?.aborted) return err(new ExecutionError("aborted", "aborted"));
 
-		return await new Promise((resolvePromise, reject) => {
+		const cwd = options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd;
+		const shellConfig = await getShellConfig(this.shellPath);
+		if (!shellConfig.ok) return shellConfig;
+
+		return await new Promise((resolvePromise) => {
 			let stdout = "";
 			let stderr = "";
 			let settled = false;
 			let timedOut = false;
-			const child = spawn(shell, [...args, command], {
-				cwd,
-				detached: process.platform !== "win32",
-				env: getShellEnv(this.shellEnv, options?.env),
-				stdio: ["ignore", "pipe", "pipe"],
-			});
+			let callbackError: ExecutionError | undefined;
+			let child: ReturnType<typeof spawn> | undefined;
+			let timeoutId: ReturnType<typeof setTimeout> | undefined;
 
-			const timeoutId =
+			const onAbort = () => {
+				if (child?.pid) {
+					killProcessTree(child.pid);
+				}
+			};
+
+			const settle = (result: Result<{ stdout: string; stderr: string; exitCode: number }, ExecutionError>) => {
+				if (timeoutId) clearTimeout(timeoutId);
+				if (options?.abortSignal) options.abortSignal.removeEventListener("abort", onAbort);
+				if (settled) return;
+				settled = true;
+				resolvePromise(result);
+			};
+
+			try {
+				child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
+					cwd,
+					detached: process.platform !== "win32",
+					env: getShellEnv(this.shellEnv, options?.env),
+					stdio: ["ignore", "pipe", "pipe"],
+				});
+			} catch (error) {
+				settle(
+					err(new ExecutionError("spawn_error", error instanceof Error ? error.message : String(error), error)),
+				);
+				return;
+			}
+
+			timeoutId =
 				typeof options?.timeout === "number"
 					? setTimeout(() => {
 							timedOut = true;
-							if (child.pid) {
+							if (child?.pid) {
 								killProcessTree(child.pid);
 							}
 						}, options.timeout * 1000)
 					: undefined;
 
-			const onAbort = () => {
-				if (child.pid) {
-					killProcessTree(child.pid);
-				}
-			};
-			if (options?.signal) {
-				if (options.signal.aborted) {
+			if (options?.abortSignal) {
+				if (options.abortSignal.aborted) {
 					onAbort();
 				} else {
-					options.signal.addEventListener("abort", onAbort, { once: true });
+					options.abortSignal.addEventListener("abort", onAbort, { once: true });
 				}
 			}
 
@@ -231,137 +294,231 @@ export class NodeExecutionEnv implements ExecutionEnv {
 			child.stderr?.setEncoding("utf8");
 			child.stdout?.on("data", (chunk: string) => {
 				stdout += chunk;
-				options?.onStdout?.(chunk);
+				try {
+					options?.onStdout?.(chunk);
+				} catch (error) {
+					callbackError = new ExecutionError(
+						"unknown",
+						error instanceof Error ? error.message : String(error),
+						error,
+					);
+					onAbort();
+				}
 			});
 			child.stderr?.on("data", (chunk: string) => {
 				stderr += chunk;
-				options?.onStderr?.(chunk);
+				try {
+					options?.onStderr?.(chunk);
+				} catch (error) {
+					callbackError = new ExecutionError(
+						"unknown",
+						error instanceof Error ? error.message : String(error),
+						error,
+					);
+					onAbort();
+				}
 			});
 
 			child.on("error", (error) => {
-				if (timeoutId) clearTimeout(timeoutId);
-				if (options?.signal) options.signal.removeEventListener("abort", onAbort);
-				if (settled) return;
-				settled = true;
-				reject(error);
+				settle(err(new ExecutionError("spawn_error", error.message, error)));
 			});
 
 			child.on("close", (code) => {
-				if (timeoutId) clearTimeout(timeoutId);
-				if (options?.signal) options.signal.removeEventListener("abort", onAbort);
-				if (settled) return;
-				settled = true;
-				if (options?.signal?.aborted) {
-					reject(new Error("aborted"));
+				if (callbackError) {
+					settle(err(callbackError));
+					return;
+				}
+				if (options?.abortSignal?.aborted) {
+					settle(err(new ExecutionError("aborted", "aborted")));
 					return;
 				}
 				if (timedOut) {
-					reject(new Error(`timeout:${options?.timeout}`));
+					settle(err(new ExecutionError("timeout", `timeout:${options?.timeout}`)));
 					return;
 				}
-				resolvePromise({ stdout, stderr, exitCode: code ?? 0 });
+				settle(ok({ stdout, stderr, exitCode: code ?? 0 }));
 			});
 		});
 	}
 
-	async readTextFile(path: string): Promise<string> {
+	async readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>> {
 		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<string>(abortSignal, resolved);
+		if (aborted) return aborted;
 		try {
-			return await readFile(resolved, "utf8");
+			return ok(await readFile(resolved, { encoding: "utf8", signal: abortSignal }));
 		} catch (error) {
-			throw toFileError(error, resolved);
+			return err(toFileError(error, resolved));
 		}
 	}
 
-	async readBinaryFile(path: string): Promise<Uint8Array> {
+	async readBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>> {
 		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<Uint8Array>(abortSignal, resolved);
+		if (aborted) return aborted;
 		try {
-			return await readFile(resolved);
+			return ok(await readFile(resolved, { signal: abortSignal }));
 		} catch (error) {
-			throw toFileError(error, resolved);
+			return err(toFileError(error, resolved));
 		}
 	}
 
-	async writeFile(path: string, content: string | Uint8Array): Promise<void> {
+	async writeFile(
+		path: string,
+		content: string | Uint8Array,
+		abortSignal?: AbortSignal,
+	): Promise<Result<void, FileError>> {
 		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<void>(abortSignal, resolved);
+		if (aborted) return aborted;
 		try {
 			await mkdir(resolve(resolved, ".."), { recursive: true });
-			await writeFile(resolved, content);
+			const afterMkdirAbort = abortResult<void>(abortSignal, resolved);
+			if (afterMkdirAbort) return afterMkdirAbort;
+			await writeFile(resolved, content, { signal: abortSignal });
+			return ok(undefined);
 		} catch (error) {
-			throw toFileError(error, resolved);
+			return err(toFileError(error, resolved));
 		}
 	}
 
-	async fileInfo(path: string): Promise<FileInfo> {
+	async appendFile(
+		path: string,
+		content: string | Uint8Array,
+		abortSignal?: AbortSignal,
+	): Promise<Result<void, FileError>> {
 		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<void>(abortSignal, resolved);
+		if (aborted) return aborted;
+		try {
+			await mkdir(resolve(resolved, ".."), { recursive: true });
+			const afterMkdirAbort = abortResult<void>(abortSignal, resolved);
+			if (afterMkdirAbort) return afterMkdirAbort;
+			await appendFile(resolved, content);
+			const afterAppendAbort = abortResult<void>(abortSignal, resolved);
+			if (afterAppendAbort) return afterAppendAbort;
+			return ok(undefined);
+		} catch (error) {
+			return err(toFileError(error, resolved));
+		}
+	}
+
+	async fileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>> {
+		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<FileInfo>(abortSignal, resolved);
+		if (aborted) return aborted;
 		try {
 			return fileInfoFromStats(resolved, await lstat(resolved));
 		} catch (error) {
-			throw toFileError(error, resolved);
+			return err(toFileError(error, resolved));
 		}
 	}
 
-	async listDir(path: string): Promise<FileInfo[]> {
+	async listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>> {
 		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<FileInfo[]>(abortSignal, resolved);
+		if (aborted) return aborted;
 		try {
 			const entries = await readdir(resolved, { withFileTypes: true });
 			const infos: FileInfo[] = [];
 			for (const entry of entries) {
+				const loopAbort = abortResult<FileInfo[]>(abortSignal, resolved);
+				if (loopAbort) return loopAbort;
 				const entryPath = resolve(resolved, entry.name);
 				try {
-					infos.push(fileInfoFromStats(entryPath, await lstat(entryPath)));
+					const info = fileInfoFromStats(entryPath, await lstat(entryPath));
+					if (info.ok) infos.push(info.value);
 				} catch (error) {
-					if (error instanceof FileError && error.code === "invalid") continue;
-					throw error;
+					return err(toFileError(error, entryPath));
 				}
 			}
-			return infos;
+			return ok(infos);
 		} catch (error) {
-			throw toFileError(error, resolved);
+			return err(toFileError(error, resolved));
 		}
 	}
 
-	async realPath(path: string): Promise<string> {
+	async realPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>> {
 		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<string>(abortSignal, resolved);
+		if (aborted) return aborted;
 		try {
-			return await realpath(resolved);
+			return ok(await realpath(resolved));
 		} catch (error) {
-			throw toFileError(error, resolved);
+			return err(toFileError(error, resolved));
 		}
 	}
 
-	async exists(path: string): Promise<boolean> {
-		try {
-			await this.fileInfo(path);
-			return true;
-		} catch (error) {
-			if (error instanceof FileError && error.code === "not_found") return false;
-			throw error;
-		}
+	async exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>> {
+		const result = await this.fileInfo(path, abortSignal);
+		if (result.ok) return ok(true);
+		if (result.error.code === "not_found") return ok(false);
+		return err(result.error);
 	}
 
-	async createDir(path: string, options?: { recursive?: boolean }): Promise<void> {
-		await mkdir(resolvePath(this.cwd, path), { recursive: options?.recursive });
-	}
-
-	async remove(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void> {
+	async createDir(
+		path: string,
+		options?: { recursive?: boolean; abortSignal?: AbortSignal },
+	): Promise<Result<void, FileError>> {
 		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<void>(options?.abortSignal, resolved);
+		if (aborted) return aborted;
+		try {
+			await mkdir(resolved, { recursive: options?.recursive ?? true });
+			const afterMkdirAbort = abortResult<void>(options?.abortSignal, resolved);
+			if (afterMkdirAbort) return afterMkdirAbort;
+			return ok(undefined);
+		} catch (error) {
+			return err(toFileError(error, resolved));
+		}
+	}
+
+	async remove(
+		path: string,
+		options?: { recursive?: boolean; force?: boolean; abortSignal?: AbortSignal },
+	): Promise<Result<void, FileError>> {
+		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<void>(options?.abortSignal, resolved);
+		if (aborted) return aborted;
 		try {
 			await rm(resolved, { recursive: options?.recursive ?? false, force: options?.force ?? false });
+			const afterRemoveAbort = abortResult<void>(options?.abortSignal, resolved);
+			if (afterRemoveAbort) return afterRemoveAbort;
+			return ok(undefined);
 		} catch (error) {
-			throw toFileError(error, resolved);
+			return err(toFileError(error, resolved));
 		}
 	}
 
-	async createTempDir(prefix: string = "tmp-"): Promise<string> {
-		return await mkdtemp(join(tmpdir(), prefix));
+	async createTempDir(prefix: string = "tmp-", abortSignal?: AbortSignal): Promise<Result<string, FileError>> {
+		const aborted = abortResult<string>(abortSignal);
+		if (aborted) return aborted;
+		try {
+			const path = await mkdtemp(join(tmpdir(), prefix));
+			const afterMkdtempAbort = abortResult<string>(abortSignal, path);
+			if (afterMkdtempAbort) return afterMkdtempAbort;
+			return ok(path);
+		} catch (error) {
+			return err(toFileError(error));
+		}
 	}
 
-	async createTempFile(options?: { prefix?: string; suffix?: string }): Promise<string> {
-		const dir = await this.createTempDir("tmp-");
-		const filePath = join(dir, `${options?.prefix ?? ""}${randomUUID()}${options?.suffix ?? ""}`);
-		await writeFile(filePath, "");
-		return filePath;
+	async createTempFile(options?: {
+		prefix?: string;
+		suffix?: string;
+		abortSignal?: AbortSignal;
+	}): Promise<Result<string, FileError>> {
+		const dir = await this.createTempDir("tmp-", options?.abortSignal);
+		if (!dir.ok) return dir;
+		const filePath = join(dir.value, `${options?.prefix ?? ""}${randomUUID()}${options?.suffix ?? ""}`);
+		const aborted = abortResult<string>(options?.abortSignal, filePath);
+		if (aborted) return aborted;
+		try {
+			await writeFile(filePath, "", { signal: options?.abortSignal });
+			return ok(filePath);
+		} catch (error) {
+			return err(toFileError(error, filePath));
+		}
 	}
 
 	async cleanup(): Promise<void> {

packages/agent/src/harness/execution-env.ts

@@ -1,3 +1,10 @@
-export { NodeExecutionEnv } from "./env/nodejs.js";
-export type { ExecutionEnv, ExecutionEnvExecOptions, FileErrorCode, FileInfo, FileKind } from "./types.js";
-export { FileError } from "./types.js";
+export type {
+	ExecutionEnv,
+	ExecutionEnvExecOptions,
+	ExecutionErrorCode,
+	FileErrorCode,
+	FileInfo,
+	FileKind,
+	Result,
+} from "./types.js";
+export { ExecutionError, err, FileError, getOrThrow, getOrUndefined, ok } from "./types.js";

packages/agent/src/harness/prompt-templates.ts

@@ -1,5 +1,5 @@
 import { parse } from "yaml";
-import type { ExecutionEnv, FileInfo, PromptTemplate } from "./types.js";
+import { type ExecutionEnv, type FileInfo, getOrUndefined, type PromptTemplate, type Result } from "./types.js";
 
 /** Warning produced while loading prompt templates. */
 export interface PromptTemplateDiagnostic {
@@ -30,7 +30,7 @@ export async function loadPromptTemplates(
 	const promptTemplates: PromptTemplate[] = [];
 	const diagnostics: PromptTemplateDiagnostic[] = [];
 	for (const path of Array.isArray(paths) ? paths : [paths]) {
-		const info = await safeFileInfo(env, path);
+		const info = getOrUndefined(await env.fileInfo(path));
 		if (!info) continue;
 		const kind = await resolveKind(env, info);
 		if (kind === "directory") {
@@ -83,17 +83,16 @@ async function loadTemplatesFromDir(
 ): Promise<{ promptTemplates: PromptTemplate[]; diagnostics: PromptTemplateDiagnostic[] }> {
 	const promptTemplates: PromptTemplate[] = [];
 	const diagnostics: PromptTemplateDiagnostic[] = [];
-	let entries: FileInfo[];
-	try {
-		entries = await env.listDir(dir);
-	} catch (error) {
+	const entriesResult = await env.listDir(dir);
+	if (!entriesResult.ok) {
 		diagnostics.push({
 			type: "warning",
-			message: errorMessage(error, "failed to list prompt template directory"),
+			message: entriesResult.error.message,
 			path: dir,
 		});
 		return { promptTemplates, diagnostics };
 	}
+	const entries = entriesResult.value;
 
 	for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
 		const kind = await resolveKind(env, entry);
@@ -110,60 +109,66 @@ async function loadTemplateFromFile(
 	filePath: string,
 ): Promise<{ promptTemplate: PromptTemplate | null; diagnostics: PromptTemplateDiagnostic[] }> {
 	const diagnostics: PromptTemplateDiagnostic[] = [];
-	try {
-		const rawContent = await env.readTextFile(filePath);
-		const { frontmatter, body } = parseFrontmatter<PromptTemplateFrontmatter>(rawContent);
-		const firstLine = body.split("\n").find((line) => line.trim());
-		let description = typeof frontmatter.description === "string" ? frontmatter.description : "";
-		if (!description && firstLine) {
-			description = firstLine.slice(0, 60);
-			if (firstLine.length > 60) description += "...";
-		}
-		return {
-			promptTemplate: {
-				name: basenameEnvPath(filePath).replace(/\.md$/i, ""),
-				description,
-				content: body,
-			},
-			diagnostics,
-		};
-	} catch (error) {
+	const rawContent = await env.readTextFile(filePath);
+	if (!rawContent.ok) {
 		diagnostics.push({
 			type: "warning",
-			message: errorMessage(error, "failed to load prompt template"),
+			message: rawContent.error.message,
 			path: filePath,
 		});
 		return { promptTemplate: null, diagnostics };
 	}
-}
 
-async function safeFileInfo(env: ExecutionEnv, path: string): Promise<FileInfo | undefined> {
-	try {
-		return await env.fileInfo(path);
-	} catch {
-		return undefined;
+	const parsed = parseFrontmatter<PromptTemplateFrontmatter>(rawContent.value);
+	if (!parsed.ok) {
+		diagnostics.push({
+			type: "warning",
+			message: parsed.error.message,
+			path: filePath,
+		});
+		return { promptTemplate: null, diagnostics };
 	}
+
+	const { frontmatter, body } = parsed.value;
+	const firstLine = body.split("\n").find((line) => line.trim());
+	let description = typeof frontmatter.description === "string" ? frontmatter.description : "";
+	if (!description && firstLine) {
+		description = firstLine.slice(0, 60);
+		if (firstLine.length > 60) description += "...";
+	}
+	return {
+		promptTemplate: {
+			name: basenameEnvPath(filePath).replace(/\.md$/i, ""),
+			description,
+			content: body,
+		},
+		diagnostics,
+	};
 }
 
 async function resolveKind(env: ExecutionEnv, info: FileInfo): Promise<"file" | "directory" | undefined> {
 	if (info.kind === "file" || info.kind === "directory") return info.kind;
-	try {
-		const realPath = await env.realPath(info.path);
-		const target = await env.fileInfo(realPath);
-		return target.kind === "file" || target.kind === "directory" ? target.kind : undefined;
-	} catch {
-		return undefined;
-	}
+	const realPath = await env.realPath(info.path);
+	if (!realPath.ok) return undefined;
+	const target = getOrUndefined(await env.fileInfo(realPath.value));
+	if (!target) return undefined;
+	return target.kind === "file" || target.kind === "directory" ? target.kind : undefined;
 }
 
-function parseFrontmatter<T extends Record<string, unknown>>(content: string): { frontmatter: T; body: string } {
-	const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-	if (!normalized.startsWith("---")) return { frontmatter: {} as T, body: normalized };
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) return { frontmatter: {} as T, body: normalized };
-	const yamlString = normalized.slice(4, endIndex);
-	const body = normalized.slice(endIndex + 4).trim();
-	return { frontmatter: (parse(yamlString) ?? {}) as T, body };
+function parseFrontmatter<T extends Record<string, unknown>>(
+	content: string,
+): Result<{ frontmatter: T; body: string }, Error> {
+	try {
+		const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+		if (!normalized.startsWith("---")) return { ok: true, value: { frontmatter: {} as T, body: normalized } };
+		const endIndex = normalized.indexOf("\n---", 3);
+		if (endIndex === -1) return { ok: true, value: { frontmatter: {} as T, body: normalized } };
+		const yamlString = normalized.slice(4, endIndex);
+		const body = normalized.slice(endIndex + 4).trim();
+		return { ok: true, value: { frontmatter: (parse(yamlString) ?? {}) as T, body } };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+	}
 }
 
 function basenameEnvPath(path: string): string {
@@ -172,10 +177,6 @@ function basenameEnvPath(path: string): string {
 	return slashIndex === -1 ? normalized : normalized.slice(slashIndex + 1);
 }
 
-function errorMessage(error: unknown, fallback: string): string {
-	return error instanceof Error ? error.message : fallback;
-}
-
 /** Parse an argument string using simple shell-style single and double quotes. */
 export function parseCommandArgs(argsString: string): string[] {
 	const args: string[] = [];

packages/agent/src/harness/skills.ts

@@ -1,6 +1,6 @@
 import ignore from "ignore";
 import { parse } from "yaml";
-import type { ExecutionEnv, Skill } from "./types.js";
+import { type ExecutionEnv, type FileInfo, getOrUndefined, type Result, type Skill } from "./types.js";
 
 const MAX_NAME_LENGTH = 64;
 const MAX_DESCRIPTION_LENGTH = 1024;
@@ -44,7 +44,7 @@ export async function loadSkills(
 	const skills: Skill[] = [];
 	const diagnostics: SkillDiagnostic[] = [];
 	for (const dir of Array.isArray(dirs) ? dirs : [dirs]) {
-		const rootInfo = await safeFileInfo(env, dir);
+		const rootInfo = getOrUndefined(await env.fileInfo(dir));
 		if (!rootInfo || (await resolveKind(env, rootInfo)) !== "directory") continue;
 		const result = await loadSkillsFromDirInternal(env, rootInfo.path, true, ignore(), rootInfo.path);
 		skills.push(...result.skills);
@@ -89,18 +89,13 @@ async function loadSkillsFromDirInternal(
 	const skills: Skill[] = [];
 	const diagnostics: SkillDiagnostic[] = [];
 
-	if (!(await env.exists(dir))) return { skills, diagnostics };
-	const dirInfo = await safeFileInfo(env, dir);
+	const dirInfo = getOrUndefined(await env.fileInfo(dir));
 	if (!dirInfo || (await resolveKind(env, dirInfo)) !== "directory") return { skills, diagnostics };
 
 	await addIgnoreRules(env, ignoreMatcher, dir, rootDir);
 
-	let entries: Awaited<ReturnType<ExecutionEnv["listDir"]>>;
-	try {
-		entries = await env.listDir(dir);
-	} catch {
-		return { skills, diagnostics };
-	}
+	const entries = getOrUndefined(await env.listDir(dir));
+	if (!entries) return { skills, diagnostics };
 
 	for (const entry of entries) {
 		if (entry.name !== "SKILL.md") continue;
@@ -148,16 +143,15 @@ async function addIgnoreRules(env: ExecutionEnv, ig: IgnoreMatcher, dir: string,
 
 	for (const filename of IGNORE_FILE_NAMES) {
 		const ignorePath = joinEnvPath(dir, filename);
-		const info = await safeFileInfo(env, ignorePath);
+		const info = getOrUndefined(await env.fileInfo(ignorePath));
 		if (info?.kind !== "file") continue;
-		try {
-			const content = await env.readTextFile(ignorePath);
-			const patterns = content
-				.split(/\r?\n/)
-				.map((line) => prefixIgnorePattern(line, prefix))
-				.filter((line): line is string => Boolean(line));
-			if (patterns.length > 0) ig.add(patterns);
-		} catch {}
+		const content = await env.readTextFile(ignorePath);
+		if (!content.ok) continue;
+		const patterns = content.value
+			.split(/\r?\n/)
+			.map((line) => prefixIgnorePattern(line, prefix))
+			.filter((line): line is string => Boolean(line));
+		if (patterns.length > 0) ig.add(patterns);
 	}
 }
 
@@ -184,40 +178,47 @@ async function loadSkillFromFile(
 	filePath: string,
 ): Promise<{ skill: Skill | null; diagnostics: SkillDiagnostic[] }> {
 	const diagnostics: SkillDiagnostic[] = [];
-	try {
-		const rawContent = await env.readTextFile(filePath);
-		const { frontmatter, body } = parseFrontmatter<SkillFrontmatter>(rawContent);
-		const skillDir = dirnameEnvPath(filePath);
-		const parentDirName = basenameEnvPath(skillDir);
-
-		for (const error of validateDescription(frontmatter.description)) {
-			diagnostics.push({ type: "warning", message: error, path: filePath });
-		}
-
-		const name = frontmatter.name || parentDirName;
-		for (const error of validateName(name, parentDirName)) {
-			diagnostics.push({ type: "warning", message: error, path: filePath });
-		}
-
-		if (!frontmatter.description || frontmatter.description.trim() === "") {
-			return { skill: null, diagnostics };
-		}
-
-		return {
-			skill: {
-				name,
-				description: frontmatter.description,
-				content: body,
-				filePath,
-				disableModelInvocation: frontmatter["disable-model-invocation"] === true,
-			},
-			diagnostics,
-		};
-	} catch (error) {
-		const message = error instanceof Error ? error.message : "failed to parse skill file";
-		diagnostics.push({ type: "warning", message, path: filePath });
+	const rawContent = await env.readTextFile(filePath);
+	if (!rawContent.ok) {
+		diagnostics.push({ type: "warning", message: rawContent.error.message, path: filePath });
 		return { skill: null, diagnostics };
 	}
+
+	const parsed = parseFrontmatter<SkillFrontmatter>(rawContent.value);
+	if (!parsed.ok) {
+		diagnostics.push({ type: "warning", message: parsed.error.message, path: filePath });
+		return { skill: null, diagnostics };
+	}
+
+	const { frontmatter, body } = parsed.value;
+	const skillDir = dirnameEnvPath(filePath);
+	const parentDirName = basenameEnvPath(skillDir);
+	const description = typeof frontmatter.description === "string" ? frontmatter.description : undefined;
+
+	for (const error of validateDescription(description)) {
+		diagnostics.push({ type: "warning", message: error, path: filePath });
+	}
+
+	const frontmatterName = typeof frontmatter.name === "string" ? frontmatter.name : undefined;
+	const name = frontmatterName || parentDirName;
+	for (const error of validateName(name, parentDirName)) {
+		diagnostics.push({ type: "warning", message: error, path: filePath });
+	}
+
+	if (!description || description.trim() === "") {
+		return { skill: null, diagnostics };
+	}
+
+	return {
+		skill: {
+			name,
+			description,
+			content: body,
+			filePath,
+			disableModelInvocation: frontmatter["disable-model-invocation"] === true,
+		},
+		diagnostics,
+	};
 }
 
 function validateName(name: string, parentDirName: string): string[] {
@@ -242,39 +243,29 @@ function validateDescription(description: string | undefined): string[] {
 	return errors;
 }
 
-function parseFrontmatter<T extends Record<string, unknown>>(content: string): { frontmatter: T; body: string } {
-	const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-	if (!normalized.startsWith("---")) return { frontmatter: {} as T, body: normalized };
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) return { frontmatter: {} as T, body: normalized };
-	const yamlString = normalized.slice(4, endIndex);
-	const body = normalized.slice(endIndex + 4).trim();
-	return { frontmatter: (parse(yamlString) ?? {}) as T, body };
-}
-
-async function safeFileInfo(
-	env: ExecutionEnv,
-	path: string,
-): Promise<Awaited<ReturnType<ExecutionEnv["fileInfo"]>> | undefined> {
+function parseFrontmatter<T extends Record<string, unknown>>(
+	content: string,
+): Result<{ frontmatter: T; body: string }, Error> {
 	try {
-		return await env.fileInfo(path);
-	} catch {
-		return undefined;
+		const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+		if (!normalized.startsWith("---")) return { ok: true, value: { frontmatter: {} as T, body: normalized } };
+		const endIndex = normalized.indexOf("\n---", 3);
+		if (endIndex === -1) return { ok: true, value: { frontmatter: {} as T, body: normalized } };
+		const yamlString = normalized.slice(4, endIndex);
+		const body = normalized.slice(endIndex + 4).trim();
+		return { ok: true, value: { frontmatter: (parse(yamlString) ?? {}) as T, body } };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
 	}
 }
 
-async function resolveKind(
-	env: ExecutionEnv,
-	info: Awaited<ReturnType<ExecutionEnv["fileInfo"]>>,
-): Promise<"file" | "directory" | undefined> {
+async function resolveKind(env: ExecutionEnv, info: FileInfo): Promise<"file" | "directory" | undefined> {
 	if (info.kind === "file" || info.kind === "directory") return info.kind;
-	try {
-		const realPath = await env.realPath(info.path);
-		const target = await env.fileInfo(realPath);
-		return target.kind === "file" || target.kind === "directory" ? target.kind : undefined;
-	} catch {
-		return undefined;
-	}
+	const realPath = await env.realPath(info.path);
+	if (!realPath.ok) return undefined;
+	const target = getOrUndefined(await env.fileInfo(realPath.value));
+	if (!target) return undefined;
+	return target.kind === "file" || target.kind === "directory" ? target.kind : undefined;
 }
 
 function joinEnvPath(base: string, child: string): string {

packages/agent/src/harness/types.ts

@@ -3,6 +3,30 @@ import type { QueueMode } from "../agent.js";
 import type { AgentEvent, AgentMessage, AgentTool, ThinkingLevel } from "../index.js";
 import type { Session } from "./session/session.js";
 
+/** Result of a fallible operation. Expected failures are returned as `ok: false` instead of thrown. */
+export type Result<TValue, TError> = { ok: true; value: TValue } | { ok: false; error: TError };
+
+/** Create a successful {@link Result}. */
+export function ok<TValue, TError>(value: TValue): Result<TValue, TError> {
+	return { ok: true, value };
+}
+
+/** Create a failed {@link Result}. */
+export function err<TValue, TError>(error: TError): Result<TValue, TError> {
+	return { ok: false, error };
+}
+
+/** Return the success value or throw the failure error. Intended for tests and explicit adapter boundaries. */
+export function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue {
+	if (!result.ok) throw result.error;
+	return result.value;
+}
+
+/** Return the success value or `undefined`. Only object values are allowed to avoid truthiness bugs with primitives. */
+export function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined {
+	return result.ok ? result.value : undefined;
+}
+
 /**
  * Skill loaded from a `SKILL.md` file or provided by an application.
  *
@@ -73,8 +97,9 @@ export interface AgentHarnessStreamOptionsPatch
 /** Kind of filesystem object as addressed by an {@link ExecutionEnv}. Symlinks are not followed automatically. */
 export type FileKind = "file" | "directory" | "symlink";
 
-/** Stable, backend-independent file error codes thrown by {@link ExecutionEnv} file operations. */
+/** Stable, backend-independent file error codes returned by {@link ExecutionEnv} file operations. */
 export type FileErrorCode =
+	| "aborted"
 	| "not_found"
 	| "permission_denied"
 	| "not_directory"
@@ -83,7 +108,7 @@ export type FileErrorCode =
 	| "not_supported"
 	| "unknown";
 
-/** Error thrown by {@link ExecutionEnv} file operations. */
+/** Error returned by {@link ExecutionEnv} file operations. */
 export class FileError extends Error {
 	constructor(
 		/** Backend-independent error code. */
@@ -91,13 +116,29 @@ export class FileError extends Error {
 		message: string,
 		/** Absolute addressed path associated with the failure, when available. */
 		public path?: string,
-		options?: ErrorOptions,
+		cause?: unknown,
 	) {
-		super(message, options);
+		super(message, cause === undefined ? undefined : { cause });
 		this.name = "FileError";
 	}
 }
 
+/** Stable, backend-independent execution error codes returned by {@link ExecutionEnv.exec}. */
+export type ExecutionErrorCode = "aborted" | "timeout" | "shell_unavailable" | "spawn_error" | "unknown";
+
+/** Error returned by {@link ExecutionEnv.exec}. */
+export class ExecutionError extends Error {
+	constructor(
+		/** Backend-independent error code. */
+		public code: ExecutionErrorCode,
+		message: string,
+		cause?: unknown,
+	) {
+		super(message, cause === undefined ? undefined : { cause });
+		this.name = "ExecutionError";
+	}
+}
+
 /** Metadata for one filesystem object in an {@link ExecutionEnv}. */
 export interface FileInfo {
 	/** Basename of {@link path}. */
@@ -114,14 +155,14 @@ export interface FileInfo {
 
 /** Options for {@link ExecutionEnv.exec}. */
 export interface ExecutionEnvExecOptions {
-	/** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. */
+	/** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. Defaults to {@link ExecutionEnv.cwd}. */
 	cwd?: string;
-	/** Additional environment variables for the command. Values override the environment defaults. */
+	/** Additional environment variables for the command. Values override the environment defaults. Defaults to no overrides. */
 	env?: Record<string, string>;
-	/** Timeout in seconds. Implementations should reject when the command exceeds this duration. */
+	/** Timeout in seconds. Implementations should return a timeout error when the command exceeds this duration. Defaults to no timeout. */
 	timeout?: number;
-	/** Abort signal used to terminate the command. */
-	signal?: AbortSignal;
+	/** Abort signal used to terminate the command. Defaults to no abort signal. */
+	abortSignal?: AbortSignal;
 	/** Called with stdout chunks as they are produced. */
 	onStdout?: (chunk: string) => void;
 	/** Called with stderr chunks as they are produced. */
@@ -134,7 +175,8 @@ export interface ExecutionEnvExecOptions {
  * Paths passed to methods may be absolute or relative to {@link cwd}. Paths returned by this interface are absolute
  * addressed paths in the environment, but are not canonicalized through symlinks unless returned by {@link resolvePath}.
  *
- * File operations throw {@link FileError} for expected filesystem failures such as missing paths or permission errors.
+ * Operation methods must never throw or reject. All filesystem/process failures, including unexpected backend failures,
+ * must be encoded in the returned {@link Result}. Implementations must preserve this invariant.
  */
 export interface ExecutionEnv {
 	/** Current working directory for relative paths and command execution. */
@@ -144,32 +186,44 @@ export interface ExecutionEnv {
 	exec(
 		command: string,
 		options?: ExecutionEnvExecOptions,
-	): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+	): Promise<Result<{ stdout: string; stderr: string; exitCode: number }, ExecutionError>>;
 
-	/** Read a UTF-8 text file. Throws {@link FileError}. */
-	readTextFile(path: string): Promise<string>;
-	/** Read a binary file. Throws {@link FileError}. */
-	readBinaryFile(path: string): Promise<Uint8Array>;
-	/** Create or overwrite a file, creating parent directories when supported. Throws {@link FileError}. */
-	writeFile(path: string, content: string | Uint8Array): Promise<void>;
-	/** Return metadata for the addressed path without following symlinks. Throws {@link FileError}. */
-	fileInfo(path: string): Promise<FileInfo>;
-	/** List direct children of a directory without following symlinks. Throws {@link FileError}. */
-	listDir(path: string): Promise<FileInfo[]>;
-	/** Return the canonical path for a path, following symlinks. Throws {@link FileError}. */
-	realPath(path: string): Promise<string>;
-	/** Return false for missing paths. Other errors, such as permission failures, may throw {@link FileError}. */
-	exists(path: string): Promise<boolean>;
-	/** Create a directory. */
-	createDir(path: string, options?: { recursive?: boolean }): Promise<void>;
-	/** Remove a file or directory. */
-	remove(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
-	/** Create a temporary directory and return its absolute path. */
-	createTempDir(prefix?: string): Promise<string>;
-	/** Create a temporary file and return its absolute path. */
-	createTempFile(options?: { prefix?: string; suffix?: string }): Promise<string>;
+	/** Read a UTF-8 text file. */
+	readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+	/** Read a binary file. */
+	readBinaryFile(path: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+	/** Create or overwrite a file, creating parent directories when supported. */
+	writeFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+	/** Create or append to a file, creating parent directories when supported. */
+	appendFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+	/** Return metadata for the addressed path without following symlinks. */
+	fileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
+	/** List direct children of a directory without following symlinks. */
+	listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
+	/** Return the canonical path for a path, following symlinks. */
+	realPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+	/** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */
+	exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+	/** Create a directory. Defaults: `recursive: true`, no abort signal. */
+	createDir(
+		path: string,
+		options?: { recursive?: boolean; abortSignal?: AbortSignal },
+	): Promise<Result<void, FileError>>;
+	/** Remove a file or directory. Defaults: `recursive: false`, `force: false`, no abort signal. */
+	remove(
+		path: string,
+		options?: { recursive?: boolean; force?: boolean; abortSignal?: AbortSignal },
+	): Promise<Result<void, FileError>>;
+	/** Create a temporary directory and return its absolute path. Defaults: `prefix: "tmp-"`, no abort signal. */
+	createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+	/** Create a temporary file and return its absolute path. Defaults: `prefix: ""`, `suffix: ""`, no abort signal. */
+	createTempFile(options?: {
+		prefix?: string;
+		suffix?: string;
+		abortSignal?: AbortSignal;
+	}): Promise<Result<string, FileError>>;
 
-	/** Release resources owned by the environment. */
+	/** Release resources owned by the environment. Must be best-effort and must not throw or reject. */
 	cleanup(): Promise<void>;
 }
 

packages/agent/src/harness/utils/shell-output.ts

@@ -1,8 +1,4 @@
-import { randomBytes } from "node:crypto";
-import { createWriteStream, type WriteStream } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { ExecutionEnv, ExecutionEnvExecOptions } from "../types.js";
+import { type ExecutionEnv, type ExecutionEnvExecOptions, ExecutionError, err, ok, type Result } from "../types.js";
 import { DEFAULT_MAX_BYTES, truncateTail } from "./truncate.js";
 
 export interface ShellCaptureOptions extends Omit<ExecutionEnvExecOptions, "onStdout" | "onStderr"> {
@@ -17,6 +13,12 @@ export interface ShellCaptureResult {
 	fullOutputPath?: string;
 }
 
+function toExecutionError(error: unknown): ExecutionError {
+	return error instanceof ExecutionError
+		? error
+		: new ExecutionError("unknown", error instanceof Error ? error.message : String(error), error);
+}
+
 export function sanitizeBinaryOutput(str: string): string {
 	return Array.from(str)
 		.filter((char) => {
@@ -34,41 +36,62 @@ export async function executeShellWithCapture(
 	env: ExecutionEnv,
 	command: string,
 	options?: ShellCaptureOptions,
-): Promise<ShellCaptureResult> {
+): Promise<Result<ShellCaptureResult, ExecutionError>> {
 	const outputChunks: string[] = [];
 	let outputBytes = 0;
 	const maxOutputBytes = DEFAULT_MAX_BYTES * 2;
+	const encoder = new TextEncoder();
 
-	let tempFilePath: string | undefined;
-	let tempFileStream: WriteStream | undefined;
 	let totalBytes = 0;
+	let fullOutputPath: string | undefined;
+	let writeChain: Promise<Result<void, ExecutionError>> = Promise.resolve(ok(undefined));
+	let captureError: ExecutionError | undefined;
 
-	const ensureTempFile = () => {
-		if (tempFilePath) return;
-		const id = randomBytes(8).toString("hex");
-		tempFilePath = join(tmpdir(), `bash-${id}.log`);
-		tempFileStream = createWriteStream(tempFilePath);
-		for (const chunk of outputChunks) {
-			tempFileStream.write(chunk);
-		}
+	const appendFullOutput = (text: string): void => {
+		if (!fullOutputPath || captureError) return;
+		const path = fullOutputPath;
+		writeChain = writeChain.then(async (previous) => {
+			if (!previous.ok) return previous;
+			const appendResult = await env.appendFile(path, text, options?.abortSignal);
+			return appendResult.ok ? ok(undefined) : err(toExecutionError(appendResult.error));
+		});
+	};
+
+	const ensureFullOutputFile = (initialContent: string): void => {
+		if (fullOutputPath || captureError) return;
+		writeChain = writeChain.then(async (previous) => {
+			if (!previous.ok) return previous;
+			const tempFile = await env.createTempFile({
+				prefix: "bash-",
+				suffix: ".log",
+				abortSignal: options?.abortSignal,
+			});
+			if (!tempFile.ok) return err(toExecutionError(tempFile.error));
+			fullOutputPath = tempFile.value;
+			const appendResult = await env.appendFile(tempFile.value, initialContent, options?.abortSignal);
+			return appendResult.ok ? ok(undefined) : err(toExecutionError(appendResult.error));
+		});
 	};
 
 	const onChunk = (chunk: string) => {
-		totalBytes += Buffer.byteLength(chunk, "utf-8");
-		const text = sanitizeBinaryOutput(chunk).replace(/\r/g, "");
-		if (totalBytes > DEFAULT_MAX_BYTES) {
-			ensureTempFile();
+		try {
+			totalBytes += encoder.encode(chunk).byteLength;
+			const text = sanitizeBinaryOutput(chunk).replace(/\r/g, "");
+			if (totalBytes > DEFAULT_MAX_BYTES && !fullOutputPath) {
+				ensureFullOutputFile(outputChunks.join("") + text);
+			} else {
+				appendFullOutput(text);
+			}
+			outputChunks.push(text);
+			outputBytes += text.length;
+			while (outputBytes > maxOutputBytes && outputChunks.length > 1) {
+				const removed = outputChunks.shift()!;
+				outputBytes -= removed.length;
+			}
+			options?.onChunk?.(text);
+		} catch (error) {
+			captureError = toExecutionError(error);
 		}
-		if (tempFileStream) {
-			tempFileStream.write(text);
-		}
-		outputChunks.push(text);
-		outputBytes += text.length;
-		while (outputBytes > maxOutputBytes && outputChunks.length > 1) {
-			const removed = outputChunks.shift()!;
-			outputBytes -= removed.length;
-		}
-		options?.onChunk?.(text);
 	};
 
 	try {
@@ -77,37 +100,36 @@ export async function executeShellWithCapture(
 			onStdout: onChunk,
 			onStderr: onChunk,
 		});
-		const fullOutput = outputChunks.join("");
-		const truncationResult = truncateTail(fullOutput);
-		if (truncationResult.truncated) {
-			ensureTempFile();
+		const tailOutput = outputChunks.join("");
+		const truncationResult = truncateTail(tailOutput);
+		if (truncationResult.truncated && !fullOutputPath) {
+			ensureFullOutputFile(tailOutput);
 		}
-		tempFileStream?.end();
-		const cancelled = options?.signal?.aborted ?? false;
-		return {
-			output: truncationResult.truncated ? truncationResult.content : fullOutput,
-			exitCode: cancelled ? undefined : result.exitCode,
+		const writeResult = await writeChain;
+		if (!writeResult.ok) return err(writeResult.error);
+		if (captureError) return err(captureError);
+
+		if (!result.ok) {
+			if (result.error.code === "aborted" || options?.abortSignal?.aborted) {
+				return ok({
+					output: truncationResult.truncated ? truncationResult.content : tailOutput,
+					exitCode: undefined,
+					cancelled: true,
+					truncated: truncationResult.truncated,
+					fullOutputPath,
+				});
+			}
+			return err(result.error);
+		}
+		const cancelled = options?.abortSignal?.aborted ?? false;
+		return ok({
+			output: truncationResult.truncated ? truncationResult.content : tailOutput,
+			exitCode: cancelled ? undefined : result.value.exitCode,
 			cancelled,
 			truncated: truncationResult.truncated,
-			fullOutputPath: tempFilePath,
-		};
-	} catch (err) {
-		if (options?.signal?.aborted) {
-			const fullOutput = outputChunks.join("");
-			const truncationResult = truncateTail(fullOutput);
-			if (truncationResult.truncated) {
-				ensureTempFile();
-			}
-			tempFileStream?.end();
-			return {
-				output: truncationResult.truncated ? truncationResult.content : fullOutput,
-				exitCode: undefined,
-				cancelled: true,
-				truncated: truncationResult.truncated,
-				fullOutputPath: tempFilePath,
-			};
-		}
-		tempFileStream?.end();
-		throw err;
+			fullOutputPath,
+		});
+	} catch (error) {
+		return err(toExecutionError(error));
 	}
 }