@oh-my-pi/pi-coding-agent 15.5.15 → 15.6.0

package/src/tiny/worker.ts

@@ -0,0 +1,523 @@
+import * as fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { parentPort } from "node:worker_threads";
+import type {
+	ProgressInfo,
+	TextGenerationPipeline,
+	TextGenerationStringOutput,
+	StoppingCriteria as TransformersStoppingCriteria,
+} from "@huggingface/transformers";
+import { getTinyModelsCacheDir, isCompiledBinary, prompt } from "@oh-my-pi/pi-utils";
+import packageJson from "../../package.json" with { type: "json" };
+import tinyTitleSystemPrompt from "../prompts/system/tiny-title-system.md" with { type: "text" };
+import { getTinyLocalModelSpec, type TinyLocalModelKey, type TinyTitleLocalModelKey } from "./models";
+import { formatTitleUserMessage, normalizeGeneratedTitle } from "./text";
+import type {
+	TinyTitleProgressEvent,
+	TinyTitleTransport,
+	TinyTitleWorkerInbound,
+	TinyTitleWorkerOutbound,
+} from "./title-protocol";
+
+const TITLE_PREFILL = "<title>";
+const TITLE_CLOSE = "</title>";
+const TITLE_MAX_NEW_TOKENS = 20;
+const STOP_DECODE_WINDOW_TOKENS = 32;
+const MEMORY_COMPLETION_MAX_NEW_TOKENS = 256;
+const TINY_TITLE_SYSTEM_PROMPT = prompt.render(tinyTitleSystemPrompt);
+const TRANSFORMERS_PACKAGE = "@huggingface/transformers";
+const sourceRequire = createRequire(import.meta.url);
+const INSTALL_LOCK_ATTEMPTS = 240;
+const INSTALL_LOCK_SLEEP_MS = 250;
+
+interface TransformersRuntime {
+	env: {
+		cacheDir?: string;
+		allowLocalModels?: boolean;
+		logLevel?: unknown;
+	};
+	LogLevel: {
+		ERROR: unknown;
+	};
+	StoppingCriteria: new () => TransformersStoppingCriteria;
+	pipeline: (
+		task: "text-generation",
+		model: string,
+		options: {
+			device: "cpu";
+			dtype: "q4";
+			progress_callback: (info: ProgressInfo) => void;
+		},
+	) => Promise<TextGenerationPipeline>;
+}
+
+const pipelines = new Map<TinyLocalModelKey, Promise<TextGenerationPipeline>>();
+
+function resolveTransformersVersionSpec(): string {
+	const manifest = packageJson as {
+		optionalDependencies?: Record<string, string>;
+		dependencies?: Record<string, string>;
+	};
+	const versionSpec =
+		manifest.optionalDependencies?.[TRANSFORMERS_PACKAGE] ?? manifest.dependencies?.[TRANSFORMERS_PACKAGE];
+	if (!versionSpec) throw new Error(`${TRANSFORMERS_PACKAGE} is missing from package.json optionalDependencies`);
+	if (!versionSpec.startsWith("catalog:")) return versionSpec;
+	const installed = sourceRequire(`${TRANSFORMERS_PACKAGE}/package.json`) as { version: string };
+	return installed.version;
+}
+let cachedTransformersVersionSpec: string | undefined;
+/**
+ * Lazily resolve (and memoize) the transformers version spec. In the
+ * `catalog:` case {@link resolveTransformersVersionSpec} `require`s the
+ * installed `@huggingface/transformers/package.json`, so touching it forces
+ * the dependency to exist. Defer it to the compiled-binary runtime-install
+ * path — which only runs when a local title model is actually generated or
+ * downloaded — so loading this worker (smoke-test ping, online title path)
+ * never triggers the transformers resolve/install dance.
+ */
+function getTransformersVersionSpec(): string {
+	cachedTransformersVersionSpec ??= resolveTransformersVersionSpec();
+	return cachedTransformersVersionSpec;
+}
+function getTransformersRuntimeKey(): string {
+	return getTransformersVersionSpec().replace(/[^A-Za-z0-9._-]/g, "_");
+}
+let generateQueue = Promise.resolve();
+let transformersRuntime: Promise<TransformersRuntime> | null = null;
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}
+
+function isErrnoCode(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function sendLog(
+	transport: TinyTitleTransport,
+	level: "debug" | "warn" | "error",
+	msg: string,
+	meta?: Record<string, unknown>,
+): void {
+	transport.send({ type: "log", level, msg, meta });
+}
+
+function getTinyTitleRuntimeDir(): string {
+	return path.join(
+		path.dirname(getTinyModelsCacheDir()),
+		"tiny-title-runtime",
+		`transformers-${getTransformersRuntimeKey()}`,
+	);
+}
+
+async function acquireInstallLock(runtimeDir: string): Promise<() => Promise<void>> {
+	const lockDir = `${runtimeDir}.lock`;
+	for (let attempt = 0; attempt < INSTALL_LOCK_ATTEMPTS; attempt++) {
+		try {
+			await fs.mkdir(lockDir);
+			return async () => {
+				await fs.rm(lockDir, { recursive: true, force: true });
+			};
+		} catch (error) {
+			if (!isErrnoCode(error, "EEXIST")) throw error;
+			await Bun.sleep(INSTALL_LOCK_SLEEP_MS);
+		}
+	}
+	throw new Error(`Timed out waiting for tiny title runtime install lock: ${lockDir}`);
+}
+
+async function isCompiledRuntimeInstalled(runtimeDir: string): Promise<boolean> {
+	return Bun.file(path.join(runtimeDir, "node_modules", "@huggingface", "transformers", "package.json")).exists();
+}
+
+async function writeRuntimeManifest(runtimeDir: string): Promise<void> {
+	await fs.mkdir(runtimeDir, { recursive: true });
+	await Bun.write(
+		path.join(runtimeDir, "package.json"),
+		`${JSON.stringify(
+			{
+				private: true,
+				type: "module",
+				dependencies: {
+					[TRANSFORMERS_PACKAGE]: getTransformersVersionSpec(),
+				},
+				trustedDependencies: ["onnxruntime-node"],
+			},
+			null,
+			"\t",
+		)}\n`,
+	);
+}
+
+async function readPipe(stream: ReadableStream<Uint8Array> | null): Promise<string> {
+	if (!stream) return "";
+	return new Response(stream).text();
+}
+
+async function runRuntimeInstall(runtimeDir: string): Promise<void> {
+	const proc = Bun.spawn([process.execPath, "install", "--cwd", runtimeDir, "--production"], {
+		env: { ...Bun.env, BUN_BE_BUN: "1" },
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [stdout, stderr, exitCode] = await Promise.all([
+		readPipe(proc.stdout as ReadableStream<Uint8Array> | null),
+		readPipe(proc.stderr as ReadableStream<Uint8Array> | null),
+		proc.exited,
+	]);
+	if (exitCode === 0) return;
+	const output = `${stdout}\n${stderr}`.trim();
+	throw new Error(
+		`Failed to install tiny title runtime with ${process.execPath} install (exit ${exitCode}): ${output}`,
+	);
+}
+
+function sendRuntimeInstallProgress(
+	transport: TinyTitleTransport,
+	requestId: string,
+	modelKey: TinyLocalModelKey,
+	status: "initiate" | "download" | "done",
+): void {
+	transport.send({
+		type: "progress",
+		id: requestId,
+		event: {
+			modelKey,
+			status,
+			name: `${TRANSFORMERS_PACKAGE}@${getTransformersVersionSpec()}`,
+		},
+	});
+}
+
+async function ensureCompiledTransformersRuntime(
+	transport: TinyTitleTransport,
+	requestId: string,
+	modelKey: TinyLocalModelKey,
+): Promise<string> {
+	const runtimeDir = getTinyTitleRuntimeDir();
+	if (await isCompiledRuntimeInstalled(runtimeDir)) return runtimeDir;
+
+	sendRuntimeInstallProgress(transport, requestId, modelKey, "initiate");
+	const releaseLock = await acquireInstallLock(runtimeDir);
+	try {
+		if (await isCompiledRuntimeInstalled(runtimeDir)) return runtimeDir;
+		await writeRuntimeManifest(runtimeDir);
+		sendRuntimeInstallProgress(transport, requestId, modelKey, "download");
+		await runRuntimeInstall(runtimeDir);
+		sendRuntimeInstallProgress(transport, requestId, modelKey, "done");
+		return runtimeDir;
+	} finally {
+		await releaseLock();
+	}
+}
+
+function configureTransformers(transformers: TransformersRuntime): TransformersRuntime {
+	transformers.env.cacheDir = getTinyModelsCacheDir();
+	transformers.env.allowLocalModels = false;
+	transformers.env.logLevel = transformers.LogLevel.ERROR;
+	return transformers;
+}
+
+async function loadTransformers(
+	transport: TinyTitleTransport,
+	requestId: string,
+	modelKey: TinyLocalModelKey,
+): Promise<TransformersRuntime> {
+	if (transformersRuntime) return transformersRuntime;
+	transformersRuntime = (async () => {
+		if (!isCompiledBinary()) return configureTransformers(sourceRequire(TRANSFORMERS_PACKAGE) as TransformersRuntime);
+		const runtimeDir = await ensureCompiledTransformersRuntime(transport, requestId, modelKey);
+		const require_ = createRequire(path.join(runtimeDir, "package.json"));
+		return configureTransformers(require_(TRANSFORMERS_PACKAGE) as TransformersRuntime);
+	})().catch(error => {
+		transformersRuntime = null;
+		throw error;
+	});
+	return transformersRuntime;
+}
+
+function createStopOnTextCriteria(
+	transformers: TransformersRuntime,
+	tokenizer: TextGenerationPipeline["tokenizer"],
+	text: string,
+): TransformersStoppingCriteria {
+	class StopOnTextCriteria extends transformers.StoppingCriteria {
+		#tokenizer: TextGenerationPipeline["tokenizer"];
+		#text: string;
+
+		constructor() {
+			super();
+			this.#tokenizer = tokenizer;
+			this.#text = text;
+		}
+
+		_call(inputIds: number[][]): boolean[] {
+			return inputIds.map(ids => {
+				const tail = ids.slice(-STOP_DECODE_WINDOW_TOKENS);
+				const decoded = this.#tokenizer.decode(tail, {
+					skip_special_tokens: false,
+					clean_up_tokenization_spaces: false,
+				});
+				return decoded.includes(this.#text);
+			});
+		}
+	}
+	return new StopOnTextCriteria();
+}
+
+function toProgressEvent(modelKey: TinyLocalModelKey, info: ProgressInfo): TinyTitleProgressEvent {
+	if (info.status === "ready") {
+		return { modelKey, status: info.status, task: info.task, model: info.model };
+	}
+	if (info.status === "progress_total") {
+		return {
+			modelKey,
+			status: info.status,
+			name: info.name,
+			progress: info.progress,
+			loaded: info.loaded,
+			total: info.total,
+			files: info.files,
+		};
+	}
+	if (info.status === "progress") {
+		return {
+			modelKey,
+			status: info.status,
+			name: info.name,
+			file: info.file,
+			progress: info.progress,
+			loaded: info.loaded,
+			total: info.total,
+		};
+	}
+	return { modelKey, status: info.status, name: info.name, file: info.file };
+}
+
+function sendProgress(
+	transport: TinyTitleTransport,
+	id: string,
+	modelKey: TinyLocalModelKey,
+	info: ProgressInfo,
+): void {
+	transport.send({ type: "progress", id, event: toProgressEvent(modelKey, info) });
+}
+
+async function loadPipeline(
+	modelKey: TinyLocalModelKey,
+	transport: TinyTitleTransport,
+	requestId: string,
+): Promise<TextGenerationPipeline> {
+	const spec = getTinyLocalModelSpec(modelKey);
+	if (!spec) throw new Error(`Unknown tiny local model: ${modelKey}`);
+	const cached = pipelines.get(modelKey);
+	if (cached) {
+		void cached
+			.then(() => {
+				transport.send({
+					type: "progress",
+					id: requestId,
+					event: { modelKey, status: "ready", task: "text-generation", model: spec.repo },
+				});
+			})
+			.catch(() => undefined);
+		return cached;
+	}
+
+	const transformers = await loadTransformers(transport, requestId, modelKey);
+	const startedAt = performance.now();
+	const loaded = transformers
+		.pipeline("text-generation", spec.repo, {
+			device: "cpu",
+			dtype: spec.dtype,
+			progress_callback: info => sendProgress(transport, requestId, modelKey, info),
+		})
+		.then(
+			generator => {
+				sendLog(transport, "debug", "tiny-model: local model loaded", {
+					modelKey,
+					repo: spec.repo,
+					elapsedMs: Math.round(performance.now() - startedAt),
+				});
+				transport.send({
+					type: "progress",
+					id: requestId,
+					event: { modelKey, status: "ready", task: "text-generation", model: spec.repo },
+				});
+				return generator;
+			},
+			error => {
+				pipelines.delete(modelKey);
+				throw error;
+			},
+		);
+	pipelines.set(modelKey, loaded);
+	return loaded;
+}
+
+function buildPrompt(generator: TextGenerationPipeline, message: string): string {
+	const chat = [
+		{ role: "system", content: TINY_TITLE_SYSTEM_PROMPT },
+		{ role: "user", content: formatTitleUserMessage(message) },
+	];
+	const chatTemplateOptions = {
+		add_generation_prompt: true,
+		tokenize: false,
+		enable_thinking: false,
+	};
+	return `${generator.tokenizer.apply_chat_template(chat, chatTemplateOptions)}${TITLE_PREFILL}`;
+}
+
+function extractTinyTitle(text: string): string | null {
+	const titleStart = text.lastIndexOf(TITLE_PREFILL);
+	const withoutPrefix = titleStart >= 0 ? text.slice(titleStart + TITLE_PREFILL.length) : text;
+	const closeIndex = withoutPrefix.indexOf(TITLE_CLOSE);
+	const withoutClose = closeIndex >= 0 ? withoutPrefix.slice(0, closeIndex) : withoutPrefix;
+	const tagIndex = withoutClose.indexOf("<");
+	const withoutTag = tagIndex >= 0 ? withoutClose.slice(0, tagIndex) : withoutClose;
+	return normalizeGeneratedTitle(withoutTag);
+}
+
+async function generateTitle(
+	transport: TinyTitleTransport,
+	requestId: string,
+	modelKey: TinyTitleLocalModelKey,
+	message: string,
+): Promise<string | null> {
+	const generator = await loadPipeline(modelKey, transport, requestId);
+	const promptText = buildPrompt(generator, message);
+	const transformers = await loadTransformers(transport, requestId, modelKey);
+	const output = (await generator(promptText, {
+		max_new_tokens: TITLE_MAX_NEW_TOKENS,
+		do_sample: false,
+		return_full_text: false,
+		stopping_criteria: createStopOnTextCriteria(transformers, generator.tokenizer, TITLE_CLOSE),
+	})) as TextGenerationStringOutput;
+	return extractTinyTitle(output[0]?.generated_text ?? "");
+}
+
+function buildCompletionPrompt(generator: TextGenerationPipeline, promptText: string): string {
+	const chat = [{ role: "user", content: promptText }];
+	const chatTemplateOptions = {
+		add_generation_prompt: true,
+		tokenize: false,
+		enable_thinking: false,
+	};
+	return `${generator.tokenizer.apply_chat_template(chat, chatTemplateOptions)}`;
+}
+
+/**
+ * Generic single-turn completion used by Mnemosyne memory tasks (fact extraction
+ * and consolidation). The caller (Mnemosyne) supplies the full task prompt; we
+ * wrap it as the user turn, decode greedily, and return the raw text for the
+ * caller's own parser. Output is capped to keep CPU latency bounded.
+ */
+async function generateCompletion(
+	transport: TinyTitleTransport,
+	requestId: string,
+	modelKey: TinyLocalModelKey,
+	promptText: string,
+	maxTokens: number | undefined,
+): Promise<string | null> {
+	const generator = await loadPipeline(modelKey, transport, requestId);
+	const text = buildCompletionPrompt(generator, promptText);
+	const requested = maxTokens ?? MEMORY_COMPLETION_MAX_NEW_TOKENS;
+	const maxNewTokens = Math.min(Math.max(1, requested), MEMORY_COMPLETION_MAX_NEW_TOKENS);
+	const output = (await generator(text, {
+		max_new_tokens: maxNewTokens,
+		do_sample: false,
+		return_full_text: false,
+	})) as TextGenerationStringOutput;
+	const generated = (output[0]?.generated_text ?? "").trim();
+	return generated === "" ? null : generated;
+}
+
+function releasePipelines(): void {
+	// Intentionally NOT calling `pipeline.dispose()`. transformers.js disposes the
+	// underlying onnxruntime InferenceSession, freeing native memory that Bun's
+	// worker/NAPI teardown then frees a second time — a double-free that aborts the
+	// process on quit ("malloc: pointer being freed was not allocated" /
+	// "NAPI FATAL ERROR"). The worker is torn down immediately after `close`, so the
+	// OS reclaims the model memory regardless; skipping dispose avoids the crash.
+	pipelines.clear();
+}
+
+function enqueueRequest(
+	transport: TinyTitleTransport,
+	request: Extract<TinyTitleWorkerInbound, { type: "generate" | "complete" | "download" }>,
+): void {
+	generateQueue = generateQueue.then(
+		async () => {
+			await handleQueuedRequest(transport, request);
+		},
+		async () => {
+			await handleQueuedRequest(transport, request);
+		},
+	);
+}
+
+async function handleQueuedRequest(
+	transport: TinyTitleTransport,
+	request: Extract<TinyTitleWorkerInbound, { type: "generate" | "complete" | "download" }>,
+): Promise<void> {
+	try {
+		if (request.type === "download") {
+			await loadPipeline(request.modelKey, transport, request.id);
+			transport.send({ type: "downloaded", id: request.id });
+			return;
+		}
+		if (request.type === "complete") {
+			const text = await generateCompletion(
+				transport,
+				request.id,
+				request.modelKey,
+				request.prompt,
+				request.maxTokens,
+			);
+			transport.send({ type: "completion", id: request.id, text });
+			return;
+		}
+		const title = await generateTitle(transport, request.id, request.modelKey, request.message);
+		transport.send({ type: "title", id: request.id, title });
+	} catch (error) {
+		transport.send({ type: "error", id: request.id, error: errorText(error) });
+	}
+}
+
+export function startTinyTitleWorker(transport: TinyTitleTransport): void {
+	transport.onMessage(message => {
+		if (message.type === "ping") {
+			transport.send({ type: "pong", id: message.id });
+			return;
+		}
+		if (message.type === "close") {
+			releasePipelines();
+			transport.send({ type: "closed" });
+			transport.close();
+			return;
+		}
+		enqueueRequest(transport, message);
+	});
+}
+
+if (!parentPort) throw new Error("tiny-title-worker: missing parentPort");
+
+const port = parentPort;
+const transport: TinyTitleTransport = {
+	send: (message: TinyTitleWorkerOutbound) => port.postMessage(message),
+	onMessage: handler => {
+		const wrap = (data: unknown): void => handler(data as TinyTitleWorkerInbound);
+		port.on("message", wrap);
+		return () => port.off("message", wrap);
+	},
+	close: () => {
+		try {
+			port.close();
+		} catch {
+			// Already closed.
+		}
+	},
+};
+
+startTinyTitleWorker(transport);

package/src/tools/bash.ts

@@ -129,6 +129,8 @@ export interface BashToolDetails {
 	timeoutSeconds?: number;
 	requestedTimeoutSeconds?: number;
 	wallTimeMs?: number;
+	/** Exit code of a command that ran to completion but failed (non-zero). */
+	exitCode?: number;
 	terminalId?: string;
 	async?: {
 		state: "running" | "completed" | "failed";
@@ -281,17 +283,19 @@ function formatWallTimeNotice(wallTimeMs: number): string {
 	return `Wall time: ${formatWallTimeSeconds(wallTimeMs)} seconds`;
 }
 
+function formatExitCodeNotice(exitCode: number): string {
+	return `Command exited with code ${exitCode}`;
+}
+
 /**
- * Strip the trailing `Wall time: <secs> seconds` notice from text so the TUI
- * can render the wall time via its styled `[Wall: …]` label without echoing
- * the same value verbatim in the output pane.
+ * Strip the trailing occurrence of `notice` (plus a single surrounding newline
+ * on each side) so the TUI can echo the value via a styled footer label
+ * instead of repeating it verbatim in the output pane. The notice is
+ * reconstructed from the same value the result was tagged with, so a literal
+ * sub-string match never strips a coincidental in-output token — only the
+ * exact line we appended in #buildCompletedResult.
  */
-function stripWallTimeNotice(text: string, wallTimeMs: number | undefined): string {
-	if (wallTimeMs === undefined) return text;
-	// Reconstruct the notice from the same value the result was tagged with so
-	// a literal sub-string match never strips a coincidental in-output token —
-	// only the exact line we appended in #buildCompletedResult.
-	const notice = formatWallTimeNotice(wallTimeMs);
+function stripTrailingNotice(text: string, notice: string): string {
 	const idx = text.lastIndexOf(notice);
 	if (idx === -1) return text;
 	let start = idx;
@@ -301,6 +305,16 @@ function stripWallTimeNotice(text: string, wallTimeMs: number | undefined): stri
 	return (text.slice(0, start) + text.slice(end)).trimEnd();
 }
 
+function stripWallTimeNotice(text: string, wallTimeMs: number | undefined): string {
+	if (wallTimeMs === undefined) return text;
+	return stripTrailingNotice(text, formatWallTimeNotice(wallTimeMs));
+}
+
+function stripExitCodeNotice(text: string, exitCode: number | undefined): string {
+	if (exitCode === undefined) return text;
+	return stripTrailingNotice(text, formatExitCodeNotice(exitCode));
+}
+
 /**
  * Bash tool implementation.
  *
@@ -357,7 +371,15 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return outputText || "(no output)";
 	}
 
-	#buildResultText(result: BashResult | BashInteractiveResult, timeoutSec: number, outputText: string): string {
+	/**
+	 * Throw for outcomes that are *not* a completed command: user/timeout
+	 * aborts and a missing exit status. The foreground and bridge callers plus
+	 * the async job manager rely on these throwing so cancellations surface as
+	 * aborts and jobs are recorded as failed. A definite non-zero exit is a
+	 * completed command that failed; #buildCompletedResult surfaces it as an
+	 * error *result* (carrying execution details) rather than a throw.
+	 */
+	#throwIfUnfinished(result: BashResult | BashInteractiveResult, timeoutSec: number, outputText: string): void {
 		if (result.cancelled) {
 			throw new ToolError(normalizeResultOutput(result) || "Command aborted");
 		}
@@ -367,10 +389,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (result.exitCode === undefined) {
 			throw new ToolError(`${outputText}\n\nCommand failed: missing exit status`);
 		}
-		if (result.exitCode !== 0) {
-			throw new ToolError(`${outputText}\n\nCommand exited with code ${result.exitCode}`);
-		}
-		return outputText;
 	}
 
 	#buildCompletedResult(
@@ -383,6 +401,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			wallTimeMs?: number;
 		} = {},
 	): AgentToolResult<BashToolDetails> {
+		const exitCode = result.exitCode;
+		const failedExit = exitCode !== undefined && exitCode !== 0;
+
 		const outputLines = [this.#formatResultOutput(result)];
 		const notices: string[] = [];
 		if (options.wallTimeMs !== undefined) {
@@ -394,7 +415,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			}
 		}
 		if (notices.length > 0) outputLines.push("", ...notices);
+		if (failedExit) outputLines.push("", formatExitCodeNotice(exitCode));
 		const outputText = outputLines.join("\n");
+
+		// Aborts / timeouts / missing-status still propagate as thrown errors.
+		this.#throwIfUnfinished(result, timeoutSec, outputText);
+
 		const details: BashToolDetails = { timeoutSeconds: timeoutSec };
 		if (options.requestedTimeoutSec !== undefined && options.requestedTimeoutSec !== timeoutSec) {
 			details.requestedTimeoutSeconds = options.requestedTimeoutSec;
@@ -405,8 +431,11 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (options.wallTimeMs !== undefined) {
 			details.wallTimeMs = options.wallTimeMs;
 		}
+		if (failedExit) {
+			details.exitCode = exitCode;
+		}
 		const resultBuilder = toolResult(details).text(outputText).truncationFromSummary(result, { direction: "tail" });
-		this.#buildResultText(result, timeoutSec, outputText);
+		if (failedExit) resultBuilder.error();
 		return resultBuilder.done();
 	}
 
@@ -500,7 +529,16 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					});
 					const finalText = this.#extractTextResult(finalResult);
 					latestText = finalText;
+					// Hand the detailed result to the foreground auto-background
+					// waiter (which renders it, footer included) before deciding
+					// the job's terminal state.
 					completion.resolve({ kind: "completed", result: finalResult });
+					if (finalResult.isError === true) {
+						// A non-zero exit is a completed command that failed. Re-enter
+						// the failure path so the job manager records it as failed and
+						// delivers the error text, matching prior throw-based behavior.
+						throw new ToolError(finalText);
+					}
 					await reportProgress(finalText, { async: { state: "completed", jobId, type: "bash" } });
 					return finalText;
 				} catch (error) {
@@ -1087,7 +1125,8 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					// double-print it alongside the styled warning line below.
 					const rawOutput = renderContext?.output ?? result.content?.find(c => c.type === "text")?.text ?? "";
 					const strippedOutput = stripOutputNotice(rawOutput, details?.meta);
-					const output = stripWallTimeNotice(strippedOutput, details?.wallTimeMs);
+					const withoutExit = stripExitCodeNotice(strippedOutput, details?.exitCode);
+					const output = stripWallTimeNotice(withoutExit, details?.wallTimeMs);
 					const displayOutput = output.trimEnd();
 					const showingFullOutput = expanded && renderContext?.isFullOutput === true;
 
@@ -1106,6 +1145,9 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 								: `Timeout: ${timeoutSeconds}s`,
 						);
 					}
+					if (isError && typeof details?.exitCode === "number") {
+						statsParts.push(`Exit: ${details.exitCode}`);
+					}
 					const timeoutLine =
 						statsParts.length > 0
 							? uiTheme.fg(

package/src/tools/browser/tab-worker.ts

@@ -917,7 +917,7 @@ export class WorkerCore {
 						dispatchEvent: (event: unknown) => boolean;
 					}
 					const select = el as unknown as SelectLike;
-					if (!select || select.tagName !== "SELECT") throw new Error("tab.select() requires a <select> element");
+					if (select?.tagName !== "SELECT") throw new Error("tab.select() requires a <select> element");
 					const EventCtor = (
 						globalThis as unknown as { Event: new (type: string, init?: { bubbles: boolean }) => unknown }
 					).Event;