@gajae-code/coding-agent 0.11.3 → 0.11.5

package/src/tools/bash-allowed-prefixes.ts

@@ -1,3 +1,11 @@
+import {
+	classifyStateArgv,
+	STATE_ACTION_NAMES,
+	type StateAction,
+	type StateArgvClassification,
+} from "../gjc-runtime/state-argv";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
+
 export interface BashAllowedPrefixesCheck {
 	allowed: boolean;
 	reason?: string;
@@ -11,9 +19,8 @@ export interface BashRestrictionOptions {
 
 const SHELL_CONTROL_CHARS = new Set([";", "|", "&", "<", ">", "(", ")"]);
 const UNSAFE_UNQUOTED_EXPANSION_CHARS = new Set(["$", "*", "?", "[", "]", "{", "}", "~"]);
-const STATE_FLAGS_WITH_VALUES = new Set(["--input", "--mode", "--session-id", "--thread-id", "--turn-id", "--to"]);
-const STATE_ACTIONS = new Set(["read", "write", "clear", "contract", "handoff"]);
 const ALLOWED_STATE_ACTIONS = new Set(["read", "write", "contract"]);
+const CANONICAL_STATE_TARGETS = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS);
 const READ_ONLY_COMMANDS = new Set(["grep", "rg", "tree", "ls", "pwd", "wc", "du", "file", "stat"]);
 
 function parseShellWords(command: string): { words: string[]; reason?: string } {
@@ -21,6 +28,7 @@ function parseShellWords(command: string): { words: string[]; reason?: string }
 	let current = "";
 	let quote: "single" | "double" | null = null;
 
+	let wordStarted = false;
 	for (let index = 0; index < command.length; index += 1) {
 		const char = command[index]!;
 		const next = command[index + 1];
@@ -54,10 +62,12 @@ function parseShellWords(command: string): { words: string[]; reason?: string }
 
 		if (char === "'") {
 			quote = "single";
+			wordStarted = true;
 			continue;
 		}
 		if (char === '"') {
 			quote = "double";
+			wordStarted = true;
 			continue;
 		}
 		if (char === "`" || (char === "$" && next === "(")) {
@@ -73,9 +83,10 @@ function parseShellWords(command: string): { words: string[]; reason?: string }
 			return { words, reason: `shell expansion character '${char}' is not allowed in restricted bash commands` };
 		}
 		if (/\s/u.test(char)) {
-			if (current.length > 0) {
+			if (wordStarted) {
 				words.push(current);
 				current = "";
+				wordStarted = false;
 			}
 			continue;
 		}
@@ -83,12 +94,13 @@ function parseShellWords(command: string): { words: string[]; reason?: string }
 			return { words, reason: "backslash escapes are not allowed in restricted bash commands" };
 		}
 		current += char;
+		wordStarted = true;
 	}
 
 	if (quote !== null) {
 		return { words, reason: "unterminated quote in restricted bash command" };
 	}
-	if (current.length > 0) words.push(current);
+	if (wordStarted) words.push(current);
 	return { words };
 }
 
@@ -101,28 +113,62 @@ function wordsStartWith(words: readonly string[], prefix: readonly string[]): bo
 	return prefix.every((word, index) => words[index] === word);
 }
 
-function parseStateAction(words: readonly string[]): string | undefined {
-	const args = words.slice(2);
-	const positional: string[] = [];
-	let skipNext = false;
-	for (const arg of args) {
-		if (skipNext) {
-			skipNext = false;
-			continue;
-		}
-		if (STATE_FLAGS_WITH_VALUES.has(arg)) {
-			skipNext = true;
-			continue;
-		}
-		if (!arg.startsWith("-")) positional.push(arg);
+function malformedStateShape(): StateActionClassification {
+	return { reason: "restricted role-agent bash only allows documented `gjc state` action shapes" };
+}
+
+interface ParsedStateAction {
+	action: string;
+	target: string;
+}
+
+interface StateActionClassification {
+	parsed?: ParsedStateAction;
+	reason?: string;
+}
+
+function hasDocumentedStatePositionals(classification: StateArgvClassification): boolean {
+	const [first, second, third] = classification.positionals;
+	if (third) return false;
+	if (!second) return true;
+	return STATE_ACTION_NAMES.has(first as StateAction) || STATE_ACTION_NAMES.has(second as StateAction);
+}
+
+function classifyStateAction(words: readonly string[]): StateActionClassification {
+	const classification = classifyStateArgv(words.slice(2));
+	if (
+		classification.unknownFlags.length > 0 ||
+		classification.flags.some(flag => flag.malformed) ||
+		!hasDocumentedStatePositionals(classification)
+	) {
+		return malformedStateShape();
+	}
+
+	const modeFlags = classification.flags.filter(flag => flag.name === "--mode");
+	const inputFlags = classification.flags.filter(flag => flag.name === "--input");
+	if (modeFlags.length > 1 || inputFlags.length > 1) {
+		return { reason: "restricted role-agent bash rejects repeated or conflicting `gjc state` target selectors" };
+	}
+	if (classification.inputs.some(input => input.kind === "file")) {
+		return { reason: "restricted role-agent bash does not allow file-backed `gjc state --input` values" };
 	}
+	if (classification.inputs.some(input => input.kind === "invalid")) return malformedStateShape();
 
-	const [first, second, third] = positional;
-	if (!first) return "read";
-	if (STATE_ACTIONS.has(first)) return second ? undefined : first;
-	if (!second) return "read";
-	if (!STATE_ACTIONS.has(second)) return undefined;
-	return third ? undefined : second;
+	const runtimeTarget = classification.runtimeSelectorCandidates.find(candidate => candidate.value)?.value;
+	const suppliedTargets = classification.selectorCandidates
+		.map(candidate => candidate.value)
+		.filter((target): target is string => target !== undefined);
+	const distinctTargets = new Set(suppliedTargets);
+	if (distinctTargets.size > 1 || (runtimeTarget && suppliedTargets.some(target => target !== runtimeTarget))) {
+		return {
+			reason:
+				"restricted role-agent bash rejects conflicting `gjc state` selectors that disagree with runtime precedence",
+		};
+	}
+	if (!runtimeTarget || !CANONICAL_STATE_TARGETS.has(runtimeTarget)) {
+		return { reason: "restricted role-agent bash requires a canonical workflow skill for `gjc state` commands" };
+	}
+	return { parsed: { action: classification.effectiveAction, target: runtimeTarget } };
 }
 
 function optionWords(words: readonly string[]): string[] {
@@ -189,15 +235,19 @@ function validateMatchedGjcCommand(words: readonly string[]): BashAllowedPrefixe
 	}
 
 	if (words[1] === "state") {
-		const action = parseStateAction(words);
-		if (!action) {
+		const classification = classifyStateAction(words);
+		if (!classification.parsed) {
 			return {
 				allowed: false,
-				reason: "restricted role-agent bash only allows documented `gjc state` action shapes",
+				reason:
+					classification.reason ?? "restricted role-agent bash only allows documented `gjc state` action shapes",
 			};
 		}
-		if (!ALLOWED_STATE_ACTIONS.has(action)) {
-			return { allowed: false, reason: `restricted role-agent bash does not allow \`gjc state ${action}\`` };
+		if (!ALLOWED_STATE_ACTIONS.has(classification.parsed.action)) {
+			return {
+				allowed: false,
+				reason: `restricted role-agent bash does not allow \`gjc state ${classification.parsed.action}\``,
+			};
 		}
 		return { allowed: true };
 	}

package/src/tools/bash-skill-urls.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { Skill } from "../extensibility/skills";
-import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
+import { initializeLocalRoot, type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import { validateRelativePath } from "../internal-urls/skill-protocol";
 import type { InternalResource } from "../internal-urls/types";
 import { normalizeLocalScheme } from "./path-utils";
@@ -162,12 +162,23 @@ async function resolveInternalUrlToPath(
 		return resolveSkillUrlToPath(url, skills);
 	}
 
+	// Managed artifact and agent resources carry session authority. Expanding
+	// either into a subprocess command would let that subprocess reopen, replace,
+	// or unlink the managed object by pathname. Keep those resources behind the
+	// internal reader boundary.
+	if (scheme === "artifact" || scheme === "agent") {
+		throw new ToolError(
+			`${scheme}:// URLs cannot be expanded in bash commands; read them through the internal reader instead.`,
+		);
+	}
+
 	if (scheme === "local") {
 		if (!localOptions) {
 			throw new ToolError(
 				"Cannot resolve local:// URL in bash command: local protocol options are unavailable for this session.",
 			);
 		}
+		await initializeLocalRoot(localOptions);
 		const resolvedLocalPath = resolveLocalUrlToPath(url, localOptions);
 		if (ensureLocalParentDirs) {
 			await fs.mkdir(path.dirname(resolvedLocalPath), { recursive: true });
@@ -215,8 +226,8 @@ export function expandSkillUrls(command: string, skills: readonly Skill[]): stri
 }
 
 /**
- * Expand supported internal URLs in a bash command string to shell-escaped absolute paths.
- * Supported schemes: skill://, agent://, artifact://, memory://, rule://, local://
+ * Expand filesystem-safe internal URLs in a bash command string. `agent://` and
+ * `artifact://` remain internal-reader-only and are rejected before resolution.
  */
 export async function expandInternalUrls(command: string, options: InternalUrlExpansionOptions): Promise<string> {
 	if (!command.includes("://") && !command.includes("local:/")) return command;

package/src/tools/bash.ts

@@ -636,6 +636,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			internalRouter: InternalUrlRouter.instance(),
 			localOptions: {
 				getArtifactsDir: this.session.getArtifactsDir,
+				isManagedDestination: this.session.isManagedSessionDestination,
 				getSessionId: this.session.getSessionId,
 			},
 		};
@@ -643,7 +644,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			...internalUrlOptions,
 			ensureLocalParentDirs: this.session.bashRestrictionProfile !== "read-only",
 		});
-		const sessionFile = this.session.getSessionFile?.() ?? null;
 		const expandedEnv = env
 			? Object.fromEntries(
 					await Promise.all(
@@ -662,7 +662,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			: undefined;
 		const resolvedEnv = {
 			...buildGjcRuntimeSessionEnv({
-				sessionFile,
+				sessionFile: null,
 				sessionId: this.session.getSessionId?.(),
 				cwd: this.session.cwd,
 			}),

package/src/tools/browser/launch.ts

@@ -1,7 +1,9 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { $which, getPuppeteerDir, logger } from "@gajae-code/utils";
+import { getPuppeteerDir } from "@gajae-code/utils/dirs";
+import * as logger from "@gajae-code/utils/logger";
+import { $which } from "@gajae-code/utils/which";
 import * as browsers from "@puppeteer/browsers";
 import type { Browser, CDPSession, Page, default as Puppeteer, Target } from "puppeteer-core";
 import { PUPPETEER_REVISIONS } from "puppeteer-core/internal/revisions.js";

package/src/tools/browser/readable.ts

@@ -1,6 +1,6 @@
 import { Readability } from "@mozilla/readability";
 import { parseHtmlLazy } from "../../utils/linkedom";
-import { htmlToBasicMarkdown } from "../../web/scrapers/types";
+import { htmlToBasicMarkdown } from "../../web/scrapers/html-to-markdown";
 
 export type ReadableFormat = "text" | "markdown";
 

package/src/tools/browser/screenshot-format.ts

@@ -0,0 +1,34 @@
+import * as os from "node:os";
+
+import { formatDimensionNote, type ResizedImage } from "../../utils/image-resize";
+
+function shortenPath(filePath: string): string {
+	const home = os.homedir();
+	return home && filePath.startsWith(home) ? `~${filePath.slice(home.length)}` : filePath;
+}
+
+export function formatScreenshot(opts: {
+	saveFullRes: boolean;
+	savedMimeType: string;
+	savedByteLength: number;
+	dest: string;
+	resized: ResizedImage;
+}): string[] {
+	const lines = ["Screenshot captured"];
+	if (opts.saveFullRes) {
+		lines.push(
+			`Saved: ${opts.savedMimeType} (${(opts.savedByteLength / 1024).toFixed(2)} KB) to ${shortenPath(opts.dest)}`,
+		);
+		lines.push(
+			`Model: ${opts.resized.mimeType} (${(opts.resized.buffer.length / 1024).toFixed(2)} KB, ${opts.resized.width}x${opts.resized.height})`,
+		);
+	} else {
+		lines.push(`Format: ${opts.resized.mimeType} (${(opts.resized.buffer.length / 1024).toFixed(2)} KB)`);
+		lines.push(`Dimensions: ${opts.resized.width}x${opts.resized.height}`);
+	}
+	const dimensionNote = formatDimensionNote(opts.resized);
+	if (dimensionNote) {
+		lines.push(dimensionNote);
+	}
+	return lines;
+}

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

@@ -63,6 +63,7 @@ export type WorkerInitPayload =
 export type ToolReply = { ok: true; value: unknown } | { ok: false; error: RunErrorPayload };
 
 export type WorkerInbound =
+	| { type: "bootstrap"; version: 1; mode: "native-free" }
 	| { type: "init"; payload: WorkerInitPayload }
 	| { type: "run"; id: string; name: string; code: string; timeoutMs: number; session: SessionSnapshot }
 	| { type: "abort"; id: string }
@@ -91,6 +92,8 @@ export interface RunErrorPayload {
 }
 
 export type WorkerOutbound =
+	| { type: "bootstrap-ready"; version: 1; mode: "native-free" }
+	| { type: "bootstrap-failed"; error: string }
 	| { type: "ready"; info: ReadyInfo }
 	| { type: "init-failed"; error: RunErrorPayload }
 	| { type: "result"; id: string; ok: true; payload: RunResultOk }

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

@@ -19,7 +19,6 @@ import type {
 	RunResultOk,
 	SessionSnapshot,
 	Transferable,
-	Transport,
 	WorkerInbound,
 	WorkerInitPayload,
 	WorkerOutbound,
@@ -38,8 +37,8 @@ interface WorkerHandle {
 	send(msg: WorkerInbound, transferList?: Transferable[]): void;
 	onMessage(handler: (msg: WorkerOutbound) => void): () => void;
 	onError(handler: (error: Error) => void): () => void;
+	onClose(handler: () => void): () => void;
 	terminate(): Promise<void>;
-	readonly mode: "worker" | "inline";
 }
 
 export type DialogPolicy = "accept" | "dismiss";
@@ -118,6 +117,13 @@ let workerInitializerForTest:
 	| ((worker: WorkerHandle, payload: WorkerInitPayload, timeoutMs: number) => Promise<ReadyInfo>)
 	| undefined;
 const GRACE_MS = 750;
+const TAB_WORKER_MODE = "native-free";
+
+function startupError(stage: string): ToolError {
+	return new ToolError(
+		`Tab worker startup failed (stage=${stage}, mode=${TAB_WORKER_MODE}, platform=${process.platform}).`,
+	);
+}
 
 interface DeadTabDescriptor {
 	tab: TabSession;
@@ -152,7 +158,7 @@ async function awaitWithinBudget(op: Promise<unknown>, remainingMs: number, labe
 		logger.debug("close teardown budget already spent; detaching step", { label });
 		return false;
 	}
-	let timer: ReturnType<typeof setTimeout> | undefined;
+	let timer: NodeJS.Timeout | undefined;
 	const timedOut = new Promise<boolean>(resolve => {
 		timer = setTimeout(() => resolve(false), remainingMs);
 	});
@@ -358,64 +364,69 @@ export async function acquireTab(
 		if (replacementHold) await releaseBrowser(browser, { kill: false });
 		throw error;
 	}
-	let worker = await spawnAcquireWorker();
-	let info: ReadyInfo;
+	let worker: WorkerHandle;
 	try {
-		info = await initializeAcquireWorker(worker, initPayload, opts.timeoutMs + GRACE_MS);
-	} catch (error) {
-		// `BuildMessage`-class failures arrive asynchronously via the worker's `error` event,
-		// after `spawnTabWorker`'s synchronous try/catch has already returned. Fall back to
-		// the inline worker here so module-resolution failures don't poison every tab open.
-		await worker.terminate().catch(() => undefined);
-		if (worker.mode === "inline") {
-			if (replacementHold) await releaseBrowser(browser, { kill: false });
-			else if (browser.refCount === 0) await releaseBrowser(browser, { kill: false });
-			throw error;
-		}
-		logger.warn("Tab worker init failed; retrying with inline tab worker (no sync-loop guard)", {
-			error: error instanceof Error ? error.message : String(error),
-		});
-		worker = await (workerFactoryForTest?.() ?? spawnInlineWorker());
-		try {
-			info = await initializeAcquireWorker(worker, initPayload, opts.timeoutMs + GRACE_MS);
-		} catch (inlineError) {
-			await worker.terminate().catch(() => undefined);
-			if (replacementHold) await releaseBrowser(browser, { kill: false });
-			else if (browser.refCount === 0) await releaseBrowser(browser, { kill: false });
-			const finalError = new ToolError(
-				`Failed to start browser tab worker (inline fallback also failed): ${inlineError instanceof Error ? inlineError.message : String(inlineError)}`,
-			);
-			(finalError as { cause?: unknown }).cause = error;
-			throw finalError;
+		worker = await spawnAcquireWorker();
+	} catch {
+		if (replacementHold) await releaseBrowser(browser, { kill: false });
+		else if (browser.refCount === 0) await releaseBrowser(browser, { kill: false });
+		throw startupError("spawn");
+	}
+	let registeredTab: TabSession | undefined;
+	let startupFailure: Error | undefined;
+	let browserHeld = false;
+	const observeFailure = (error: Error): void => {
+		if (registeredTab) markTabDead(registeredTab, error);
+		else startupFailure ??= error;
+	};
+	const unlistenLifetimeMessages = worker.onMessage(msg => {
+		if (msg.type === "closed") observeFailure(startupError("protocol-closed"));
+	});
+	const unlistenLifetimeErrors = worker.onError(() => observeFailure(startupError("error")));
+	const unlistenLifetimeClose = worker.onClose(() => observeFailure(startupError("physical-close")));
+	try {
+		const info = await initializeAcquireWorker(worker, initPayload, opts.timeoutMs + GRACE_MS);
+		afterWorkerInitializationForTest?.(name);
+		if (startupFailure) throw startupFailure;
+		if (opts.requireVacantName && tabs.has(name))
+			throw new ToolError(`Tab ${JSON.stringify(name)} was replaced during recovery.`);
+
+		holdBrowser(browser);
+		browserHeld = true;
+		if (replacementHold) {
+			await releaseBrowser(browser, { kill: false });
+			replacementHold = false;
 		}
-	}
-
-	afterWorkerInitializationForTest?.(name);
-	if (opts.requireVacantName && tabs.has(name)) {
+		if (startupFailure) throw startupFailure;
+
+		const tab: TabSession = {
+			name,
+			browser,
+			targetId: info.targetId,
+			worker,
+			state: "alive",
+			info,
+			pending: new Map(),
+			dialogPolicy: opts.dialogs,
+			kindTag: browser.kind.kind,
+			ownerId: opts.ownerId,
+			lastUsedAt: Date.now(),
+			recoveryOpts: freezeRecoveryOptions(opts),
+		};
+		registeredTab = tab;
+		worker.onMessage(msg => handleTabMessage(tab, msg));
+		tabs.set(name, tab);
+		return { tab, created: true };
+	} catch (error) {
+		unlistenLifetimeMessages();
+		unlistenLifetimeErrors();
+		unlistenLifetimeClose();
 		await worker.terminate().catch(() => undefined);
+		if (browserHeld) await releaseBrowser(browser, { kill: false });
 		if (replacementHold) await releaseBrowser(browser, { kill: false });
-		throw new ToolError(`Tab ${JSON.stringify(name)} was replaced during recovery.`);
+		else if (!browserHeld && browser.refCount === 0) await releaseBrowser(browser, { kill: false });
+		throw error;
 	}
-	holdBrowser(browser);
-	if (replacementHold) await releaseBrowser(browser, { kill: false });
-	const tab: TabSession = {
-		name,
-		browser,
-		targetId: info.targetId,
-		worker,
-		state: "alive",
-		info,
-		pending: new Map(),
-		dialogPolicy: opts.dialogs,
-		kindTag: browser.kind.kind,
-		ownerId: opts.ownerId,
-		lastUsedAt: Date.now(),
-		recoveryOpts: freezeRecoveryOptions(opts),
-	};
-	worker.onMessage(msg => handleTabMessage(tab, msg));
-	worker.onError(error => markTabDead(tab, error));
-	tabs.set(name, tab);
-	return { tab, created: true };
 }
 
 export async function runInTab(name: string, opts: RunInTabOptions): Promise<RunResultOk> {
@@ -871,22 +882,14 @@ async function raceWithTimeout<T>(
 }
 
 async function spawnTabWorker(): Promise<WorkerHandle> {
-	try {
-		const worker = isCompiledBinary()
-			? new Worker("./packages/coding-agent/src/tools/browser/tab-worker-entry.ts", { type: "module" })
-			: new Worker(new URL("./tab-worker-entry.ts", import.meta.url).href, { type: "module" });
-		return wrapBunWorker(worker);
-	} catch (err) {
-		logger.warn("Bun Worker spawn failed; using inline tab worker (no sync-loop guard)", {
-			error: err instanceof Error ? err.message : String(err),
-		});
-		return spawnInlineWorker();
-	}
+	const worker = isCompiledBinary()
+		? new Worker("./packages/coding-agent/src/tools/browser/tab-worker-entry.ts", { type: "module" })
+		: new Worker(new URL("./tab-worker-entry.ts", import.meta.url).href, { type: "module" });
+	return wrapBunWorker(worker);
 }
 
 function wrapBunWorker(worker: Worker): WorkerHandle {
 	return {
-		mode: "worker",
 		send(msg, transferList) {
 			worker.postMessage(msg, { transfer: transferList ?? [] });
 		},
@@ -896,9 +899,8 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
 			return () => worker.removeEventListener("message", wrap);
 		},
 		onError(handler) {
-			const onError = (event: ErrorEvent): void => handler(errorFromWorkerEvent(event));
-			const onMessageError = (event: MessageEvent): void =>
-				handler(new ToolError(`Tab worker message error: ${String(event.data)}`));
+			const onError = (): void => handler(startupError("error"));
+			const onMessageError = (): void => handler(startupError("messageerror"));
 			worker.addEventListener("error", onError);
 			worker.addEventListener("messageerror", onMessageError);
 			return () => {
@@ -906,69 +908,76 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
 				worker.removeEventListener("messageerror", onMessageError);
 			};
 		},
+		onClose(handler) {
+			const onClose = (): void => handler();
+			worker.addEventListener("close", onClose);
+			return () => worker.removeEventListener("close", onClose);
+		},
 		async terminate() {
 			worker.terminate();
 		},
 	};
 }
 
-/**
- * Inline fallback for environments where Bun cannot compile or spawn the worker
- * entry. This preserves normal browser behavior but cannot interrupt synchronous
- * infinite loops because user code runs on the main thread.
- */
-async function spawnInlineWorker(): Promise<WorkerHandle> {
-	const hostListeners = new Set<(message: WorkerOutbound) => void>();
-	const workerListeners = new Set<(message: WorkerInbound) => void>();
-	const workerTransport: Transport = {
-		send: msg =>
-			queueMicrotask(() => {
-				for (const listener of hostListeners) listener(msg as WorkerOutbound);
-			}),
-		onMessage: handler => {
-			const typed = handler as (message: WorkerInbound) => void;
-			workerListeners.add(typed);
-			return () => workerListeners.delete(typed);
-		},
-		close: () => {},
-	};
-	const { WorkerCore } = await import("./tab-worker");
-	new WorkerCore(workerTransport);
-	return {
-		mode: "inline",
-		send: msg =>
-			queueMicrotask(() => {
-				for (const listener of workerListeners) listener(msg);
-			}),
-		onMessage: handler => {
-			hostListeners.add(handler);
-			return () => hostListeners.delete(handler);
-		},
-		onError: () => () => {},
-		async terminate() {},
-	};
-}
-
 async function initializeTabWorker(
 	worker: WorkerHandle,
 	payload: WorkerInitPayload,
 	timeoutMs: number,
 ): Promise<ReadyInfo> {
-	const { promise, resolve, reject } = Promise.withResolvers<ReadyInfo>();
+	type StartupPhase = "await-bootstrap" | "bootstrap-confirmed" | "await-init";
+	let phase: StartupPhase = "await-bootstrap";
+	const { promise: bootstrap, resolve: bootstrapReady, reject: rejectBootstrap } = Promise.withResolvers<void>();
+	const { promise: initialized, resolve: ready, reject: rejectInitialized } = Promise.withResolvers<ReadyInfo>();
+	void initialized.catch(() => undefined);
+	const fail = (stage: string): void => {
+		const error = startupError(stage);
+		rejectBootstrap(error);
+		rejectInitialized(error);
+	};
 	const unlisten = worker.onMessage(msg => {
-		if (msg.type === "ready") resolve(msg.info);
-		else if (msg.type === "init-failed") reject(errorFromPayload(msg.error));
-		else if (msg.type === "log") logWorkerMessage(msg);
-	});
-	const unlistenError = worker.onError(error => {
-		reject(new ToolError(`Tab worker failed during startup: ${error.message}`));
+		if (msg.type === "log") {
+			logWorkerMessage(msg);
+			return;
+		}
+		if (phase === "await-bootstrap") {
+			if (msg.type === "bootstrap-ready" && msg.version === 1 && msg.mode === TAB_WORKER_MODE) {
+				phase = "bootstrap-confirmed";
+				bootstrapReady();
+			} else if (msg.type === "bootstrap-failed") {
+				fail("bootstrap");
+			} else if (msg.type === "closed") {
+				fail("protocol-closed");
+			} else {
+				fail("protocol-phase");
+			}
+			return;
+		}
+		if (phase !== "await-init") {
+			fail("protocol-phase");
+			return;
+		}
+		if (msg.type === "ready") {
+			ready(msg.info);
+		} else if (msg.type === "init-failed") {
+			fail("init");
+		} else if (msg.type === "closed") {
+			fail("protocol-closed");
+		} else {
+			fail("protocol-phase");
+		}
 	});
+	const unlistenError = worker.onError(() => fail("error"));
+	const unlistenClose = worker.onClose(() => fail("physical-close"));
 	try {
+		worker.send({ type: "bootstrap", version: 1, mode: TAB_WORKER_MODE });
+		await raceWithTimeout(bootstrap, timeoutMs, startupError("bootstrap-timeout").message);
+		phase = "await-init";
 		worker.send({ type: "init", payload });
-		return await raceWithTimeout(promise, timeoutMs, "Timed out initializing browser tab worker");
+		return await raceWithTimeout(initialized, timeoutMs, startupError("init-timeout").message);
 	} finally {
 		unlisten();
 		unlistenError();
+		unlistenClose();
 	}
 }
 
@@ -979,9 +988,3 @@ export function initializeTabWorkerForTest(
 ): Promise<ReadyInfo> {
 	return initializeTabWorker(worker, payload, timeoutMs);
 }
-
-function errorFromWorkerEvent(event: ErrorEvent): Error {
-	if (event.error instanceof Error) return event.error;
-	if (event.message) return new Error(event.message);
-	return new Error("Unknown tab worker error");
-}