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

package/src/task/executor.ts

@@ -15,6 +15,7 @@ import {
 	formatModelSelectorValue,
 	formatModelStringWithRouting,
 	resolveAgentPrewalkPattern,
+	resolveConfiguredModelPatterns,
 	resolveModelOverride,
 	resolveModelOverrideWithAuthFallback,
 } from "../config/model-resolver";
@@ -161,22 +162,44 @@ function resolveSubagentRetryFallbackCandidates(
 	return candidates;
 }
 
+function resolveSubagentDefaultRetryFallbackChain(settings: Settings): string[] | undefined {
+	const fallbackChain = settings.get("retry.fallbackChains")?.default;
+	if (
+		!Array.isArray(fallbackChain) ||
+		fallbackChain.length === 0 ||
+		!fallbackChain.every(entry => typeof entry === "string")
+	) {
+		return undefined;
+	}
+	return fallbackChain;
+}
+
 function installSubagentRetryFallbackChain(args: {
 	settings: Settings;
 	id: string;
 	candidates: SubagentRetryFallbackCandidate[];
+	defaultFallbackChain: string[] | undefined;
 	model: Model<Api> | undefined;
 	authFallbackUsed: boolean;
 }): string | undefined {
-	const { settings, id, candidates, model, authFallbackUsed } = args;
-	if (!model || authFallbackUsed || candidates.length <= 1) return undefined;
+	const { settings, id, candidates, defaultFallbackChain, model, authFallbackUsed } = args;
+	if (!model || authFallbackUsed || candidates.length === 0) return undefined;
 
 	const selectedIndex = candidates.findIndex(
 		candidate => candidate.model.provider === model.provider && candidate.model.id === model.id,
 	);
 	if (selectedIndex < 0) return undefined;
 	const fallbackSelectors = candidates.slice(selectedIndex + 1).map(candidate => candidate.selector);
-	if (fallbackSelectors.length === 0) return undefined;
+	const existingFallbackChains = settings.get("retry.fallbackChains");
+	// A single explicit model may reuse a configured default chain, but never an implicit parent fallback.
+	const fallbackChain = fallbackSelectors.length > 0 ? fallbackSelectors : defaultFallbackChain;
+	if (
+		!Array.isArray(fallbackChain) ||
+		fallbackChain.length === 0 ||
+		!fallbackChain.every(entry => typeof entry === "string")
+	) {
+		return undefined;
+	}
 
 	const role = `${SUBAGENT_RETRY_FALLBACK_ROLE_PREFIX}${id}`;
 	const modelRoles: Record<string, string> = {};
@@ -189,10 +212,10 @@ function installSubagentRetryFallbackChain(args: {
 	}
 	modelRoles[role] = candidates[selectedIndex].selector;
 	settings.override("modelRoles", modelRoles);
+	// Insert the task-specific role first so another role assigned to the same model cannot capture fallback routing.
 	const fallbackChains: Record<string, string[]> = {
-		[role]: fallbackSelectors,
+		[role]: fallbackChain,
 	};
-	const existingFallbackChains = settings.get("retry.fallbackChains");
 	for (const existingRole in existingFallbackChains) {
 		if (existingRole !== role) {
 			fallbackChains[existingRole] = existingFallbackChains[existingRole];
@@ -914,7 +937,7 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 	const finalOutputChunks: string[] = [];
 	const RECENT_OUTPUT_TAIL_BYTES = 8 * 1024;
 	let recentOutputTail = "";
-	let tailLastLineRepresentable = false;
+	let recentOutputDirty = false;
 	let resolved = false;
 	let abortSent = false;
 	let abortReason: AbortReason | undefined;
@@ -1054,7 +1077,22 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 	let lastProgressEmitMs = 0;
 	let progressTimeoutId: NodeJS.Timeout | null = null;
 
+	// Recompute progress.recentOutput from the capped tail. Deferred: text_delta
+	// appends only extend the tail and mark it dirty; the (up to 8KB) split/filter
+	// runs synchronously here, immediately before the ONLY places the progress
+	// object is snapshotted ({...progress} for onProgress and the eventBus
+	// progress channel, both inside emitProgressNow — including the
+	// scheduleProgress(flush) finalize/error/cancel paths). Observers therefore
+	// always see exact state; no staleness beyond the existing 150ms coalescing.
+	const refreshRecentOutput = () => {
+		if (!recentOutputDirty) return;
+		recentOutputDirty = false;
+		const filtered = recentOutputTail.split("\n").filter(line => line.trim());
+		progress.recentOutput = filtered.slice(-8).reverse();
+	};
+
 	const emitProgressNow = () => {
+		refreshRecentOutput();
 		progress.durationMs = Date.now() - startTime;
 		onProgress?.({ ...progress });
 		const activityGist =
@@ -1137,36 +1175,16 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 		return message.usage;
 	};
 
-	const updateRecentOutputLines = () => {
-		const lines = recentOutputTail.split("\n");
-		const filtered = lines.filter(line => line.trim());
-		progress.recentOutput = filtered.slice(-8).reverse();
-		// The tail's last raw segment (after its final newline) is "represented"
-		// in recentOutput only when it trims non-empty — an empty/whitespace-only
-		// trailing segment is filtered out, so recentOutput[0] is then the line
-		// before it, not the tail's true last line.
-		tailLastLineRepresentable = lines[lines.length - 1].trim().length > 0;
-	};
-
 	const appendRecentOutputTail = (text: string) => {
 		if (!text) return;
 		recentOutputTail += text;
-		const truncated = recentOutputTail.length > RECENT_OUTPUT_TAIL_BYTES;
-		if (truncated) {
+		if (recentOutputTail.length > RECENT_OUTPUT_TAIL_BYTES) {
 			recentOutputTail = recentOutputTail.slice(-RECENT_OUTPUT_TAIL_BYTES);
 		}
-		// Fast path: a token without a newline only extends the current last line.
-		// This runs on every text_delta token (hundreds/thousands per second while
-		// streaming), so skip re-splitting the whole (up to 8KB) tail unless the line
-		// structure actually changed. Requires no truncation AND the tail's last line
-		// already represented (trims non-empty) — otherwise boundaries shift and a
-		// full recompute is required. Appending to a non-empty line keeps it non-empty,
-		// so the flag stays valid across consecutive fast-path tokens.
-		if (truncated || text.includes("\n") || !tailLastLineRepresentable || progress.recentOutput.length === 0) {
-			updateRecentOutputLines();
-		} else {
-			progress.recentOutput = [progress.recentOutput[0] + text, ...progress.recentOutput.slice(1)];
-		}
+		// O(chunk) hot path: this runs on every text_delta token (hundreds/
+		// thousands per second while streaming). Line reconstruction is deferred
+		// to refreshRecentOutput() at the emit boundary.
+		recentOutputDirty = true;
 	};
 
 	const replaceRecentOutputFromContent = (content: unknown[]) => {
@@ -1181,12 +1199,12 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 				recentOutputTail = recentOutputTail.slice(-RECENT_OUTPUT_TAIL_BYTES);
 			}
 		}
-		updateRecentOutputLines();
+		recentOutputDirty = true;
 	};
 
 	const resetRecentOutput = () => {
 		recentOutputTail = "";
-		tailLastLineRepresentable = false;
+		recentOutputDirty = false;
 		progress.recentOutput = [];
 	};
 
@@ -2319,6 +2337,11 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			}
 			checkAbort();
 
+			const configuredModelPatterns = resolveConfiguredModelPatterns(modelPatterns, settings);
+			const defaultRetryFallbackChain =
+				configuredModelPatterns.length === 1
+					? resolveSubagentDefaultRetryFallbackChain(subagentSettings)
+					: undefined;
 			const {
 				model,
 				thinkingLevel: resolvedThinkingLevel,
@@ -2352,6 +2375,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				settings: subagentSettings,
 				id,
 				candidates: resolveSubagentRetryFallbackCandidates(modelPatterns, modelRegistry, settings),
+				defaultFallbackChain: defaultRetryFallbackChain,
 				model,
 				authFallbackUsed,
 			});
@@ -2479,6 +2503,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					model || modelOverride === undefined ? undefined : options.parentActiveModelPattern,
 				modelPatternFallbackRole:
 					model || modelOverride === undefined ? undefined : `${SUBAGENT_RETRY_FALLBACK_ROLE_PREFIX}${id}`,
+				modelPatternDefaultFallbackChain:
+					model || modelOverride === undefined ? undefined : defaultRetryFallbackChain,
 				thinkingLevel: effectiveThinkingLevel,
 				toolNames,
 				outputSchema,

package/src/task/index.ts

@@ -21,6 +21,7 @@ import type { ToolSession } from "..";
 import type { Theme } from "../modes/theme/theme";
 import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.md" with { type: "text" };
 import taskDescriptionTemplate from "../prompts/tools/task.md" with { type: "text" };
+import taskAsyncContractTemplate from "../prompts/tools/task-async-contract.md" with { type: "text" };
 import taskSummaryTemplate from "../prompts/tools/task-summary.md" with { type: "text" };
 import { truncateForPrompt } from "../tools/approval";
 import { isIrcEnabled } from "../tools/hub";
@@ -894,14 +895,16 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			failedSchedules.length > 0
 				? ` Failed to schedule ${failedSchedules.length} spawn${failedSchedules.length === 1 ? "" : "s"}: ${failedSchedules.join("; ")}.`
 				: "";
-		const coordinationHint =
+		const coordinationHint = [
 			started.length === 1
 				? ircEnabled
 					? `DM \`${started[0].agentId}\` via \`hub\` send to coordinate while it runs; use \`hub\` only to inspect (\`jobs\`), wait, or cancel a stuck task.`
 					: `Use \`hub\` to inspect (\`jobs\`), wait, or cancel a stuck task.`
 				: ircEnabled
 					? `DM these ids via \`hub\` send to coordinate while they run; use \`hub\` only to inspect (\`jobs\`), wait, or cancel a stuck task.`
-					: `Use \`hub\` to inspect (\`jobs\`), wait, or cancel a stuck task by id.`;
+					: `Use \`hub\` to inspect (\`jobs\`), wait, or cancel a stuck task by id.`,
+			taskAsyncContractTemplate.trim(),
+		].join("\n");
 
 		if (syncSpawns.length === 0) {
 			if (spawns.length === 1) {
@@ -915,7 +918,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						content: [
 							{
 								type: "text",
-								text: `Spawned agent \`${agentId}\` (job \`${jobId}\`). The result will be delivered when it yields. ${coordinationHint}`,
+								text: `Spawned agent \`${agentId}\` (job \`${jobId}\`). Its result auto-delivers on yield unless a settled \`hub jobs\`/\`wait\` snapshot consumes it first. ${coordinationHint}`,
 							},
 						],
 						details: buildAsyncDetails(),
@@ -932,7 +935,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					content: [
 						{
 							type: "text",
-							text: `Spawned ${started.length} background agents using ${agentLabel}.${scheduleFailureSummary} Each result will be delivered when that agent yields.\n${startedListing}\n${coordinationHint}`,
+							text: `Spawned ${started.length} background agents using ${agentLabel}.${scheduleFailureSummary} Each result auto-delivers on yield unless a settled \`hub jobs\`/\`wait\` snapshot consumes it first.\n${startedListing}\n${coordinationHint}`,
 						},
 					],
 					details: buildAsyncDetails(),
@@ -997,7 +1000,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 
 		const spawnedSummary =
 			started.length > 0
-				? `Spawned ${started.length} background agent${started.length === 1 ? "" : "s"}.${scheduleFailureSummary} Each result will be delivered when that agent yields.\n${started.map(({ agentId, jobId }) => `- \`${agentId}\` (job \`${jobId}\`)`).join("\n")}\n${coordinationHint}`
+				? `Spawned ${started.length} background agent${started.length === 1 ? "" : "s"}.${scheduleFailureSummary} Each result auto-delivers on yield unless a settled \`hub jobs\`/\`wait\` snapshot consumes it first.\n${started.map(({ agentId, jobId }) => `- \`${agentId}\` (job \`${jobId}\`)`).join("\n")}\n${coordinationHint}`
 				: scheduleFailureSummary.trim();
 		const text = [merged.contentParts.join("\n\n"), spawnedSummary]
 			.filter(section => section.trim().length > 0)
@@ -1078,12 +1081,41 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				try {
 					markRunning();
 					progress.status = "running";
-					await reportProgress(`Running background task ${agentId}...`);
+					await reportProgress(
+						`Running background task ${agentId}...`,
+						buildDetails() as unknown as Record<string, unknown>,
+					);
+					const forwardSyncProgress: AgentToolUpdateCallback<TaskToolDetails> = async update => {
+						const nextProgress = update.details?.progress?.[0];
+						if (nextProgress) {
+							// The job body owns status and identity (id/index/agent);
+							// copy only the live metrics the subagent streams so the
+							// polling row reflects the resolved model, reasoning level,
+							// and running counters without reverting the "running"
+							// status back to the subagent's initial "pending" snapshot.
+							progress.resolvedModel = nextProgress.resolvedModel;
+							progress.tokens = nextProgress.tokens;
+							progress.requests = nextProgress.requests;
+							progress.contextTokens = nextProgress.contextTokens;
+							progress.contextWindow = nextProgress.contextWindow;
+							progress.cost = nextProgress.cost;
+							progress.toolCount = nextProgress.toolCount;
+							progress.currentTool = nextProgress.currentTool;
+							progress.lastIntent = nextProgress.lastIntent;
+							progress.recentTools = nextProgress.recentTools.slice();
+							progress.recentOutput = nextProgress.recentOutput.slice();
+							progress.retryState = nextProgress.retryState;
+							progress.retryFailure = nextProgress.retryFailure;
+						}
+						const updateText =
+							update.content.find(part => part.type === "text")?.text ?? `Running background task ${agentId}...`;
+						await reportProgress(updateText, buildDetails() as unknown as Record<string, unknown>);
+					};
 					const result = await this.#executeSync(
 						toolCallId,
 						spawnParams,
 						runSignal,
-						undefined,
+						forwardSyncProgress,
 						agentId,
 						progress.index,
 						true,
@@ -1104,11 +1136,16 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					progress.extractedToolData = singleResult?.extractedToolData;
 					progress.retryFailure = singleResult?.retryFailure;
 					progress.retryState = undefined;
+					if (singleResult?.resolvedModel) {
+						progress.resolvedModel = singleResult.resolvedModel;
+					} else {
+						delete progress.resolvedModel;
+					}
 					onSettled?.(resultFailed);
 					const statusText = resultFailed
 						? `Background task ${agentId} failed.`
 						: `Background task ${agentId} complete.`;
-					await reportProgress(statusText);
+					await reportProgress(statusText, buildDetails() as unknown as Record<string, unknown>);
 					const deliveryText = `${finalText}${buildFollowUpHint(singleResult?.aborted === true)}`;
 					if (resultFailed) {
 						// Mark the job itself failed; the failed agent stays interrogable.
@@ -1123,7 +1160,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					progress.durationMs = Math.max(0, Date.now() - startedAt);
 					onSettled?.(true);
 					const statusText = `Background task ${agentId} failed.`;
-					await reportProgress(statusText);
+					await reportProgress(statusText, buildDetails() as unknown as Record<string, unknown>);
 					const message = error instanceof Error ? error.message : String(error);
 					const hint = AgentRegistry.global().get(agentId) ? buildFollowUpHint(false) : "";
 					throw new TaskJobError(`${message}${hint}`);

package/src/task/worktree.ts

@@ -414,6 +414,8 @@ export async function ensureIsolation(
 	preferred?: IsoBackendKind,
 ): Promise<IsolationHandle> {
 	const repoRoot = await getRepoRoot(baseCwd);
+	const repository = await git.repo.resolve(repoRoot);
+	const sourceCommonDir = repository?.commonDir ?? path.join(repoRoot, ".git");
 	const baseDir = getWorktreeDir(getTaskIsolationSegment(repoRoot, id));
 	const mergedDir = path.join(baseDir, TASK_ISOLATION_MOUNT_DIR);
 	const resolution = natives.isoResolve(preferred ?? null);
@@ -424,6 +426,14 @@ export async function ensureIsolation(
 		await fs.rm(baseDir, { recursive: true, force: true });
 		try {
 			await natives.isoStart(candidate, repoRoot, mergedDir);
+			// Sever the isolation's git metadata from the source checkout. Copy
+			// backends duplicate `repoRoot`'s `.git` verbatim — a linked-worktree
+			// pointer file (or the rcopy `git worktree add` registration) leaves
+			// the isolation sharing the source's HEAD/index/ref namespace, so a
+			// task's git operations would mutate the parent checkout and stack
+			// parallel task branches. Detaching gives each isolation a private,
+			// frozen repo that still borrows the source object DB via alternates.
+			await git.detachGitDir(mergedDir, sourceCommonDir);
 			return {
 				mergedDir,
 				backend: candidate,

package/src/tools/browser/aria/aria-snapshot.ts

@@ -1,4 +1,5 @@
 import type { ElementHandle, JSHandle, Page } from "puppeteer-core";
+import { ToolError } from "../../tool-errors";
 import ariaBundle from "./aria-snapshot.bundle.txt" with { type: "text" };
 // `aria-snapshot.bundle.txt` is a generated, committed artifact: Playwright's
 // injected ARIA-snapshot sources (pinned, Apache-2.0) bundled to a CJS module.
@@ -69,15 +70,41 @@ export async function resolveAriaRefHandle(page: Page, ref: string): Promise<Ele
 const ARIA_REF_PREFIXES = ["aria-ref=", "aria-ref/", "ariaref/"];
 
 /**
- * Recognize the explicit `[ref=eN]` selector forms and return the bare ref id,
- * else null. Accepts `aria-ref=e5` (Playwright-MCP style), `aria-ref/e5`, and
- * `ariaref/e5` — lets `tab.click("aria-ref=e5")` etc. act on snapshot refs. A
- * bare `e5` is intentionally NOT a ref selector: the cmux backend already uses
- * bare `eN`/`@eN` for its own observe ids, so requiring the prefix keeps action
- * selectors meaning the same thing on both backends. (`tab.ref("e5")` still
- * accepts a bare id directly.)
+ * Guard the selector funnels: `tab.click`/`type`/`fill`/`waitFor*`/`scrollIntoView`
+ * take string selectors only, but user `run` code routinely passes the ElementHandle
+ * from `tab.id(n)`/`tab.ref(...)` (or an un-awaited Promise of one) straight in.
+ * Without this the value reaches `.trim()`/`.startsWith()` and throws the opaque,
+ * minified `A.trim is not a function` instead of a recovery-naming ToolError.
+ */
+export function assertSelectorString(selector: unknown): asserts selector is string {
+	if (typeof selector === "string") return;
+	let kind: string;
+	if (selector !== null && typeof selector === "object") {
+		kind =
+			"then" in selector && typeof selector.then === "function" ? "a Promise (missing await?)" : "an ElementHandle";
+	} else {
+		kind = `a ${typeof selector}`;
+	}
+	throw new ToolError(
+		`Browser selector must be a string; got ${kind}. ` +
+			"tab.click/type/fill/waitFor take string selectors only — " +
+			'call the handle method directly (e.g. (await tab.id(n)).click()) or pass a string like "aria-ref=eN".',
+	);
+}
+
+/**
+ * Recognize a snapshot-ref selector and return the bare ref id, else null.
+ * Accepts `aria-ref=e5` (Playwright-MCP style), `aria-ref/e5`, `ariaref/e5`,
+ * and bare `e5`/`@e5`: agents copy ids straight out of the snapshot YAML
+ * (`[ref=e5]`), so `tab.click("e5")` must act on the ref instead of falling
+ * through to a CSS tag selector that can never match. Bare ids are safe to
+ * claim here — an eN tag name is not real HTML, and the tab-worker backend's
+ * observe ids are numeric (`tab.id(7)`), so refs are its only eN namespace.
+ * (The cmux backend parses selectors itself and routes bare `eN` to its own
+ * observe ids; either way `eN` means "the id from the last page dump".)
  */
 export function parseAriaRefSelector(selector: string): string | null {
+	assertSelectorString(selector);
 	const trimmed = selector.trim();
 	for (const prefix of ARIA_REF_PREFIXES) {
 		if (trimmed.startsWith(prefix)) {
@@ -85,7 +112,8 @@ export function parseAriaRefSelector(selector: string): string | null {
 			return /^e\d+$/.test(id) ? id : null;
 		}
 	}
-	return null;
+	const bare = /^@?(e\d+)$/.exec(trimmed);
+	return bare ? bare[1]! : null;
 }
 
 /**

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 =