@oh-my-pi/pi-coding-agent 17.0.3 → 17.0.5

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

@@ -9,7 +9,7 @@ import type { ToolSession } from "../../index";
 import { resolveToCwd } from "../../path-utils";
 import { formatScreenshot } from "../../render-utils";
 import { ToolAbortError, ToolError, throwIfAborted } from "../../tool-errors";
-import { type AriaSnapshotOptions, buildAriaSnapshotScript } from "../aria/aria-snapshot";
+import { type AriaSnapshotOptions, assertSelectorString, buildAriaSnapshotScript } from "../aria/aria-snapshot";
 import { DEFAULT_VIEWPORT } from "../launch";
 import { extractReadableFromHtml, type ReadableFormat } from "../readable";
 import {
@@ -1015,6 +1015,7 @@ export class CmuxTab {
 	}
 
 	#selectorSpec(selector: string): SelectorSpec {
+		assertSelectorString(selector);
 		const raw = selector;
 		let normalized = selector;
 		if (normalized.startsWith("p-text/")) normalized = `text/${normalized.slice("p-text/".length)}`;

package/src/tools/browser/cmux/socket-client.ts

@@ -1,9 +1,12 @@
 import { randomUUID } from "node:crypto";
 import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
 import { ToolError } from "../../tool-errors";
 
 const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const UTF8 = new TextEncoder();
 
 type RequestJob = {
 	method: string;
@@ -25,6 +28,37 @@ type CmuxErrorPayload = {
 	details?: unknown;
 };
 
+type RelayEndpoint = {
+	host: string;
+	port: number;
+};
+
+type RelayCredentials = {
+	relayId: string;
+	relayToken: Uint8Array<ArrayBuffer>;
+};
+
+function parseRelayCredentials(relayIdValue: unknown, relayTokenValue: unknown): RelayCredentials | null {
+	if (typeof relayIdValue !== "string" || typeof relayTokenValue !== "string") {
+		return null;
+	}
+	const relayId = relayIdValue.trim();
+	const relayTokenHex = relayTokenValue.trim();
+	if (
+		relayId.length === 0 ||
+		relayTokenHex.length === 0 ||
+		relayTokenHex.length % 2 !== 0 ||
+		!/^[0-9a-f]+$/i.test(relayTokenHex)
+	) {
+		return null;
+	}
+	const relayToken = new Uint8Array(new ArrayBuffer(relayTokenHex.length / 2));
+	for (let index = 0; index < relayToken.length; index++) {
+		relayToken[index] = Number.parseInt(relayTokenHex.slice(index * 2, index * 2 + 2), 16);
+	}
+	return { relayId, relayToken };
+}
+
 export function formatCmuxError(error: CmuxErrorPayload | undefined): string {
 	const code = typeof error?.code === "string" && error.code.length > 0 ? error.code : "error";
 	const message = typeof error?.message === "string" && error.message.length > 0 ? error.message : "cmux error";
@@ -35,6 +69,8 @@ export function formatCmuxError(error: CmuxErrorPayload | undefined): string {
 export class CmuxSocketClient {
 	readonly #socketPath: string;
 	readonly #password: string | undefined;
+	readonly #relayId: string | undefined;
+	readonly #relayToken: string | undefined;
 	#socket: net.Socket | null = null;
 	#connectPromise: Promise<void> | null = null;
 	#connected = false;
@@ -45,9 +81,11 @@ export class CmuxSocketClient {
 	#activeJob: RequestJob | null = null;
 	#pumping = false;
 
-	constructor(opts: { socketPath: string; password?: string }) {
+	constructor(opts: { socketPath: string; password?: string; relayId?: string; relayToken?: string }) {
 		this.#socketPath = opts.socketPath;
 		this.#password = opts.password;
+		this.#relayId = opts.relayId ?? process.env.CMUX_RELAY_ID;
+		this.#relayToken = opts.relayToken ?? process.env.CMUX_RELAY_TOKEN;
 	}
 
 	async connect(): Promise<void> {
@@ -101,7 +139,11 @@ export class CmuxSocketClient {
 	}
 
 	async #openSocket(): Promise<void> {
-		const socket = net.createConnection({ path: this.#socketPath });
+		const relayEndpoint = this.#parseRelayEndpoint();
+		const relayCredentials = relayEndpoint ? await this.#loadRelayCredentials(relayEndpoint) : null;
+		const socket = relayEndpoint
+			? net.createConnection({ host: relayEndpoint.host, port: relayEndpoint.port })
+			: net.createConnection({ path: this.#socketPath });
 		this.#socket = socket;
 		this.#buffer = "";
 		socket.setEncoding("utf8");
@@ -111,13 +153,16 @@ export class CmuxSocketClient {
 
 		try {
 			await this.#waitForConnect(socket);
-			this.#connected = true;
+			if (relayEndpoint && relayCredentials) {
+				await this.#authenticateRelay(relayEndpoint, relayCredentials);
+			}
 			if (this.#password) {
 				const line = await this.#sendLine(`auth ${this.#password}`, DEFAULT_CONNECT_TIMEOUT_MS);
 				if (line.startsWith("ERROR:") && !line.includes("Unknown command 'auth'")) {
 					throw new ToolError(line);
 				}
 			}
+			this.#connected = true;
 		} catch (err) {
 			this.#connected = false;
 			socket.destroy();
@@ -128,6 +173,97 @@ export class CmuxSocketClient {
 		}
 	}
 
+	#parseRelayEndpoint(): RelayEndpoint | null {
+		const value = this.#socketPath.trim();
+		if (value.length === 0 || value.startsWith("/")) {
+			return null;
+		}
+		const match = /^(127\.0\.0\.1|localhost):([0-9]+)$/.exec(value);
+		if (!match) {
+			return null;
+		}
+		const port = Number.parseInt(match[2] ?? "", 10);
+		if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+			return null;
+		}
+		return { host: "127.0.0.1", port };
+	}
+
+	async #loadRelayCredentials(endpoint: RelayEndpoint): Promise<RelayCredentials> {
+		const environmentCredentials = parseRelayCredentials(this.#relayId, this.#relayToken);
+		if (environmentCredentials) {
+			return environmentCredentials;
+		}
+
+		const authPath = path.join(os.homedir(), ".cmux", "relay", `${endpoint.port}.auth`);
+		let payload: unknown;
+		try {
+			payload = await Bun.file(authPath).json();
+		} catch {
+			throw new ToolError(
+				`Missing cmux relay auth metadata for ${endpoint.host}:${endpoint.port}; set CMUX_RELAY_ID/CMUX_RELAY_TOKEN or restore ~/.cmux/relay/${endpoint.port}.auth`,
+			);
+		}
+		const relayId = payload && typeof payload === "object" && "relay_id" in payload ? payload.relay_id : undefined;
+		const relayToken =
+			payload && typeof payload === "object" && "relay_token" in payload ? payload.relay_token : undefined;
+		const fileCredentials = parseRelayCredentials(relayId, relayToken);
+		if (!fileCredentials) {
+			throw new ToolError(`Invalid cmux relay auth metadata in ~/.cmux/relay/${endpoint.port}.auth`);
+		}
+		return fileCredentials;
+	}
+
+	async #authenticateRelay(endpoint: RelayEndpoint, credentials: RelayCredentials): Promise<void> {
+		const challengeLine = await this.#nextLine(DEFAULT_CONNECT_TIMEOUT_MS);
+		let challenge: unknown;
+		try {
+			challenge = JSON.parse(challengeLine);
+		} catch {
+			throw new ToolError(`Invalid cmux relay authentication challenge from ${endpoint.host}:${endpoint.port}`);
+		}
+		if (
+			!challenge ||
+			typeof challenge !== "object" ||
+			!("protocol" in challenge) ||
+			challenge.protocol !== "cmux-relay-auth" ||
+			!("version" in challenge) ||
+			typeof challenge.version !== "number" ||
+			!Number.isInteger(challenge.version) ||
+			!("relay_id" in challenge) ||
+			challenge.relay_id !== credentials.relayId ||
+			!("nonce" in challenge) ||
+			typeof challenge.nonce !== "string" ||
+			challenge.nonce.length === 0
+		) {
+			throw new ToolError(`Invalid cmux relay authentication challenge from ${endpoint.host}:${endpoint.port}`);
+		}
+
+		const message = `relay_id=${challenge.relay_id}\nnonce=${challenge.nonce}\nversion=${challenge.version}`;
+		const key = await globalThis.crypto.subtle.importKey(
+			"raw",
+			credentials.relayToken,
+			{ name: "HMAC", hash: "SHA-256" },
+			false,
+			["sign"],
+		);
+		const mac = await globalThis.crypto.subtle.sign("HMAC", key, UTF8.encode(message));
+		const authLine = JSON.stringify({
+			relay_id: credentials.relayId,
+			mac: Buffer.from(mac).toString("hex"),
+		});
+		const responseLine = await this.#sendLine(authLine, DEFAULT_CONNECT_TIMEOUT_MS);
+		let response: unknown;
+		try {
+			response = JSON.parse(responseLine);
+		} catch {
+			throw new ToolError(`Cmux relay authentication failed for ${endpoint.host}:${endpoint.port}`);
+		}
+		if (!response || typeof response !== "object" || !("ok" in response) || response.ok !== true) {
+			throw new ToolError(`Cmux relay authentication failed for ${endpoint.host}:${endpoint.port}`);
+		}
+	}
+
 	#waitForConnect(socket: net.Socket): Promise<void> {
 		const { promise, resolve, reject } = Promise.withResolvers<void>();
 		const timer = setTimeout(() => {

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

@@ -117,6 +117,10 @@ export function bindBrowserRunFacade<T extends object>(target: T, signal: AbortS
 				return wrapped;
 			}
 			if (value && typeof value === "object") {
+				// Never proxy AbortSignals: native combinators (AbortSignal.any, fetch)
+				// brand-check internal slots that a Proxy cannot forward, and reading a
+				// signal needs no abort gating anyway.
+				if (value instanceof AbortSignal) return value;
 				const wrapped = bindBrowserRunFacade(value, signal);
 				cache.set(prop, wrapped);
 				return wrapped;

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

@@ -95,6 +95,8 @@ export interface RunErrorPayload {
 	stack?: string;
 	isToolError: boolean;
 	isAbort: boolean;
+	/** The worker could not restore tab-scoped browser state and must be recycled. */
+	recoverTab?: boolean;
 }
 
 export type WorkerOutbound =

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

@@ -138,6 +138,7 @@ const GRACE_MS = 750;
 // vanished instead of a bare "not alive". Cleared when the name is opened again.
 const killedTabs = new Map<string, string>();
 const DEFAULT_TAB_CLOSE_TIMEOUT_MS = 5_000;
+class RecoverableWorkerError extends ToolError {}
 
 async function waitForTabCleanup<T>(
 	tab: TabSession,
@@ -488,16 +489,23 @@ async function runInTabWithSnapshot(
 				async reason => await forceKillTab(name, reason),
 			);
 		} catch (error) {
-			if (error instanceof ToolError && error.message.startsWith("Browser code execution timed out after ")) {
+			const runTimedOut =
+				error instanceof ToolError && error.message.startsWith("Browser code execution timed out after ");
+			if (runTimedOut || error instanceof RecoverableWorkerError) {
 				try {
-					if (tab.worker.mode === "inline")
-						await forceKillTab(name, "Browser code execution timed out; tab killed");
-					else await recycleTimedOutWorkerTab(tab, opts.timeoutMs + GRACE_MS);
+					if (tab.worker.mode === "inline") {
+						const reason = runTimedOut
+							? "Browser code execution timed out; tab killed"
+							: "Browser request interception cleanup failed; tab killed";
+						await forceKillTab(name, reason);
+					} else {
+						await recycleTimedOutWorkerTab(tab, opts.timeoutMs + GRACE_MS);
+					}
 				} catch (recycleError) {
-					logger.warn("Failed to recycle timed-out browser tab worker; killing tab", {
+					logger.warn("Failed to recycle browser tab worker; killing tab", {
 						error: recycleError instanceof Error ? recycleError.message : String(recycleError),
 					});
-					await forceKillTab(name, "Browser code execution timed out; tab killed");
+					await forceKillTab(name, "Browser tab worker recovery failed; tab killed");
 				}
 			}
 			throw error;
@@ -873,11 +881,13 @@ async function targetIdForTarget(target: Target): Promise<string> {
 }
 
 function errorFromPayload(payload: RunErrorPayload): Error {
-	const error = payload.isAbort
-		? new ToolAbortError()
-		: payload.isToolError
-			? new ToolError(payload.message)
-			: new Error(payload.message);
+	const error = payload.recoverTab
+		? new RecoverableWorkerError(payload.message)
+		: payload.isAbort
+			? new ToolAbortError()
+			: payload.isToolError
+				? new ToolError(payload.message)
+				: new Error(payload.message);
 	error.name = payload.name;
 	if (payload.stack) error.stack = payload.stack;
 	return error;

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

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { postmortem, Snowflake, untilAborted } from "@oh-my-pi/pi-utils";
+import { postmortem, Snowflake, untilAborted, withTimeout } from "@oh-my-pi/pi-utils";
 import type { HTMLElement } from "linkedom";
 import type {
 	Browser,
@@ -24,6 +24,7 @@ import { formatScreenshot } from "../render-utils";
 import { ToolAbortError, ToolError, throwIfAborted } from "../tool-errors";
 import {
 	type AriaSnapshotOptions,
+	assertSelectorString,
 	captureAriaSnapshot,
 	parseAriaRefSelector,
 	resolveAriaRefHandle,
@@ -37,6 +38,7 @@ import {
 } from "./launch";
 import { extractReadableFromHtml, type ReadableFormat } from "./readable";
 import {
+	bindBrowserRunFacade,
 	CELL_BUDGET_SLACK_MS,
 	markHandled,
 	resolvePredicateTimeout,
@@ -144,6 +146,8 @@ interface OpenDialogInfo {
  */
 const QUICK_OP_TIMEOUT_MS = 20_000;
 const ACTION_OP_TIMEOUT_MS = 8_000;
+/** Maximum wait for a renderer acknowledgement after a wheel event is queued. */
+const SCROLL_ACK_TIMEOUT_MS = 2_000;
 /** Headroom subtracted from the cell budget so a per-op deadline fires before it. */
 const OP_DEADLINE_SLACK_MS = CELL_BUDGET_SLACK_MS;
 /**
@@ -155,6 +159,8 @@ const OP_DEADLINE_SLACK_MS = CELL_BUDGET_SLACK_MS;
 const ZERO_MATCH_FAIL_FAST_MS = 2_000;
 /** Poll cadence for the zero-match watchdog. */
 const ZERO_MATCH_POLL_MS = 250;
+/** Cleanup must settle inside the supervisor's 750ms post-run grace window. */
+const REQUEST_INTERCEPTION_CLEANUP_TIMEOUT_MS = 500;
 
 export interface OpTimeouts {
 	/** Largest per-op deadline allowed — strictly below the cell budget. */
@@ -175,6 +181,21 @@ export function resolveOpTimeouts(cellTimeoutMs: number): OpTimeouts {
 	};
 }
 
+/** Queue a wheel event without treating a delayed renderer acknowledgement as dispatch failure. */
+export async function dispatchScroll(
+	dispatch: () => Promise<void>,
+	ackTimeoutMs = SCROLL_ACK_TIMEOUT_MS,
+): Promise<void> {
+	const deadline = Promise.withResolvers<void>();
+	const timer = setTimeout(() => deadline.resolve(), ackTimeoutMs);
+	timer.unref();
+	try {
+		await Promise.race([dispatch(), deadline.promise]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
 /**
  * Effective timeout for a wait helper (`waitFor*`). A positive explicit `{ timeout }` is
  * honored but clamped to the cell budget so it still fails fast + named; raising the tool
@@ -246,6 +267,7 @@ interface TabApi {
 }
 
 export function normalizeSelector(selector: string): string {
+	assertSelectorString(selector);
 	if (!selector) return selector;
 	if (
 		!SELECTOR_HANDLER_PREFIXES.some(prefix => selector.startsWith(prefix)) &&
@@ -334,12 +356,125 @@ function redactUrlCredentials(url: string): string {
 	}
 }
 
+class RequestInterceptionCleanupError extends ToolError {}
+
+interface RunPageScope {
+	page: Page;
+	cleanup(): Promise<void>;
+}
+
+/**
+ * Expose the tab page while retaining the request handlers created by this run.
+ * Puppeteer's Page wraps an internal emitter, so `removeAllListeners("request")`
+ * would also remove its forwarding listener; the facade removes only user handlers.
+ */
+function createRunPageScope(page: Page): RunPageScope {
+	const requestHandlers: unknown[] = [];
+	const on = page.on;
+	const off = page.off;
+	const once = page.once;
+	const removeAllListeners = page.removeAllListeners;
+	const onDescriptor = Object.getOwnPropertyDescriptor(page, "on");
+	const offDescriptor = Object.getOwnPropertyDescriptor(page, "off");
+	const onceDescriptor = Object.getOwnPropertyDescriptor(page, "once");
+	const removeAllDescriptor = Object.getOwnPropertyDescriptor(page, "removeAllListeners");
+
+	Object.defineProperties(page, {
+		on: {
+			configurable: true,
+			value: (type: unknown, handler: unknown): Page => {
+				Reflect.apply(on, page, [type, handler]);
+				if (type === "request") requestHandlers.push(handler);
+				return page;
+			},
+		},
+		once: {
+			configurable: true,
+			value: (type: unknown, handler: unknown): Page => {
+				if (type !== "request" || typeof handler !== "function") {
+					Reflect.apply(once, page, [type, handler]);
+					return page;
+				}
+				const wrapper = (event: unknown): void => {
+					const index = requestHandlers.lastIndexOf(wrapper);
+					if (index >= 0) requestHandlers.splice(index, 1);
+					Reflect.apply(off, page, ["request", wrapper]);
+					Reflect.apply(handler, page, [event]);
+				};
+				requestHandlers.push(wrapper);
+				Reflect.apply(on, page, [type, wrapper]);
+				return page;
+			},
+		},
+		off: {
+			configurable: true,
+			value: (type: unknown, handler?: unknown): Page => {
+				Reflect.apply(off, page, [type, handler]);
+				if (type === "request") {
+					if (handler === undefined) requestHandlers.length = 0;
+					else {
+						const index = requestHandlers.lastIndexOf(handler);
+						if (index >= 0) requestHandlers.splice(index, 1);
+					}
+				}
+				return page;
+			},
+		},
+		removeAllListeners: {
+			configurable: true,
+			value: (type?: unknown): Page => {
+				Reflect.apply(removeAllListeners, page, [type]);
+				if (type === undefined || type === "request") requestHandlers.length = 0;
+				return page;
+			},
+		},
+	});
+
+	return {
+		page,
+		async cleanup() {
+			if (onDescriptor) Object.defineProperty(page, "on", onDescriptor);
+			else Reflect.deleteProperty(page, "on");
+			if (offDescriptor) Object.defineProperty(page, "off", offDescriptor);
+			else Reflect.deleteProperty(page, "off");
+			if (onceDescriptor) Object.defineProperty(page, "once", onceDescriptor);
+			else Reflect.deleteProperty(page, "once");
+			if (removeAllDescriptor) Object.defineProperty(page, "removeAllListeners", removeAllDescriptor);
+			else Reflect.deleteProperty(page, "removeAllListeners");
+			for (const handler of requestHandlers) Reflect.apply(off, page, ["request", handler]);
+			requestHandlers.length = 0;
+			try {
+				await withTimeout(
+					page.setRequestInterception(false),
+					REQUEST_INTERCEPTION_CLEANUP_TIMEOUT_MS,
+					"Timed out clearing browser request interception",
+				);
+			} catch (error) {
+				throw new RequestInterceptionCleanupError(
+					"Failed to clear browser request interception after browser.run",
+					{
+						error: error instanceof Error ? error.message : String(error),
+					},
+				);
+			}
+		},
+	};
+}
+
 function errorPayload(error: unknown): RunErrorPayload {
+	const recoverTab = error instanceof RequestInterceptionCleanupError || undefined;
 	if (error instanceof ToolAbortError) {
 		return { name: error.name, message: error.message, stack: error.stack, isToolError: false, isAbort: true };
 	}
 	if (error instanceof ToolError) {
-		return { name: error.name, message: error.message, stack: error.stack, isToolError: true, isAbort: false };
+		return {
+			name: error.name,
+			message: error.message,
+			stack: error.stack,
+			isToolError: true,
+			isAbort: false,
+			recoverTab,
+		};
 	}
 	if (error instanceof Error) {
 		return { name: error.name, message: error.message, stack: error.stack, isToolError: false, isAbort: false };
@@ -720,6 +855,7 @@ export class WorkerCore {
 			await session.send("Page.enable").catch(() => undefined);
 			await session.send("Page.handleJavaScriptDialog", { accept: false }).catch(() => undefined);
 			await session.send("Page.stopLoading").catch(() => undefined);
+			await session.send("Fetch.disable").catch(() => undefined);
 		} catch (error) {
 			this.#log("debug", "Recovery CDP session failed; proceeding with attach", {
 				error: error instanceof Error ? error.message : String(error),
@@ -816,17 +952,21 @@ export class WorkerCore {
 			opCounter: 0,
 		};
 		this.#active = active;
+		let completed = false;
+		let returnValue: unknown;
+		let failure: { error: unknown } | undefined;
+		let runPage: RunPageScope | undefined;
 		try {
 			throwIfAborted(signal);
-			const page = this.#requirePage();
+			runPage = createRunPageScope(this.#requirePage());
 			const browser = this.#requireBrowser();
 			const tabApi = this.#createTabApi(msg.name, msg.timeoutMs, signal, msg.session, output, screenshots, active);
 			const runtime = this.#ensureRuntime(msg.session);
 			runtime.setCwd(msg.session.cwd);
 			runtime.setRunScope({
-				page,
-				browser,
-				tab: tabApi,
+				page: bindBrowserRunFacade(runPage.page, signal),
+				browser: bindBrowserRunFacade(browser, signal),
+				tab: bindBrowserRunFacade(tabApi, signal),
 				assert: (cond: unknown, text?: string): void => {
 					if (!cond) throw new ToolError(text ?? "Assertion failed");
 				},
@@ -879,25 +1019,37 @@ export class WorkerCore {
 			try {
 				const hooks = this.#hooksForActiveRun();
 				if (!hooks) throw new ToolError("Browser runtime started without an active run");
-				const returnValue = await Promise.race([
+				returnValue = await Promise.race([
 					runtime.run(msg.code, `browser-run-${msg.id}.js`, hooks, { runId: msg.id, cwd: msg.session.cwd }),
 					cancelRejection,
 				]);
-				await this.#postReadyInfo();
-				this.#transport.send({
-					type: "result",
-					id: msg.id,
-					ok: true,
-					payload: { displays: output.finish(), returnValue: cloneSafe(returnValue), screenshots },
-				});
+				completed = true;
 			} finally {
 				signal.removeEventListener("abort", onCancel);
 			}
 		} catch (error) {
-			this.#transport.send({ type: "result", id: msg.id, ok: false, error: errorPayload(error) });
+			failure = { error };
 		} finally {
-			if (this.#active?.id === msg.id) this.#active = null;
 			runAc.abort(postmortem.markExpectedCleanupError(new ToolAbortError("Browser run ended")));
+			try {
+				await runPage?.cleanup();
+			} catch (error) {
+				failure = { error };
+			}
+			if (this.#active?.id === msg.id) this.#active = null;
+		}
+		if (failure) {
+			this.#transport.send({ type: "result", id: msg.id, ok: false, error: errorPayload(failure.error) });
+			return;
+		}
+		if (completed) {
+			await this.#postReadyInfo();
+			this.#transport.send({
+				type: "result",
+				id: msg.id,
+				ok: true,
+				payload: { displays: output.finish(), returnValue: cloneSafe(returnValue), screenshots },
+			});
 		}
 	}
 
@@ -1212,11 +1364,22 @@ export class WorkerCore {
 			press: (key, opts) =>
 				op(`tab.press(${JSON.stringify(key)})`, actionOpMs, async sig => {
 					const selector = opts?.selector;
-					if (selector) await untilAborted(sig, () => page.focus(normalizeSelector(selector)));
+					if (selector) {
+						if (parseAriaRefSelector(selector) !== null) {
+							const handle = await this.#resolveAriaRef(selector);
+							try {
+								await untilAborted(sig, () => handle.focus());
+							} finally {
+								await handle.dispose().catch(() => undefined);
+							}
+						} else await untilAborted(sig, () => page.focus(normalizeSelector(selector)));
+					}
 					await untilAborted(sig, () => page.keyboard.press(key));
 				}),
 			scroll: (deltaX, deltaY) =>
-				op("tab.scroll()", actionOpMs, sig => untilAborted(sig, () => page.mouse.wheel({ deltaX, deltaY }))),
+				op("tab.scroll()", actionOpMs, sig =>
+					untilAborted(sig, () => dispatchScroll(() => page.mouse.wheel({ deltaX, deltaY }))),
+				),
 			drag: (from, to) => op("tab.drag()", actionOpMs, sig => this.#drag(from, to, sig)),
 			waitFor: (selector, opts) => {
 				const w = waitMs(opts?.timeout);
@@ -1387,9 +1550,10 @@ export class WorkerCore {
 		const captureMime = `image/${captureType}` as const;
 		let buffer: Buffer;
 		if (opts.selector) {
-			const handle = (await untilAborted(signal, () =>
-				page.$(normalizeSelector(opts.selector!)),
-			)) as ElementHandle | null;
+			const handle =
+				parseAriaRefSelector(opts.selector) !== null
+					? await this.#resolveAriaRef(opts.selector)
+					: asElementHandle(await untilAborted(signal, () => page.$(normalizeSelector(opts.selector!))));
 			if (!handle) throw new ToolError("Screenshot selector did not resolve to an element");
 			try {
 				// Bring the element into view with a single instant scroll instead of puppeteer's
@@ -1462,9 +1626,10 @@ export class WorkerCore {
 			role: "from" | "to",
 		): Promise<{ x: number; y: number; handle?: ElementHandle }> => {
 			if (typeof target === "string") {
-				const handle = (await untilAborted(signal, () =>
-					page.$(normalizeSelector(target)),
-				)) as ElementHandle | null;
+				const handle =
+					parseAriaRefSelector(target) !== null
+						? await this.#resolveAriaRef(target)
+						: asElementHandle(await untilAborted(signal, () => page.$(normalizeSelector(target))));
 				if (!handle) throw new ToolError(`Drag ${role} selector did not resolve: ${target}`);
 				const box = (await untilAborted(signal, () => handle.boundingBox())) as {
 					x: number;
@@ -1505,10 +1670,7 @@ export class WorkerCore {
 	}
 
 	async #select(selector: string, values: string[], timeoutMs: number, signal: AbortSignal): Promise<string[]> {
-		const page = this.#requirePage();
-		const handle = (await untilAborted(signal, () =>
-			page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle({ signal }),
-		)) as ElementHandle;
+		const handle = await this.#resolveActionHandle(selector, timeoutMs, signal);
 		try {
 			return (await untilAborted(signal, () =>
 				handle.evaluate((el, vals) => {
@@ -1527,10 +1689,17 @@ export class WorkerCore {
 						globalThis as unknown as { Event: new (type: string, init?: { bubbles: boolean }) => unknown }
 					).Event;
 					const wanted = new Set(vals as string[]);
-					const selected: string[] = [];
+					// Assign the full selection first, then read back: on a single
+					// <select>, un-selecting the current option mid-loop leaves the
+					// browser reporting it selected until another option takes over,
+					// which double-counted the old value in the returned list.
 					for (let i = 0; i < select.options.length; i++) {
 						const opt = select.options[i] as SelectOption;
 						opt.selected = wanted.has(opt.value);
+					}
+					const selected: string[] = [];
+					for (let i = 0; i < select.options.length; i++) {
+						const opt = select.options[i] as SelectOption;
 						if (opt.selected) selected.push(opt.value);
 					}
 					select.dispatchEvent(new EventCtor("input", { bubbles: true }));
@@ -1551,10 +1720,7 @@ export class WorkerCore {
 		session: SessionSnapshot,
 	): Promise<void> {
 		if (!filePaths.length) throw new ToolError("tab.uploadFile() requires at least one file path");
-		const page = this.#requirePage();
-		const handle = (await untilAborted(signal, () =>
-			page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle({ signal }),
-		)) as ElementHandle;
+		const handle = await this.#resolveActionHandle(selector, timeoutMs, signal);
 		try {
 			const absolute = filePaths.map(filePath => resolveToCwd(filePath, session.cwd));
 			const upload = handle as unknown as { uploadFile: (...paths: string[]) => Promise<void> };

package/src/tools/debug.ts

@@ -504,12 +504,15 @@ const ADAPTER_UNAVAILABLE_MESSAGES: Readonly<Record<string, string>> = {
 	debugpy: "adapter 'debugpy' is not available: python not found in PATH",
 	dlv: "adapter 'dlv' is not available: install with 'go install github.com/go-delve/delve/cmd/dlv@latest'",
 	rdbg: "adapter 'rdbg' is not available: install with 'gem install debug'",
+	"js-debug-adapter":
+		"adapter 'js-debug-adapter' is not available: install vscode-js-debug with Mason or set JS_DEBUG_DAP_SERVER to dapDebugServer.js",
 };
 
 const ADAPTER_CANONICAL_COMMANDS: Readonly<Record<string, string>> = {
 	debugpy: "python",
 	dlv: "dlv",
 	rdbg: "rdbg",
+	"js-debug-adapter": "js-debug-adapter",
 };
 
 function formatAdapterUnavailable(adapterName: string, command: string, cwd: string): string {