@oh-my-pi/pi-coding-agent 16.2.11 → 16.2.12

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

@@ -1,18 +1,19 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { logger, Snowflake } from "@oh-my-pi/pi-utils";
+import { logger, Snowflake, untilAborted } from "@oh-my-pi/pi-utils";
 import { JsRuntime, type RuntimeHooks } from "../../../eval/js/shared/runtime";
 import type { JsDisplayOutput } from "../../../eval/js/shared/types";
 import { callSessionTool } from "../../../eval/js/tool-bridge";
-import type { ToolSession } from "../../../sdk";
 import { resizeImage } from "../../../utils/image-resize";
+import type { ToolSession } from "../../index";
 import { resolveToCwd } from "../../path-utils";
 import { formatScreenshot } from "../../render-utils";
-import { ToolAbortError, ToolError } from "../../tool-errors";
+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 type { Observation, ReadyInfo, RunResultOk, ScreenshotResult, SessionSnapshot } from "../tab-protocol";
 import {
 	type CmuxEvalResult,
@@ -44,7 +45,7 @@ interface RunContext {
 	session: SessionSnapshot;
 	displays: RunResultOk["displays"];
 	screenshots: ScreenshotResult[];
-	signal?: AbortSignal;
+	signal: AbortSignal;
 	timeoutMs: number;
 }
 
@@ -535,9 +536,10 @@ export class CmuxTab {
 
 	async waitForUrl(pattern: string | RegExp, opts?: { timeout?: number }): Promise<string> {
 		const timeoutMs = opts?.timeout ?? this.#runContext?.timeoutMs ?? 30_000;
+		const signal = this.#runContext?.signal;
 		if (typeof pattern === "string") {
-			await this.#request("browser.wait", { url_contains: pattern, timeout_ms: timeoutMs }, timeoutMs);
-			const result = (await this.#request("browser.url.get", {}, timeoutMs)) as CmuxUrlGetResult;
+			await this.#request("browser.wait", { url_contains: pattern, timeout_ms: timeoutMs }, timeoutMs, signal);
+			const result = (await this.#request("browser.url.get", {}, timeoutMs, signal)) as CmuxUrlGetResult;
 			if (typeof result.url === "string" && result.url.length > 0) {
 				this.#lastUrl = result.url;
 			}
@@ -545,29 +547,45 @@ export class CmuxTab {
 		}
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() <= deadline) {
-			const result = (await this.#request("browser.url.get", {}, Math.min(timeoutMs, 5_000))) as CmuxUrlGetResult;
+			const result = (await this.#request(
+				"browser.url.get",
+				{},
+				Math.min(timeoutMs, 5_000),
+				signal,
+			)) as CmuxUrlGetResult;
 			if (typeof result.url === "string" && result.url.length > 0) {
 				this.#lastUrl = result.url;
 				if (pattern.test(result.url)) return result.url;
 			}
-			await Bun.sleep(200);
+			await untilAborted(signal, () => Bun.sleep(200));
 		}
 		throw new ToolError(`tab.waitForUrl() timed out after ${timeoutMs}ms`);
 	}
 
 	async waitForNavigation(opts?: { waitUntil?: WaitUntil; timeout?: number }): Promise<null> {
 		const timeoutMs = opts?.timeout ?? this.#runContext?.timeoutMs ?? 30_000;
+		const signal = this.#runContext?.signal;
 		// Cmux has no native "next navigation" wait — snapshot the current URL via a fresh
 		// `browser.url.get` (never the possibly-stale `#lastUrl`), then poll for a change
 		// from it (mirroring headless `page.waitForNavigation` intent) and optionally settle
 		// on the requested load state. Start it BEFORE the click/submit that navigates; after
 		// a completed nav it times out like puppeteer does.
-		const baseline = (await this.#request("browser.url.get", {}, Math.min(timeoutMs, 5_000))) as CmuxUrlGetResult;
+		const baseline = (await this.#request(
+			"browser.url.get",
+			{},
+			Math.min(timeoutMs, 5_000),
+			signal,
+		)) as CmuxUrlGetResult;
 		const startUrl = typeof baseline.url === "string" && baseline.url.length > 0 ? baseline.url : this.#lastUrl;
 		if (typeof baseline.url === "string" && baseline.url.length > 0) this.#lastUrl = baseline.url;
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() <= deadline) {
-			const result = (await this.#request("browser.url.get", {}, Math.min(timeoutMs, 5_000))) as CmuxUrlGetResult;
+			const result = (await this.#request(
+				"browser.url.get",
+				{},
+				Math.min(timeoutMs, 5_000),
+				signal,
+			)) as CmuxUrlGetResult;
 			if (typeof result.url === "string" && result.url.length > 0) {
 				this.#lastUrl = result.url;
 				if (result.url !== startUrl) {
@@ -576,12 +594,13 @@ export class CmuxTab {
 							"browser.wait",
 							{ load_state: mapWaitUntil(opts.waitUntil), timeout_ms: timeoutMs },
 							timeoutMs,
+							signal,
 						);
 					}
 					return null;
 				}
 			}
-			await Bun.sleep(200);
+			await untilAborted(signal, () => Bun.sleep(200));
 		}
 		throw new ToolError(`tab.waitForNavigation() timed out after ${timeoutMs}ms`);
 	}
@@ -627,6 +646,7 @@ export class CmuxTab {
 		opts?: { timeout?: number },
 	): Promise<CmuxResponse> {
 		const timeoutMs = opts?.timeout ?? this.#runContext?.timeoutMs ?? 30_000;
+		const signal = this.#runContext?.signal;
 		await this.#installResponseObserver();
 		const startId = await this.#responseCursor();
 		const deadline = Date.now() + timeoutMs;
@@ -640,7 +660,7 @@ export class CmuxTab {
 					return response;
 				}
 			}
-			await Bun.sleep(100);
+			await untilAborted(signal, () => Bun.sleep(100));
 		}
 		throw new ToolError(`tab.waitForResponse() timed out after ${timeoutMs}ms`);
 	}
@@ -665,8 +685,14 @@ export class CmuxTab {
 		method: string,
 		params: Record<string, unknown>,
 		timeoutMs?: number,
+		signal: AbortSignal | undefined = this.#runContext?.signal,
 	): Promise<Record<string, unknown>> {
-		return await this.#client.request(method, { surface_id: this.#surfaceId, ...params }, { timeoutMs });
+		throwIfAborted(signal);
+		const result = await untilAborted(signal, () =>
+			this.#client.request(method, { surface_id: this.#surfaceId, ...params }, { timeoutMs }),
+		);
+		throwIfAborted(signal);
+		return result;
 	}
 
 	async #readGeometry(timeoutMs?: number): Promise<CmuxGeometry> {
@@ -717,12 +743,13 @@ export class CmuxTab {
 		...args: unknown[]
 	): Promise<unknown> {
 		const timeoutMs = opts?.timeout ?? this.#runContext?.timeoutMs ?? 30_000;
+		const signal = this.#runContext?.signal;
 		const pollingMs = typeof opts?.polling === "number" ? opts.polling : 200;
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() <= deadline) {
 			const value = typeof fn === "string" ? await this.#evalScript<unknown>(fn) : await this.evaluate(fn, ...args);
 			if (value) return value;
-			await Bun.sleep(pollingMs);
+			await untilAborted(signal, () => Bun.sleep(pollingMs));
 		}
 		throw new ToolError(`page.waitForFunction() timed out after ${timeoutMs}ms`);
 	}
@@ -863,16 +890,17 @@ export class CmuxTab {
 	}
 
 	async #waitForSelector(selector: string, timeoutMs: number): Promise<void> {
+		const signal = this.#runContext?.signal;
 		const spec = this.#selectorSpec(selector);
 		const nativeSelector = this.#nativeSelector(spec);
 		if (nativeSelector) {
-			await this.#request("browser.wait", { selector: nativeSelector, timeout_ms: timeoutMs }, timeoutMs);
+			await this.#request("browser.wait", { selector: nativeSelector, timeout_ms: timeoutMs }, timeoutMs, signal);
 			return;
 		}
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() <= deadline) {
 			if (await this.#selectorExists(spec)) return;
-			await Bun.sleep(100);
+			await untilAborted(signal, () => Bun.sleep(100));
 		}
 		throw new ToolError(`tab.waitFor(${JSON.stringify(selector)}) timed out after ${timeoutMs}ms`);
 	}
@@ -1251,22 +1279,26 @@ class CmuxBrowserFacade {
 }
 
 export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promise<RunResultOk> {
+	const runAc = new AbortController();
 	const timeoutSignal = AbortSignal.timeout(opts.timeoutMs);
-	const signal = opts.signal ? AbortSignal.any([timeoutSignal, opts.signal]) : timeoutSignal;
+	const signal = AbortSignal.any(
+		opts.signal ? [timeoutSignal, opts.signal, runAc.signal] : [timeoutSignal, runAc.signal],
+	);
 	const displays: RunResultOk["displays"] = [];
 	const screenshots: ScreenshotResult[] = [];
 	const runId = crypto.randomUUID();
 	tab.setRunContext({ session: opts.snapshot, displays, screenshots, signal, timeoutMs: opts.timeoutMs });
 	const runtime = tab.ensureRuntime(opts.snapshot);
 	runtime.setCwd(opts.snapshot.cwd);
+	const runTab = bindBrowserRunFacade(tab, signal);
 	runtime.setRunScope({
-		page: tab.page,
-		browser: tab.browser,
-		tab,
+		page: bindBrowserRunFacade(tab.page, signal),
+		browser: bindBrowserRunFacade(tab.browser, signal),
+		tab: runTab,
 		assert: (cond: unknown, text?: string): void => {
 			if (!cond) throw new ToolError(text ?? "Assertion failed");
 		},
-		wait: (ms: number): Promise<void> => Bun.sleep(ms),
+		wait: (ms: number): Promise<void> => waitForBrowserRun(ms, signal),
 	});
 
 	const { promise: cancelRejection, reject } = Promise.withResolvers<never>();
@@ -1282,9 +1314,18 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 
 	try {
 		const hooks: RuntimeHooks = {
-			onText: chunk => logger.debug(chunk.replace(/\n$/, "")),
-			onDisplay: output => pushDisplay(displays, output),
-			callTool: (name, args) => callSessionTool(name, args, { session: opts.session, signal }),
+			onText: chunk => {
+				throwIfAborted(signal);
+				logger.debug(chunk.replace(/\n$/, ""));
+			},
+			onDisplay: output => {
+				throwIfAborted(signal);
+				pushDisplay(displays, output);
+			},
+			callTool: (name, args) => {
+				throwIfAborted(signal);
+				return callSessionTool(name, args, { session: opts.session, signal });
+			},
 		};
 		// Like the inline worker fallback, cmux runs user JS in-process: awaited cmux/tool calls
 		// observe this abort signal, but a synchronous infinite loop cannot be interrupted here.
@@ -1295,6 +1336,7 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 		return { displays, returnValue: cloneSafe(returnValue), screenshots };
 	} finally {
 		signal.removeEventListener("abort", onAbort);
+		runAc.abort(new ToolAbortError("Browser run ended"));
 		tab.clearRunContext();
 	}
 }

package/src/tools/browser/registry.ts

@@ -71,8 +71,28 @@ export async function acquireBrowser(kind: BrowserKind, opts: AcquireBrowserOpti
 		browsers.delete(key);
 		await disposeBrowserHandle(existing, { kill: false });
 	}
+	// Short-circuit before launching: the tool wrapper's `untilAborted` only
+	// rejects its outer promise on abort; without this check `openBrowserHandle`
+	// would still fire and its result would land in `browsers` below.
+	if (opts.signal?.aborted) throw new ToolAbortError("Browser open aborted");
 
 	const handle = await openBrowserHandle(kind, opts);
+	// The launch may resolve AFTER the caller has already aborted (the outer
+	// `untilAborted` rejects immediately on abort but does not cancel the
+	// inner promise, and `launchHeadlessBrowser` does not accept a signal).
+	// Without this branch the completed handle sits in `browsers` at
+	// refCount:0 forever — no tab ever takes a hold, `releaseBrowser` never
+	// fires, and `releaseAllTabs` walks `tabs`, not `browsers`, so the
+	// orphaned Chromium/app process / puppeteer handle survives to process
+	// exit. (Issue #3963.)
+	if (opts.signal?.aborted) {
+		await disposeBrowserHandle(handle, { kill: kind.kind === "spawned" }).catch(err => {
+			logger.debug("Failed to dispose orphan browser after abort", {
+				error: err instanceof Error ? err.message : String(err),
+			});
+		});
+		throw new ToolAbortError("Browser open aborted");
+	}
 	browsers.set(key, handle);
 	return handle;
 }
@@ -239,3 +259,8 @@ async function disposeBrowserHandle(handle: BrowserHandle, opts: { kill: boolean
 	}
 	if (opts.kill && handle.pid !== undefined) await gracefulKillTreeOnce(handle.pid);
 }
+
+/** Test-only accessor for the module-global browsers map. */
+export function getBrowsersMapForTest(): ReadonlyMap<string, BrowserHandle> {
+	return browsers;
+}

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

@@ -0,0 +1,47 @@
+import { untilAborted } from "@oh-my-pi/pi-utils";
+import { throwIfAborted } from "../tool-errors";
+
+/** Sleeps inside evaluated browser code while honoring the owning run's cancellation signal. */
+export async function waitForBrowserRun(ms: number, signal: AbortSignal): Promise<void> {
+	throwIfAborted(signal);
+	await untilAborted(signal, () => Bun.sleep(ms));
+	throwIfAborted(signal);
+}
+
+/** Binds a long-lived browser facade to one evaluated run's abort signal. */
+export function bindBrowserRunFacade<T extends object>(target: T, signal: AbortSignal): T {
+	const cache = new Map<PropertyKey, unknown>();
+	return new Proxy(target, {
+		get(current, prop) {
+			throwIfAborted(signal);
+			const cached = cache.get(prop);
+			if (cached) return cached;
+			const value = Reflect.get(current, prop, current);
+			if (typeof value === "function") {
+				const wrapped = (...args: unknown[]): unknown => {
+					throwIfAborted(signal);
+					const result = Reflect.apply(value, current, args);
+					if (result && typeof result === "object") {
+						const then = Reflect.get(result, "then");
+						if (typeof then === "function") {
+							return Promise.resolve(result).then(resolved => {
+								throwIfAborted(signal);
+								return resolved;
+							});
+						}
+					}
+					throwIfAborted(signal);
+					return result;
+				};
+				cache.set(prop, wrapped);
+				return wrapped;
+			}
+			if (value && typeof value === "object") {
+				const wrapped = bindBrowserRunFacade(value, signal);
+				cache.set(prop, wrapped);
+				return wrapped;
+			}
+			return value;
+		},
+	});
+}

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

@@ -1,8 +1,8 @@
 import { getPuppeteerDir, logger, Snowflake, workerHostEntry } from "@oh-my-pi/pi-utils";
 import type { Page, Target } from "puppeteer-core";
 import { callSessionTool } from "../../eval/js/tool-bridge";
-import type { ToolSession } from "../../sdk";
 import { webpExclusionForModel } from "../../utils/image-loading";
+import type { ToolSession } from "../index";
 import { expandPath } from "../path-utils";
 import { ToolAbortError, ToolError } from "../tool-errors";
 import { pickElectronTarget } from "./attach";
@@ -59,6 +59,13 @@ interface TabSessionBase<TBrowser extends BrowserHandle = BrowserHandle> {
 	pending: Map<string, PendingRun>;
 	dialogPolicy?: DialogPolicy;
 	kindTag: BrowserKindTag;
+	/**
+	 * Session id of the caller that CREATED the tab. Preserved across reuse so
+	 * that dispose of the creating session can reap browser resources without
+	 * yanking the tab out from under a subagent that only reused it.
+	 * Undefined when the acquirer did not identify itself.
+	 */
+	ownerSessionId?: string;
 }
 
 export interface WorkerTabSession extends TabSessionBase<PuppeteerBrowserHandle> {
@@ -84,6 +91,12 @@ export interface AcquireTabOptions {
 	timeoutMs: number;
 	dialogs?: DialogPolicy;
 	cmuxSurface?: string;
+	/**
+	 * Session id of the acquirer. Recorded on the tab when created (never on
+	 * reuse) so `releaseTabsForOwner` can walk the shared tabs map on session
+	 * dispose. Optional — omitting it opts the tab out of session-scoped reap.
+	 */
+	ownerSessionId?: string;
 }
 
 export interface AcquireTabResult {
@@ -239,6 +252,16 @@ async function acquireTabImpl(
 		}
 	}
 
+	// If the caller aborted while we were spawning/initializing the worker,
+	// tear the freshly-built worker down before publishing the tab so the
+	// browser refCount (which `holdBrowser` below would take) never grows for
+	// a tab nobody is waiting for.
+	if (opts.signal?.aborted) {
+		await worker.terminate().catch(() => undefined);
+		if (tempHold) await releaseBrowser(browser, { kill: false }).catch(() => undefined);
+		throw new ToolAbortError("Browser tab open aborted");
+	}
+
 	holdBrowser(browser);
 	if (tempHold) await releaseBrowser(browser, { kill: false });
 	const tab: WorkerTabSession = {
@@ -252,6 +275,7 @@ async function acquireTabImpl(
 		pending: new Map(),
 		dialogPolicy: opts.dialogs,
 		kindTag: browser.kind.kind,
+		ownerSessionId: opts.ownerSessionId,
 	};
 	worker.onMessage(msg => handleTabMessage(tab, msg));
 	tabs.set(name, tab);
@@ -303,6 +327,11 @@ async function acquireCmuxTab(
 			await cmuxTab.goto(opts.url, { waitUntil: opts.waitUntil ?? "load", timeoutMs: opts.timeoutMs });
 		}
 		const info = await cmuxTab.readyInfo(opts.viewport ?? DEFAULT_VIEWPORT);
+		// If the caller aborted while we were opening the cmux surface, close the
+		// surface (if we own it) instead of taking a browser hold on it.
+		if (opts.signal?.aborted) {
+			throw new ToolAbortError("Browser tab open aborted");
+		}
 		holdBrowser(browser);
 		const tab: CmuxTabSession = {
 			name,
@@ -317,6 +346,7 @@ async function acquireCmuxTab(
 			dialogPolicy: opts.dialogs,
 			kindTag: browser.kind.kind,
 			cmuxAttachedSurface: attachedSurface,
+			ownerSessionId: opts.ownerSessionId,
 		};
 		tabs.set(name, tab);
 		return { tab, created: true };
@@ -386,12 +416,28 @@ async function runInTabWithSnapshot(
 			timeoutMs: opts.timeoutMs,
 			session: snapshot,
 		});
-		return await raceWithTimeout(
-			promise,
-			opts.timeoutMs + GRACE_MS,
-			"Browser code execution hung past grace; tab killed",
-			async reason => await forceKillTab(name, reason),
-		);
+		try {
+			return await raceWithTimeout(
+				promise,
+				opts.timeoutMs + GRACE_MS,
+				"Browser code execution hung past grace; tab killed",
+				async reason => await forceKillTab(name, reason),
+			);
+		} catch (error) {
+			if (error instanceof ToolError && error.message.startsWith("Browser code execution timed out after ")) {
+				try {
+					if (tab.worker.mode === "inline")
+						await forceKillTab(name, "Browser code execution timed out; tab killed");
+					else await recycleTimedOutWorkerTab(tab, opts.timeoutMs + GRACE_MS);
+				} catch (recycleError) {
+					logger.warn("Failed to recycle timed-out browser tab worker; killing tab", {
+						error: recycleError instanceof Error ? recycleError.message : String(recycleError),
+					});
+					await forceKillTab(name, "Browser code execution timed out; tab killed");
+				}
+			}
+			throw error;
+		}
 	} finally {
 		opts.signal?.removeEventListener("abort", abort);
 		tab.pending.delete(id);
@@ -467,6 +513,34 @@ export async function dropHeadlessTabs(): Promise<void> {
 	for (const name of names) await releaseTab(name);
 }
 
+/**
+ * Release every tab created by the given session id. Invoked from
+ * `AgentSession.dispose()` so headless/spawned Chromium and workers the
+ * session opened do not leak into the long-lived process — the module-global
+ * `tabs`/`browsers` maps that back this tool are not otherwise walked by
+ * session teardown. (Issue #3963.)
+ *
+ * Ownership is recorded ONLY on tab creation (`acquireTab` with
+ * `ownerSessionId`), never on reuse: a subagent re-driving a tab another
+ * session opened will not yank teardown responsibility away from the
+ * creator. Tabs opened with no owner (e.g. from an SDK caller that doesn't
+ * identify a session) are skipped and must be released explicitly.
+ */
+export async function releaseTabsForOwner(ownerId: string, opts: ReleaseTabOptions = {}): Promise<number> {
+	if (!ownerId) return 0;
+	const names = [...tabs.values()].filter(tab => tab.ownerSessionId === ownerId).map(tab => tab.name);
+	let count = 0;
+	for (const name of names) {
+		if (await releaseTab(name, opts)) count++;
+	}
+	return count;
+}
+
+/** Test-only accessor for the module-global tabs map. */
+export function getTabsMapForTest(): ReadonlyMap<string, TabSession> {
+	return tabs;
+}
+
 function isLastSurfaceCloseError(err: unknown): boolean {
 	const message = err instanceof Error ? err.message : String(err);
 	return /last/i.test(message);
@@ -583,6 +657,45 @@ function toErrorPayload(error: unknown): RunErrorPayload {
 	return { name: "Error", message: String(error), isAbort: false, isToolError: false };
 }
 
+async function recycleTimedOutWorkerTab(tab: WorkerTabSession, timeoutMs: number): Promise<void> {
+	const oldWorker = tab.worker;
+	await oldWorker.terminate().catch(() => undefined);
+	const browserWSEndpoint = tab.browser.browser.wsEndpoint();
+	if (!browserWSEndpoint) throw new ToolError("Browser websocket endpoint is unavailable");
+	const payload: WorkerInitPayload = {
+		mode: "attach",
+		browserWSEndpoint,
+		safeDir: getPuppeteerDir(),
+		targetId: tab.targetId,
+		dialogs: tab.dialogPolicy,
+	};
+	let worker = await spawnTabWorker();
+	try {
+		const info = await initializeTabWorker(worker, payload, timeoutMs);
+		tab.worker = worker;
+		tab.info = info;
+		tab.state = "alive";
+		worker.onMessage(msg => handleTabMessage(tab, msg));
+	} catch (error) {
+		await worker.terminate().catch(() => undefined);
+		worker = await spawnInlineWorker();
+		try {
+			const info = await initializeTabWorker(worker, payload, timeoutMs);
+			tab.worker = worker;
+			tab.info = info;
+			tab.state = "alive";
+			worker.onMessage(msg => handleTabMessage(tab, msg));
+		} catch (inlineError) {
+			await worker.terminate().catch(() => undefined);
+			const finalError = new ToolError(
+				`Failed to recycle timed-out browser tab worker (inline fallback also failed): ${inlineError instanceof Error ? inlineError.message : String(inlineError)}`,
+			);
+			Object.defineProperty(finalError, "cause", { value: error, configurable: true });
+			throw finalError;
+		}
+	}
+}
+
 async function forceKillTab(name: string, reason: string): Promise<void> {
 	const tab = tabs.get(name);
 	if (!tab) return;

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

@@ -36,6 +36,7 @@ import {
 	loadPuppeteerInWorker,
 } from "./launch";
 import { extractReadableFromHtml, type ReadableFormat } from "./readable";
+import { waitForBrowserRun } from "./run-cancellation";
 import type {
 	Observation,
 	ObservationEntry,
@@ -481,13 +482,13 @@ async function clickQueryHandlerText(
 			const target = await resolveActionableQueryHandlerClickTarget(handles);
 			if (!target) {
 				lastReason = handles.length ? "no-visible-candidate" : "no-matches";
-				await Bun.sleep(100);
+				await untilAborted(clickSignal, () => Bun.sleep(100));
 				continue;
 			}
 			const actionability = await isClickActionable(target);
 			if (!actionability.ok) {
 				lastReason = actionability.reason;
-				await Bun.sleep(100);
+				await untilAborted(clickSignal, () => Bun.sleep(100));
 				continue;
 			}
 			try {
@@ -495,7 +496,7 @@ async function clickQueryHandlerText(
 				return;
 			} catch (err) {
 				lastReason = err instanceof Error ? err.message : String(err);
-				await Bun.sleep(100);
+				await untilAborted(clickSignal, () => Bun.sleep(100));
 			}
 		} finally {
 			await Promise.all(handles.map(async handle => handle.dispose().catch(() => undefined)));
@@ -515,6 +516,7 @@ export interface InflightOp {
 interface ActiveRun {
 	id: string;
 	ac: AbortController;
+	signal: AbortSignal;
 	displays: RunResultOk["displays"];
 	screenshots: ScreenshotResult[];
 	pendingTools: Map<string, { resolve(value: unknown): void; reject(error: Error): void }>;
@@ -697,12 +699,14 @@ export class WorkerCore {
 		}
 		const timeoutSignal = AbortSignal.timeout(msg.timeoutMs);
 		const ac = new AbortController();
-		const signal = AbortSignal.any([timeoutSignal, ac.signal]);
+		const runAc = new AbortController();
+		const signal = AbortSignal.any([timeoutSignal, ac.signal, runAc.signal]);
 		const displays: RunResultOk["displays"] = [];
 		const screenshots: ScreenshotResult[] = [];
 		const active: ActiveRun = {
 			id: msg.id,
 			ac,
+			signal,
 			displays,
 			screenshots,
 			pendingTools: new Map(),
@@ -724,7 +728,7 @@ export class WorkerCore {
 				assert: (cond: unknown, text?: string): void => {
 					if (!cond) throw new ToolError(text ?? "Assertion failed");
 				},
-				wait: (ms: number): Promise<void> => Bun.sleep(ms),
+				wait: (ms: number): Promise<void> => waitForBrowserRun(ms, signal),
 			});
 			const { promise: cancelRejection, reject: rejectCancel } = Promise.withResolvers<never>();
 			const onCancel = (): void => {
@@ -767,6 +771,7 @@ export class WorkerCore {
 			this.#transport.send({ type: "result", id: msg.id, ok: false, error: errorPayload(error) });
 		} finally {
 			if (this.#active?.id === msg.id) this.#active = null;
+			runAc.abort(new ToolAbortError("Browser run ended"));
 		}
 	}
 
@@ -783,11 +788,18 @@ export class WorkerCore {
 		const active = this.#active;
 		if (!active) return null;
 		return {
-			// console.* output stays on the supervisor log channel — matches pre-runtime behavior
-			// where browser cells didn't surface `console.log` to the model.
-			onText: chunk => this.#log("debug", chunk.replace(/\n$/, "")),
-			onDisplay: output => this.#pushDisplay(active.displays, output),
-			callTool: (name, args) => this.#callTool(active, name, args),
+			onText: chunk => {
+				throwIfAborted(active.signal);
+				this.#log("debug", chunk.replace(/\n$/, ""));
+			},
+			onDisplay: output => {
+				throwIfAborted(active.signal);
+				this.#pushDisplay(active.displays, output);
+			},
+			callTool: (name, args) => {
+				throwIfAborted(active.signal);
+				return this.#callTool(active, name, args);
+			},
 		};
 	}
 

package/src/tools/browser.ts

@@ -262,6 +262,7 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 				timeoutMs,
 				dialogs: params.dialogs,
 				signal,
+				ownerSessionId: this.session.getSessionId?.() ?? undefined,
 			}),
 		);
 		const tab = result.tab;

package/src/tools/eval.ts

@@ -10,6 +10,7 @@ import { defaultEvalSessionId } from "../eval/session-id";
 import type { EvalCellResult, EvalDisplayOutput, EvalLanguage, EvalStatusEvent, EvalToolDetails } from "../eval/types";
 import evalDescription from "../prompts/tools/eval.md" with { type: "text" };
 import { DEFAULT_MAX_BYTES, OutputSink, type OutputSummary, TailBuffer } from "../session/streaming-output";
+import { resolveSpawnPolicy } from "../task/spawn-policy";
 import { webpExclusionForModel } from "../utils/image-loading";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import type { ToolSession } from ".";
@@ -164,13 +165,10 @@ export interface EvalToolDescriptionOptions {
 	rb?: boolean;
 	jl?: boolean;
 	/**
-	 * Whether `agent()` is allowed in this session. Driven by the parent's
-	 * spawn policy (`getSessionSpawns`). Defaults to `true` for backward
-	 * compatibility — when the session forbids spawning, the prelude doc
-	 * omits the `agent()` entry so the model does not promise itself a
-	 * helper that will only ever throw "spawns disabled".
+	 * Parent spawn policy (`getSessionSpawns`). `true`/omitted means unrestricted,
+	 * `false`/`""` hides `agent()`, and a comma list drives the advertised default.
 	 */
-	spawns?: boolean;
+	spawns?: boolean | string | null;
 }
 
 export function getEvalToolDescription(options: EvalToolDescriptionOptions = {}): string {
@@ -178,8 +176,16 @@ export function getEvalToolDescription(options: EvalToolDescriptionOptions = {})
 	const js = options.js ?? true;
 	const rb = options.rb ?? false;
 	const jl = options.jl ?? false;
-	const spawns = options.spawns ?? true;
-	return prompt.render(evalDescription, { py, js, rb, jl, spawns });
+	const spawnPolicy = resolveSpawnPolicy(options.spawns ?? true);
+	return prompt.render(evalDescription, {
+		py,
+		js,
+		rb,
+		jl,
+		spawns: spawnPolicy.enabled,
+		spawnDefaultAgent: spawnPolicy.defaultAgent,
+		spawnAllowedAgentsText: spawnPolicy.allowedPromptText,
+	});
 }
 
 export interface EvalToolOptions {
@@ -294,13 +300,12 @@ export class EvalTool implements AgentTool<typeof evalSchema> {
 		if (!this.session) return getEvalToolDescription();
 		const backends = resolveEvalBackends(this.session);
 		const sessionSpawns = this.session.getSessionSpawns?.() ?? "*";
-		const spawnsAllowed = sessionSpawns !== "" && sessionSpawns !== null;
 		return getEvalToolDescription({
 			py: backends.python,
 			js: backends.js,
 			rb: backends.ruby,
 			jl: backends.julia,
-			spawns: spawnsAllowed,
+			spawns: sessionSpawns,
 		});
 	}
 	/** All reuse-chain examples; the `examples` getter filters by enabled languages. */