@oh-my-pi/pi-coding-agent 16.4.6 → 16.5.0

package/src/session/session-context.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "bun:test";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import * as snapcompact from "@oh-my-pi/snapcompact";
 import type { CompactionSummaryMessage } from "./messages";
-import { buildSessionContext } from "./session-context";
+import { buildSessionContext, type StrippedToolCallsMarker } from "./session-context";
 import type { SessionEntry } from "./session-entries";
 
 const timestamp = "2026-07-09T00:00:00.000Z";
@@ -129,12 +129,16 @@ function danglingCallIds(messages: AgentMessage[]): string[] {
 }
 
 describe("buildSessionContext dangling toolCalls", () => {
-	it("strips a dangling toolCall-only assistant turn from the transcript by default", () => {
+	it("strips a dangling toolCall from the transcript but keeps the turn with a stripped marker", () => {
 		const context = buildSessionContext(danglingToolCallEntries, undefined, undefined, { transcript: true });
 
 		expect(danglingCallIds(context.messages)).toEqual([]);
-		// The turn had nothing but the dangling call, so the whole message drops.
-		expect(context.messages.some(message => message.role === "assistant")).toBe(false);
+		// The turn survives (even content-less) carrying the marker so the TUI
+		// renders a placeholder row instead of silently erasing the activity.
+		const assistant = context.messages.find(message => message.role === "assistant");
+		expect(assistant).toBeDefined();
+		expect(assistant?.content).toEqual([]);
+		expect((assistant as AgentMessage & StrippedToolCallsMarker).strippedToolCalls).toBe(1);
 	});
 
 	it("keeps a dangling toolCall in transcript mode with keepDanglingToolCalls", () => {
@@ -146,11 +150,12 @@ describe("buildSessionContext dangling toolCalls", () => {
 		expect(danglingCallIds(context.messages)).toEqual(["call-1"]);
 	});
 
-	it("always strips dangling toolCalls from the LLM context", () => {
+	it("always strips dangling toolCalls from the LLM context and drops the emptied turn", () => {
 		const context = buildSessionContext(danglingToolCallEntries, undefined, undefined, {
 			keepDanglingToolCalls: true,
 		});
 
 		expect(danglingCallIds(context.messages)).toEqual([]);
+		expect(context.messages.some(message => message.role === "assistant")).toBe(false);
 	});
 });

package/src/session/session-context.ts

@@ -131,6 +131,16 @@ export interface BuildSessionContextOptions {
 	keepDanglingToolCalls?: boolean;
 }
 
+/**
+ * Display-only marker set on transcript assistant messages whose dangling
+ * `toolCall` blocks were stripped (no paired result on the resolved path —
+ * failed/retried turns, results on sibling branches). The TUI renders a
+ * placeholder row from it so the turn's activity never silently vanishes.
+ */
+export interface StrippedToolCallsMarker {
+	strippedToolCalls?: number;
+}
+
 /**
  * Build the session context from entries using tree traversal.
  * If leafId is provided, walks from that entry to root.
@@ -353,6 +363,7 @@ export function buildSessionContext(
 						undefined,
 						undefined,
 						snapcompactHistoryBlocksForContext(snapcompactArchive, options),
+						entry.warning,
 					),
 				);
 			} else {
@@ -385,6 +396,7 @@ export function buildSessionContext(
 			providerPayload,
 			undefined,
 			snapcompactHistoryBlocksForContext(snapcompactArchive, options),
+			compaction.warning,
 		);
 		// Agent context (non-transcript): summary first so the LLM sees the
 		// compacted context before recent messages.
@@ -468,10 +480,11 @@ export function buildSessionContext(
 		for (let i = messages.length - 1; i >= 0; i--) {
 			const message = messages[i];
 			if (message.role !== "assistant") continue;
-			const hasDangling = message.content.some(
-				block => block.type === "toolCall" && !pairedToolResultIds.has(block.id),
-			);
-			if (!hasDangling) continue;
+			let strippedToolCalls = 0;
+			for (const block of message.content) {
+				if (block.type === "toolCall" && !pairedToolResultIds.has(block.id)) strippedToolCalls++;
+			}
+			if (strippedToolCalls === 0) continue;
 			const normalized = message.content
 				.filter(
 					block =>
@@ -483,13 +496,17 @@ export function buildSessionContext(
 						? { ...block, thinkingSignature: undefined }
 						: block,
 				);
-			if (normalized.length === 0) {
+			if (normalized.length === 0 && !options?.transcript) {
 				messages.splice(i, 1);
+			} else {
+				const rewritten = { ...message, content: normalized };
 				if (options?.transcript) {
-					cacheMissExplainedAt.splice(i, 1);
+					// Display transcript: keep the turn (even content-less) and mark
+					// how many calls were dropped so the TUI renders a placeholder
+					// row instead of silently erasing the turn's activity.
+					(rewritten as AgentMessage & StrippedToolCallsMarker).strippedToolCalls = strippedToolCalls;
 				}
-			} else {
-				messages[i] = { ...message, content: normalized };
+				messages[i] = rewritten;
 			}
 		}
 	}

package/src/session/session-entries.ts

@@ -92,6 +92,12 @@ export interface CompactionEntry<T = unknown> extends SessionEntryBase {
 	preserveData?: Record<string, unknown>;
 	/** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
 	fromExtension?: boolean;
+	/**
+	 * Dead-end warning from the post-pass progress guard: the pass completed
+	 * but freed too little for maintenance to continue. Rendered on the
+	 * compaction divider.
+	 */
+	warning?: string;
 }
 
 export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {

package/src/slash-commands/builtin-registry.ts

@@ -6,6 +6,7 @@ import { type AutocompleteItem, Spacer } from "@oh-my-pi/pi-tui";
 import { APP_NAME, getProjectDir, setProjectDir } from "@oh-my-pi/pi-utils";
 import { COLLAB_GUEST_ALLOWED_COMMANDS, CollabGuestLink } from "../collab/guest";
 import { CollabHost } from "../collab/host";
+import { expandRoleAlias, getModelMatchPreferences, resolveCliModel } from "../config/model-resolver";
 import { applyProviderGlobalsFromSettings } from "../config/provider-globals";
 import type { SettingPath, SettingValue } from "../config/settings";
 import { settings } from "../config/settings";
@@ -460,6 +461,30 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "prewalk",
+		description: "Switch to a fast/cheap model at the next action (works even without --prewalk)",
+		acpDescription: "Prewalk at the next action",
+		handle: async (_command, runtime) => {
+			const rolePattern = expandRoleAlias("@smol", runtime.settings);
+			const resolved = resolveCliModel({
+				cliModel: rolePattern,
+				modelRegistry: runtime.session.modelRegistry,
+				preferences: getModelMatchPreferences(runtime.settings),
+			});
+			if (resolved.error || !resolved.model) {
+				return usage(resolved.error ?? `Model "${rolePattern}" not found`, runtime);
+			}
+			if (!runtime.session.modelRegistry.hasConfiguredAuth(resolved.model)) {
+				return usage(`No API key for ${resolved.model.provider}/${resolved.model.id}`, runtime);
+			}
+			runtime.session.armPrewalk(resolved.model, resolved.thinkingLevel);
+			await runtime.output(
+				`Prewalk on: switching to ${resolved.model.provider}/${resolved.model.id} at the next edit/write (todo-gated).`,
+			);
+			return commandConsumed();
+		},
+	},
 	{
 		name: "advisor",
 		description: "Toggle the advisor (a second model that reviews each turn and injects notes)",

package/src/task/agents.ts

@@ -50,7 +50,7 @@ const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
 			name: "task",
 			description: "General-purpose subagent with full capabilities for delegated multi-step tasks",
 			spawns: "*",
-			model: "pi/task",
+			model: "@task",
 			thinkingLevel: AUTO_THINKING,
 		},
 		template: taskMd,
@@ -60,7 +60,7 @@ const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
 		frontmatter: {
 			name: "sonic",
 			description: "Low-reasoning agent for strictly mechanical updates or data collection only",
-			model: "pi/smol",
+			model: "@smol",
 			thinkingLevel: Effort.Medium,
 		},
 		template: taskMd,

package/src/thinking.ts

@@ -62,18 +62,25 @@ const THINKING_LEVEL_BY_SELECTOR: Readonly<Record<string, ThinkingLevel>> = {
 };
 
 function getOwnSelector<T>(selectors: Readonly<Record<string, T>>, value: string | null | undefined): T | undefined {
-	return value === undefined || value === null || !Object.hasOwn(selectors, value) ? undefined : selectors[value];
+	if (value === undefined || value === null) return undefined;
+	if (Object.hasOwn(selectors, value)) return selectors[value];
+	// Accept unambiguous abbreviations (`xhi` → xhigh, `med` → medium) so every
+	// selector surface (`--thinking`, `:suffix`, role values) parses alike.
+	// Two-character minimum keeps single letters (`m`) from guessing.
+	if (value.length < 2) return undefined;
+	const matches = Object.keys(selectors).filter(selector => selector.startsWith(value));
+	return matches.length === 1 ? selectors[matches[0]] : undefined;
 }
 
 /**
- * Parses a provider-facing effort value.
+ * Parses a provider-facing effort value. Accepts unambiguous abbreviations.
  */
 export function parseEffort(value: string | null | undefined): Effort | undefined {
 	return getOwnSelector(EFFORT_BY_SELECTOR, value);
 }
 
 /**
- * Parses an agent-local thinking selector.
+ * Parses an agent-local thinking selector. Accepts unambiguous abbreviations.
  */
 export function parseThinkingLevel(value: string | null | undefined): ThinkingLevel | undefined {
 	return getOwnSelector(THINKING_LEVEL_BY_SELECTOR, value);

package/src/tiny/models.ts

@@ -1,4 +1,4 @@
-/** Default session-title model: the online pi/smol path (no local download / on-device inference). */
+/** Default session-title model: the online @smol path (no local download / on-device inference). */
 export const ONLINE_TINY_TITLE_MODEL_KEY = "online";
 /** Local model the `tiny-models` CLI downloads when none is named. Not the session-title default — that is {@link ONLINE_TINY_TITLE_MODEL_KEY}. */
 export const DEFAULT_TINY_TITLE_LOCAL_MODEL_KEY = "lfm2-700m";
@@ -87,9 +87,9 @@ void TINY_TITLE_MODEL_VALUES_MATCH_REGISTRY;
 export const TINY_TITLE_MODEL_OPTIONS = [
 	{
 		value: ONLINE_TINY_TITLE_MODEL_KEY,
-		label: "Online (TINY role, else pi/smol)",
+		label: "Online (TINY role, else @smol)",
 		description:
-			"Online title generation: the TINY model role (set one in /models) when assigned, otherwise the online fallback (commit role, then pi/smol). No local download or on-device inference.",
+			"Online title generation: the TINY model role (set one in /models) when assigned, otherwise the online fallback (commit role, then @smol). No local download or on-device inference.",
 	},
 	...TINY_TITLE_LOCAL_MODELS.map(model => ({
 		value: model.key,
@@ -194,9 +194,9 @@ void TINY_MEMORY_MODEL_VALUES_MATCH_REGISTRY;
 export const TINY_MEMORY_MODEL_OPTIONS = [
 	{
 		value: ONLINE_MEMORY_MODEL_KEY,
-		label: "Online (TINY role, else smol)",
+		label: "Online (TINY role, else @smol)",
 		description:
-			"Use the online model: the TINY role from /models when set, otherwise pi/smol. No local model download or on-device inference.",
+			"Use the online model: the TINY role from /models when set, otherwise @smol. No local model download or on-device inference.",
 	},
 	...TINY_MEMORY_LOCAL_MODELS.map(model => ({
 		value: model.key,
@@ -256,9 +256,9 @@ export type AutoThinkingModelKey = TinyMemoryModelKey;
 export const AUTO_THINKING_MODEL_OPTIONS = [
 	{
 		value: ONLINE_AUTO_THINKING_MODEL_KEY,
-		label: "Online (TINY role, else smol)",
+		label: "Online (TINY role, else @smol)",
 		description:
-			"Classify prompt difficulty online with the TINY role model (set one in /models) or pi/smol; no local download or on-device inference.",
+			"Classify prompt difficulty online with the TINY role model (set one in /models) or @smol; no local download or on-device inference.",
 	},
 	...TINY_MEMORY_LOCAL_MODELS.map(model => ({
 		value: model.key,

package/src/tools/bash-interactive.ts

@@ -19,6 +19,7 @@ import { OutputSink, type OutputSummary } from "../session/streaming-output";
 import { sanitizeWithOptionalSixelPassthrough } from "../utils/sixel";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "./output-meta";
 import { formatStatusIcon, replaceTabs } from "./render-utils";
+import { readTerminalRows, styleTerminalRow } from "./terminal-output";
 
 export interface BashInteractiveResult extends OutputSummary {
 	exitCode: number | undefined;
@@ -225,14 +226,10 @@ class BashInteractiveOverlayComponent implements Component {
 
 	#readViewport(innerWidth: number, maxContentRows: number): string[] {
 		this.#terminal.resize(innerWidth, maxContentRows);
-		const buffer = this.#terminal.buffer.active;
-		const viewportY = buffer.viewportY;
-		const visibleLines: string[] = [];
-		for (let i = 0; i < maxContentRows; i++) {
-			const line = buffer.getLine(viewportY + i)?.translateToString(true) ?? "";
-			visibleLines.push(truncateToWidth(replaceTabs(sanitizeText(line)), innerWidth));
-		}
-		return visibleLines;
+		const viewportY = this.#terminal.buffer.active.viewportY;
+		return readTerminalRows(this.#terminal, viewportY, maxContentRows).map(line =>
+			truncateToWidth(styleTerminalRow(line, this.uiTheme.getFgAnsi("toolOutput")), innerWidth),
+		);
 	}
 	render(width: number): readonly string[] {
 		const safeWidth = Math.max(20, width);

package/src/tools/bash.ts

@@ -36,12 +36,18 @@ import {
 	stripRawOutputArtifactNotice,
 } from "./output-meta";
 import { resolveToCwd } from "./path-utils";
-import { capPreviewLines, formatToolWorkingDirectory, previewWindowRows, replaceTabs } from "./render-utils";
+import {
+	capPreviewLines,
+	DEFAULT_TERMINAL_PREVIEW_LINES,
+	formatToolWorkingDirectory,
+	previewWindowRows,
+	replaceTabs,
+} from "./render-utils";
 import { ToolAbortError, ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 import { clampTimeout, TOOL_TIMEOUTS } from "./tool-timeouts";
 
-export const BASH_DEFAULT_PREVIEW_LINES = 10;
+export const BASH_DEFAULT_PREVIEW_LINES = DEFAULT_TERMINAL_PREVIEW_LINES;
 
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS = 60_000;
@@ -193,10 +199,9 @@ type ManagedBashJobCompletion =
 
 interface ManagedBashJobHandle {
 	jobId: string;
-	label: string;
 	completion: Promise<ManagedBashJobCompletion>;
 	getLatestText: () => string;
-	setBackgrounded: (backgrounded: boolean) => void;
+	stopUpdates: () => void;
 }
 
 function normalizeResultOutput(result: BashResult | BashInteractiveResult): string {
@@ -327,6 +332,10 @@ function formatExitCodeNotice(exitCode: number): string {
 	return `Command exited with code ${exitCode}`;
 }
 
+function formatBackgroundNotice(jobId: string): string {
+	return `Backgrounded as job ${jobId}; result will be delivered automatically.`;
+}
+
 /**
  * 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
@@ -355,6 +364,11 @@ function stripExitCodeNotice(text: string, exitCode: number | undefined): string
 	return stripTrailingNotice(text, formatExitCodeNotice(exitCode));
 }
 
+function stripBackgroundNotice(text: string, async: BashToolDetails["async"] | undefined): string {
+	if (async?.state !== "running") return text;
+	return stripTrailingNotice(text, formatBackgroundNotice(async.jobId));
+}
+
 /**
  * Bash tool implementation.
  *
@@ -389,6 +403,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 			hasGrep: isToolActive("grep", this.session.settings.get("grep.enabled")),
 			hasGlob: isToolActive("glob", this.session.settings.get("glob.enabled")),
 			hasRead: isToolActive("read", true),
+			hasLaunch: isToolActive("launch", this.session.settings.get("launch.enabled")),
 			hasEval: isToolActive(
 				"eval",
 				evalBackends.python || evalBackends.js || evalBackends.ruby || evalBackends.julia,
@@ -518,7 +533,6 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 	#buildBackgroundStartResult(
 		jobId: string,
-		label: string,
 		previewText: string,
 		timeoutSec: number | undefined,
 		options: { requestedTimeoutSec?: number; notices?: readonly string[] } = {},
@@ -542,11 +556,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		if (options.notices?.length) {
 			lines.push(...options.notices, "");
 		}
-		lines.push(`Background job ${jobId} started: ${label}`);
-		lines.push("Result will be delivered automatically when complete.");
-		lines.push(
-			`You can use \`job\` to poll until complete, but prefer to continue with another task in the meanwhile if it's not blocking.`,
-		);
+		lines.push(formatBackgroundNotice(jobId));
 		return {
 			content: [{ type: "text", text: lines.join("\n") }],
 			details,
@@ -567,7 +577,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 		resolvedEnv?: Record<string, string>;
 		onUpdate?: AgentToolUpdateCallback<BashToolDetails>;
-		startBackgrounded: boolean;
+		forwardUpdates: boolean;
 	}): ManagedBashJobHandle {
 		const manager = this.session.asyncJobManager;
 		if (!manager) {
@@ -576,7 +586,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 		const label = options.command.length > 120 ? `${options.command.slice(0, 117)}...` : options.command;
 		let latestText = "";
-		let backgrounded = options.startBackgrounded;
+		let forwardUpdates = options.forwardUpdates;
 		const completion = Promise.withResolvers<ManagedBashJobCompletion>();
 
 		const jobId = manager.register(
@@ -632,11 +642,12 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 			},
 			{
 				ownerId: this.session.getAgentId?.() ?? undefined,
-				onProgress: async (text, details) => {
+				onProgress: async text => {
 					latestText = text;
+					if (!forwardUpdates) return;
 					await options.onUpdate?.({
 						content: [{ type: "text", text }],
-						details: backgrounded ? ((details ?? {}) as BashToolDetails) : {},
+						details: {},
 					});
 				},
 			},
@@ -644,11 +655,10 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 		return {
 			jobId,
-			label,
 			completion: completion.promise,
 			getLatestText: () => latestText,
-			setBackgrounded: (nextBackgrounded: boolean) => {
-				backgrounded = nextBackgrounded;
+			stopUpdates: () => {
+				forwardUpdates = false;
 			},
 		};
 	}
@@ -813,9 +823,9 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 				resolvedEnv,
 				onUpdate,
-				startBackgrounded: true,
+				forwardUpdates: false,
 			});
-			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
+			return this.#buildBackgroundStartResult(job.jobId, "", timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
 			});
@@ -851,10 +861,10 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 				resolvedEnv,
 				onUpdate,
-				startBackgrounded,
+				forwardUpdates: !startBackgrounded,
 			});
 			if (startBackgrounded) {
-				return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
+				return this.#buildBackgroundStartResult(job.jobId, "", timeoutSec, {
 					requestedTimeoutSec,
 					notices: pendingNotices,
 				});
@@ -874,9 +884,9 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 				autoBgManager.cancel(job.jobId);
 				throw new ToolAbortError(job.getLatestText() || "Command aborted");
 			}
-			job.setBackgrounded(true);
+			job.stopUpdates();
 			autoBgManager.resumeDeliveries([job.jobId]);
-			return this.#buildBackgroundStartResult(job.jobId, job.label, job.getLatestText(), timeoutSec, {
+			return this.#buildBackgroundStartResult(job.jobId, job.getLatestText(), timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
 			});
@@ -1303,7 +1313,8 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					) {
 						return cachedLines;
 					}
-					const strippedOutput = stripOutputNotice(rawOutput, details?.meta);
+					const withoutBackground = stripBackgroundNotice(rawOutput, details?.async);
+					const strippedOutput = stripOutputNotice(withoutBackground, details?.meta);
 					const withoutExit = stripExitCodeNotice(strippedOutput, details?.exitCode);
 					const withoutWall = stripWallTimeNotice(withoutExit, details?.wallTimeMs);
 					const rawOutputArtifact = stripRawOutputArtifactNotice(withoutWall);
@@ -1317,6 +1328,9 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					const requestedTimeoutSeconds = details?.requestedTimeoutSeconds;
 					const wallTimeMs = details?.wallTimeMs;
 					const statsParts: string[] = [];
+					if (details?.async?.state === "running") {
+						statsParts.push(`Backgrounded: ${details.async.jobId}`);
+					}
 					if (wallTimeMs !== undefined) {
 						statsParts.push(`Wall: ${formatWallTimeSeconds(wallTimeMs)}s`);
 					}

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

@@ -12,7 +12,12 @@ import { ToolAbortError, ToolError, throwIfAborted } from "../../tool-errors";
 import { type AriaSnapshotOptions, buildAriaSnapshotScript } from "../aria/aria-snapshot";
 import { DEFAULT_VIEWPORT } from "../launch";
 import { extractReadableFromHtml, type ReadableFormat } from "../readable";
-import { bindBrowserRunFacade, waitForBrowserRun } from "../run-cancellation";
+import {
+	bindBrowserRunFacade,
+	resolvePredicateTimeout,
+	type WaitPredicateOptions,
+	waitForBrowserRun,
+} from "../run-cancellation";
 import { cloneSafe, RunOutput } from "../run-output";
 import type { Observation, ReadyInfo, RunResultOk, ScreenshotResult, SessionSnapshot } from "../tab-protocol";
 import {
@@ -1352,7 +1357,17 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 			assert: (cond: unknown, text?: string): void => {
 				if (!cond) throw new ToolError(text ?? "Assertion failed");
 			},
-			wait: (ms: number): Promise<void> => waitForBrowserRun(ms, signal),
+			wait: (msOrPredicate: number | (() => unknown), waitOpts?: WaitPredicateOptions): Promise<unknown> =>
+				waitForBrowserRun(
+					msOrPredicate,
+					signal,
+					typeof msOrPredicate === "number"
+						? waitOpts
+						: {
+								timeout: resolvePredicateTimeout(opts.timeoutMs, waitOpts?.timeout),
+								interval: waitOpts?.interval,
+							},
+				),
 		});
 
 		const hooks: RuntimeHooks = {

package/src/tools/browser/launch.ts

@@ -121,12 +121,16 @@ async function loadBrowsers(): Promise<typeof BrowsersNs> {
 }
 
 /**
- * Lazily download Chromium on first browser launch via @puppeteer/browsers.
- * Skipped when a system Chromium (NixOS) or PUPPETEER_EXECUTABLE_PATH is set.
- * The browser is cached under ~/.omp/puppeteer (getPuppeteerDir).
+ * Resolve the Chromium executable puppeteer will launch, lazily downloading it
+ * on first use via @puppeteer/browsers. Skipped when a system Chromium (NixOS)
+ * or PUPPETEER_EXECUTABLE_PATH is set. The browser is cached under
+ * ~/.omp/puppeteer (getPuppeteerDir). Returns undefined when platform
+ * detection fails (puppeteer default resolution takes over). Exported so
+ * real-browser tests can probe launchability and skip on hosts missing
+ * Chrome's system libraries.
  */
 let chromiumExecutablePromise: Promise<string | undefined> | undefined;
-async function ensureChromiumExecutable(): Promise<string | undefined> {
+export async function ensureChromiumExecutable(): Promise<string | undefined> {
 	const sysChrome = resolveSystemChromium();
 	if (sysChrome) return sysChrome;
 	const envPath = process.env.PUPPETEER_EXECUTABLE_PATH;

package/src/tools/browser/run-cancellation.ts

@@ -1,5 +1,5 @@
 import { untilAborted } from "@oh-my-pi/pi-utils";
-import { throwIfAborted } from "../tool-errors";
+import { ToolError, throwIfAborted } from "../tool-errors";
 
 /**
  * Marks a run-scoped promise as observed without changing its behavior for awaited callers.
@@ -16,12 +16,72 @@ export function markHandled<T>(promise: Promise<T>): Promise<T> {
 	return promise;
 }
 
-/** Sleeps inside evaluated browser code while honoring the owning run's cancellation signal. */
-export function waitForBrowserRun(ms: number, signal: AbortSignal): Promise<void> {
-	const promise = (async (): Promise<void> => {
-		throwIfAborted(signal);
-		await untilAborted(signal, () => Bun.sleep(ms));
+/** Headroom subtracted from the cell budget so an in-run deadline fires before the opaque whole-cell timeout. */
+export const CELL_BUDGET_SLACK_MS = 1_000;
+
+/** Default poll deadline for `wait(predicate)` before clamping to the cell budget. */
+export const DEFAULT_PREDICATE_TIMEOUT_MS = 30_000;
+
+/** Options for the predicate form of the run-scoped `wait()` helper. */
+export interface WaitPredicateOptions {
+	/** Max time to poll before failing, in ms (default 30s, clamped to the cell budget). */
+	timeout?: number;
+	/** Poll interval in ms (default 100, floor 10). */
+	interval?: number;
+}
+
+/**
+ * Effective `wait(predicate)` deadline for a given cell budget. Always strictly below
+ * the cell budget so the named `wait(predicate) timed out` error wins the race against
+ * the opaque whole-cell "Browser code execution timed out". `0`/`Infinity` ("disable")
+ * map to the largest bounded deadline; negative/NaN garbage falls back to the default.
+ */
+export function resolvePredicateTimeout(cellTimeoutMs: number, explicit?: number): number {
+	const budgetBound = Math.max(1, cellTimeoutMs - CELL_BUDGET_SLACK_MS);
+	if (explicit === 0 || explicit === Number.POSITIVE_INFINITY) return budgetBound;
+	if (explicit !== undefined && Number.isFinite(explicit) && explicit > 0) return Math.min(explicit, budgetBound);
+	return Math.min(DEFAULT_PREDICATE_TIMEOUT_MS, budgetBound);
+}
+
+/**
+ * Run-scoped `wait()` helper for evaluated browser code, honoring the owning run's
+ * cancellation signal.
+ *
+ * - `wait(ms)` sleeps for `ms` milliseconds.
+ * - `wait(fn, { timeout?, interval? })` polls `fn` (sync or async) until it returns a
+ *   truthy value and resolves with that value; throws a named `ToolError` on timeout
+ *   instead of stalling into the whole-cell deadline. Predicate errors propagate.
+ */
+export function waitForBrowserRun(
+	msOrPredicate: number | (() => unknown),
+	signal: AbortSignal,
+	opts?: WaitPredicateOptions,
+): Promise<unknown> {
+	const promise = (async (): Promise<unknown> => {
 		throwIfAborted(signal);
+		if (typeof msOrPredicate === "number") {
+			await untilAborted(signal, async () => await Bun.sleep(msOrPredicate));
+			throwIfAborted(signal);
+			return undefined;
+		}
+		if (typeof msOrPredicate !== "function") {
+			throw new ToolError("wait(...) expects milliseconds (number) or a predicate function to poll");
+		}
+		const timeout =
+			opts?.timeout !== undefined && Number.isFinite(opts.timeout) && opts.timeout > 0
+				? opts.timeout
+				: DEFAULT_PREDICATE_TIMEOUT_MS;
+		const interval = Math.max(opts?.interval ?? 100, 10);
+		const deadline = Date.now() + timeout;
+		for (;;) {
+			const value = await untilAborted(signal, async () => await msOrPredicate());
+			throwIfAborted(signal);
+			if (value) return value;
+			if (Date.now() + interval > deadline) {
+				throw new ToolError(`wait(predicate) timed out after ${timeout}ms — predicate never returned truthy`);
+			}
+			await untilAborted(signal, async () => await Bun.sleep(interval));
+		}
 	})();
 	return markHandled(promise);
 }

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

@@ -59,6 +59,12 @@ export type WorkerInitPayload =
 			safeDir: string;
 			targetId: string;
 			dialogs?: "accept" | "dismiss";
+			/**
+			 * Post-timeout recycle: before adopting the page, dismiss any open JS dialog and
+			 * stop a pending navigation so a blocked target cannot stall worker init (which
+			 * previously force-killed the tab). Never set for first-time Electron attach.
+			 */
+			recover?: boolean;
 	  };
 
 export type ToolReply = { ok: true; value: unknown } | { ok: false; error: RunErrorPayload };