pi-agent-browser-native 0.2.43 → 0.2.45

package/docs/platform-smoke.md

@@ -6,15 +6,18 @@ This is a release-blocking gate. Missing Crabbox setup, Docker, macOS SSH, the n
 
 ## Required release gate
 
-Run the cheap harness checks first, then the full matrix:
+Run the cheap harness checks first, build the project-owned Ubuntu image, run doctor explicitly, then run the full matrix and inspect the evidence:
 
 ```sh
 npm run check:platform-smoke
 npm run smoke:platform:ubuntu-image
+npm run smoke:platform:doctor
 npm run smoke:platform:all
+crabbox list --provider local-container
+crabbox list --provider parallels
 ```
 
-`smoke:platform:all` runs `smoke:platform:doctor` before any target suite starts. The canonical `npm run verify -- release` gate also runs the same platform doctor and full `macos,ubuntu,windows-native` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without the platform gate.
+`smoke:platform:all` also runs `smoke:platform:doctor` before any target suite starts, so the explicit doctor step is a readable release checklist step rather than a hidden precondition. The canonical `npm run verify -- release` gate also runs the configured-source lifecycle harness, then the same platform doctor and full `macos,ubuntu,windows-native` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without lifecycle and platform gates. After the matrix, inspect `.artifacts/platform-smoke/<run-id>/...` summaries and manifests; a green Crabbox exit without matching suite assertions is not release proof. Use provider-specific `crabbox list` commands for cleanup review because this host may have unrelated Crabbox providers configured that require credentials.
 
 Per-target commands are for diagnosis:
 
@@ -43,7 +46,7 @@ crabbox --version
 crabbox providers
 ```
 
-Use `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` only when testing a non-default Crabbox binary.
+Use Crabbox `0.26.0` or newer. Use `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` only when testing a non-default Crabbox binary.
 
 Standard configuration knobs:
 
@@ -51,9 +54,12 @@ Standard configuration knobs:
 PLATFORM_SMOKE_MAC_HOST=localhost
 PLATFORM_SMOKE_MAC_USER="$USER"
 PLATFORM_SMOKE_MAC_WORK_ROOT="/Users/$USER/crabbox/pi-agent-browser-native"
+# Optional only when localhost SSH does not use port 22.
+PLATFORM_SMOKE_MAC_PORT=22
 
 # Default local image built by npm run smoke:platform:ubuntu-image.
-PLATFORM_SMOKE_UBUNTU_IMAGE="pi-agent-browser-native-platform:node24-agent-browser0.27.1"
+# The tag suffix is derived from scripts/agent-browser-capability-baseline.mjs.
+PLATFORM_SMOKE_UBUNTU_IMAGE="pi-agent-browser-native-platform:node24-agent-browser<baseline-version>"
 
 PLATFORM_SMOKE_WINDOWS_VM="pi-extension-windows-template"
 PLATFORM_SMOKE_WINDOWS_SNAPSHOT="crabbox-ready"
@@ -64,7 +70,7 @@ PLATFORM_SMOKE_WINDOWS_WORK_ROOT="C:\\crabbox\\pi-agent-browser-native"
 PLATFORM_SMOKE_AUTH_ENV=""
 ```
 
-The Ubuntu target image is derived from `node:24-bookworm`, installs `agent-browser@0.27.1`, installs Debian Chromium through apt, creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebuild it after upstream rebaselining, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command.
+The Ubuntu target image is derived from `node:24-bookworm`, installs the `agent-browser` version from [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs), installs Debian Chromium through apt, creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebuild it after upstream rebaselining, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command; a missing tool is image/template drift.
 
 The configured upstream `agent-browser` baseline is imported from [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs). Target-local browser suites verify that exact `agent-browser` version before running. Bake the exact upstream CLI and browser runtime into the Windows template/snapshot for speed and reproducibility; missing or stale Windows `agent-browser` / browser readiness is a blocked setup, not something the smoke command repairs. The Windows browser suite checks the preinstalled browser cache and prewarms one short local file URL before the extension harness runs.
 
@@ -78,7 +84,7 @@ Crabbox does not install project runtime tools. The macOS host, Ubuntu image, an
 - Browser/runtime dependencies needed by upstream `agent-browser`.
 - Native PowerShell and OpenSSH Server on Windows.
 
-For Windows, reuse `pi-extension-windows-template` with the shared canonical `crabbox-ready` power-off snapshot. Do not create one-off project VMs. If a reusable tool is missing, update the shared template, verify from a fresh SSH session, remove caches/secrets/checkouts, shut down cleanly, and promote a known-good power-off snapshot.
+For Windows, reuse `pi-extension-windows-template` with the shared canonical `crabbox-ready` power-off snapshot configured in [`platform-smoke.config.mjs`](../platform-smoke.config.mjs). Do not create one-off project VMs or run tests directly on the source VM. If a reusable tool is missing, update the shared template, verify from a fresh SSH session, remove caches/secrets/checkouts, shut down cleanly, and promote a known-good power-off snapshot.
 
 ## What the suites prove
 
@@ -108,7 +114,7 @@ The dogfood suite intentionally uses the checkout harness while `platform-build`
 
 ## Artifact contract
 
-Every target suite writes host-side evidence under:
+Every target run writes host-side evidence under one run id shared by that target’s suites:
 
 ```text
 .artifacts/platform-smoke/<run-id>/<target>/<suite>/
@@ -117,9 +123,9 @@ Every target suite writes host-side evidence under:
 Required files include:
 
 ```text
-summary.json
+summary.json           # includes ok, target, suite, exit code, elapsed time, writtenAt
 artifact-manifest.json
-target.json
+target.json            # package, package version, Crabbox binary/version, provider, work root/image/template
 suite.json
 command.txt
 exit-code.txt

package/extensions/agent-browser/index.ts

@@ -7,19 +7,14 @@
  */
 
 import type { ChildProcess } from "node:child_process";
-import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
-	highlightCode,
 	isToolCallEventType,
-	keyHint,
 	type AgentToolResult,
 	type ExtensionAPI,
 	type ExtensionContext,
-	type Theme,
-	type ToolResultEvent,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import {
@@ -42,12 +37,12 @@ import {
 	getImplicitSessionIdleTimeoutMs,
 	hasLaunchScopedTabCorrectionFlag,
 	extractExplicitSessionName,
-	redactInvocationArgs,
 	restoreManagedSessionStateFromBranch,
 	resolveManagedSessionState,
 	validateToolArgs,
 	type CompatibilityWorkaround,
 } from "./lib/runtime.js";
+import { isRecord } from "./lib/parsing.js";
 import { buildPromptPolicy, getLatestUserPrompt, shouldAppendBrowserSystemPrompt } from "./lib/prompt-policy.js";
 import { isCloseCommand } from "./lib/command-taxonomy.js";
 import {
@@ -97,6 +92,7 @@ import {
 	type ElectronLaunchRecord,
 } from "./lib/orchestration/electron-host/index.js";
 import { buildValidationFailureResult, resolveAgentBrowserInput } from "./lib/orchestration/input-plan.js";
+import { applyAgentBrowserOutputPath } from "./lib/orchestration/output-file.js";
 import type { NetworkRouteRecord } from "./lib/results/contracts.js";
 import type { SessionArtifactManifest } from "./lib/results/contracts.js";
 import {
@@ -121,153 +117,19 @@ import {
 import { withOptionalSessionArgs } from "./lib/results/next-actions.js";
 import { canRegisterWebSearchTool, loadAgentBrowserConfigSync } from "./lib/config.js";
 import { createAgentBrowserWebSearchTool } from "./lib/web-search.js";
+import {
+	isDirectAgentBrowserBashAllowed,
+	isHarmlessAgentBrowserInspectionCommand,
+	looksLikeDirectAgentBrowserBash,
+} from "./lib/bash-guard.js";
+import {
+	AgentBrowserResultComponent,
+	buildAgentBrowserToolResultPatch,
+	formatAgentBrowserRenderCall,
+	formatAgentBrowserRenderResult,
+} from "./lib/pi-tool-rendering.js";
 
 const DEFAULT_SESSION_MODE = "auto" as const;
-const DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV = "PI_AGENT_BROWSER_ALLOW_DIRECT_BASH";
-const PACKAGE_NAME = "pi-agent-browser-native";
-
-const TUI_COLLAPSED_OUTPUT_MAX_LINES = 10;
-const TUI_INVOCATION_PREVIEW_MAX_CHARS = 120;
-const ANSI_CONTROL_SEQUENCE_PATTERN = /\x1B(?:\][^\x07\x1B]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|P[^\x1B]*(?:\x1B\\)|_[^\x1B]*(?:\x1B\\)|\^[^\x1B]*(?:\x1B\\)|[@-Z\\-_])/g;
-const UNSAFE_DISPLAY_CONTROL_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\x80-\x9F]/g;
-
-function sanitizeDisplayText(text: string): string {
-	return text
-		.replace(ANSI_CONTROL_SEQUENCE_PATTERN, "")
-		.replace(/\r/g, "")
-		.replace(UNSAFE_DISPLAY_CONTROL_PATTERN, "�");
-}
-
-function replaceTabsForDisplay(text: string): string {
-	return text.replaceAll("\t", "    ");
-}
-
-function trimTrailingBlankLines(lines: string[]): string[] {
-	let end = lines.length;
-	while (end > 0 && lines[end - 1].trim().length === 0) {
-		end -= 1;
-	}
-	return lines.slice(0, end);
-}
-
-function isJsonDocumentText(text: string): boolean {
-	const trimmed = text.trim();
-	if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
-		return false;
-	}
-	try {
-		JSON.parse(trimmed);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function getPrimaryTextContent(result: AgentToolResult<unknown>): string {
-	const textContent = result.content.find((item) => item.type === "text");
-	return textContent?.type === "text" ? textContent.text : "";
-}
-
-function colorizeToolOutputLines(text: string, theme: Theme, isError: boolean): string[] {
-	const normalizedLines = trimTrailingBlankLines(replaceTabsForDisplay(sanitizeDisplayText(text)).split("\n"));
-	const normalizedText = normalizedLines.join("\n");
-	if (normalizedText.length === 0) {
-		return [];
-	}
-	if (isJsonDocumentText(normalizedText)) {
-		return highlightCode(normalizedText, "json");
-	}
-	return normalizedLines.map((line) => {
-		if (line.length === 0) {
-			return "";
-		}
-		return isError ? theme.fg("error", line) : theme.fg("toolOutput", line);
-	});
-}
-
-function formatExpandHint(theme: Theme): string {
-	try {
-		return keyHint("app.tools.expand", "to expand");
-	} catch {
-		return `${theme.fg("dim", "ctrl+o")} ${theme.fg("muted", "to expand")}`;
-	}
-}
-
-function formatVisualTruncationNotice(remainingLines: number, totalLines: number, theme: Theme): string {
-	return `${theme.fg("muted", `... (${remainingLines} more lines, ${totalLines} total, `)}${formatExpandHint(theme)}${theme.fg("muted", ")")}`;
-}
-
-function formatAgentBrowserRenderCall(args: unknown, theme: Theme): string {
-	const input = isRecord(args) ? args : {};
-	const semanticAction = compileAgentBrowserSemanticAction(input.semanticAction);
-	const job = compileAgentBrowserJob(input.job);
-	const qa = compileAgentBrowserQaPreset(input.qa);
-	const sourceLookup = compileAgentBrowserSourceLookup(input.sourceLookup);
-	const networkSourceLookup = compileAgentBrowserNetworkSourceLookup(input.networkSourceLookup);
-	const electron = compileAgentBrowserElectron(input.electron);
-	const generatedBatch = networkSourceLookup.compiled ?? sourceLookup.compiled ?? job.compiled ?? qa.compiled;
-	const rawArgs = Array.isArray(input.args)
-		? input.args.filter((value): value is string => typeof value === "string")
-		: electron.compiled
-			? ["electron", electron.compiled.action]
-			: (semanticAction.compiled?.args ?? generatedBatch?.args ?? []);
-	const redactedArgs = redactInvocationArgs(rawArgs);
-	const invocation = sanitizeDisplayText(redactedArgs.join(" ")).replace(/\s+/g, " ").trim();
-	const invocationPreview =
-		invocation.length > TUI_INVOCATION_PREVIEW_MAX_CHARS
-			? `${invocation.slice(0, TUI_INVOCATION_PREVIEW_MAX_CHARS - 3)}...`
-			: invocation;
-	let text = theme.fg("toolTitle", theme.bold("agent_browser"));
-	if (invocationPreview.length > 0) {
-		text += ` ${theme.fg("accent", invocationPreview)}`;
-	}
-	if (input.sessionMode === "fresh") {
-		text += theme.fg("dim", " sessionMode=fresh");
-	}
-	if (typeof input.stdin === "string") {
-		text += theme.fg("dim", " + stdin");
-	}
-	return text;
-}
-
-function formatAgentBrowserRenderResult(
-	result: AgentToolResult<unknown>,
-	options: { expanded: boolean; isPartial: boolean },
-	theme: Theme,
-	isError: boolean,
-): string {
-	if (options.isPartial) {
-		return theme.fg("warning", "Running agent-browser...");
-	}
-
-	const outputText = getPrimaryTextContent(result);
-	const outputLines = colorizeToolOutputLines(outputText, theme, isError);
-	if (outputLines.length === 0) {
-		const details = isRecord(result.details) ? result.details : undefined;
-		const rawSummary = typeof details?.summary === "string" ? details.summary : isError ? "agent-browser failed" : "Done";
-		const sanitizedSummary = sanitizeDisplayText(rawSummary).trim();
-		const summary = sanitizedSummary.length > 0 ? sanitizedSummary : isError ? "agent-browser failed" : "Done";
-		return isError ? theme.fg("error", summary) : theme.fg("success", summary);
-	}
-
-	return `\n${outputLines.join("\n")}`;
-}
-
-function formatModelVisibleFailureCategoryNotice(details: unknown): string | undefined {
-	if (!isRecord(details) || details.resultCategory !== "failure") return undefined;
-	const failureCategory = typeof details.failureCategory === "string" && details.failureCategory.length > 0
-		? details.failureCategory
-		: undefined;
-	return `Result category: failure${failureCategory ? `; failureCategory: ${failureCategory}` : ""}; Pi tool isError: true.`;
-}
-
-type AgentBrowserToolContent = AgentToolResult<unknown>["content"];
-type AgentBrowserToolContentItem = AgentBrowserToolContent[number];
-
-type AgentBrowserToolResultPatch = {
-	content?: AgentBrowserToolContent;
-	isError?: boolean;
-};
 
 type OwnedManagedSession = {
 	branchOwned: boolean;
@@ -283,290 +145,7 @@ interface BranchManagedResourceEvents {
 	managedSessionCloseRanks: Map<string, number>;
 }
 
-function agentBrowserToolResultRequestedJson(event: ToolResultEvent): boolean {
-	const details = isRecord(event.details) ? event.details : undefined;
-	const detailArgs = Array.isArray(details?.args) ? details.args : undefined;
-	const inputArgs = isRecord(event.input) && Array.isArray(event.input.args) ? event.input.args : undefined;
-	return detailArgs?.includes("--json") === true || inputArgs?.includes("--json") === true;
-}
-
-function agentBrowserToolResultHasParseableJsonContent(content: AgentBrowserToolContent): boolean {
-	return content.some((item) => {
-		if (item.type !== "text" || typeof item.text !== "string") return false;
-		const text = item.text.trim();
-		if (text.length === 0) return false;
-		try {
-			JSON.parse(text);
-			return true;
-		} catch {
-			return false;
-		}
-	});
-}
-
-function appendModelVisibleFailureCategoryNotice(content: AgentBrowserToolContent, notice: string): AgentBrowserToolContent | undefined {
-	const noticeContent: AgentBrowserToolContentItem = { type: "text", text: notice };
-	const textIndex = content.findIndex((item) => item.type === "text" && typeof item.text === "string");
-	if (textIndex === -1) return [noticeContent, ...content];
-	const textItem = content[textIndex];
-	if (textItem.type !== "text" || typeof textItem.text !== "string" || textItem.text.includes(notice)) return undefined;
-	return content.map((item, index) => index === textIndex
-		? { ...item, text: `${textItem.text}\n\n${notice}` }
-		: item);
-}
-
-function buildAgentBrowserToolResultPatch(event: ToolResultEvent): AgentBrowserToolResultPatch | undefined {
-	if (event.toolName !== "agent_browser") return undefined;
-	const preservesParseableJson = agentBrowserToolResultRequestedJson(event) && agentBrowserToolResultHasParseableJsonContent(event.content);
-	const notice = preservesParseableJson ? undefined : formatModelVisibleFailureCategoryNotice(event.details);
-	const content = notice ? appendModelVisibleFailureCategoryNotice(event.content, notice) : undefined;
-	const shouldMarkError = isRecord(event.details) && event.details.resultCategory === "failure" && event.isError !== true;
-	if (!shouldMarkError && !content) return undefined;
-	return {
-		...(content ? { content } : {}),
-		...(shouldMarkError ? { isError: true } : {}),
-	};
-}
-
-class AgentBrowserResultComponent {
-	private expanded = false;
-	private theme: Theme | undefined;
-	private readonly text = new Text("", 0, 0);
-
-	setState(value: string, expanded: boolean, theme: Theme): void {
-		this.text.setText(value);
-		this.expanded = expanded;
-		this.theme = theme;
-	}
-
-	render(width: number): string[] {
-		const lines = this.text.render(width);
-		if (this.expanded || lines.length <= TUI_COLLAPSED_OUTPUT_MAX_LINES) {
-			return lines;
-		}
-		const theme = this.theme;
-		if (!theme) {
-			return lines.slice(0, TUI_COLLAPSED_OUTPUT_MAX_LINES);
-		}
-		const hiddenLineCount = lines.length - TUI_COLLAPSED_OUTPUT_MAX_LINES;
-		return [
-			...lines.slice(0, TUI_COLLAPSED_OUTPUT_MAX_LINES),
-			formatVisualTruncationNotice(hiddenLineCount, lines.length, theme),
-		];
-	}
-
-	invalidate(): void {
-		this.text.invalidate();
-	}
-}
-
-
-const DIRECT_AGENT_BROWSER_EXECUTABLE_PATTERN = /^(?:[.~]|\.\.?|\/)?(?:[^\s;&|]+\/)?agent-browser$/;
-const HARMLESS_AGENT_BROWSER_INSPECTION_PATTERN = /^\s*(?:command\s+-v|which|type\s+-P)\s+agent-browser\s*$/;
-
-type ShellQuoteState = 'double' | 'single' | undefined;
-
-function isShellAssignmentToken(token: string): boolean {
-	return /^[A-Za-z_][A-Za-z0-9_]*=/.test(token);
-}
-
-function stripOuterQuotes(token: string): string {
-	if (token.length >= 2 && ((token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'")))) {
-		return token.slice(1, -1);
-	}
-	return token;
-}
-
-function segmentLaunchesAgentBrowser(tokens: string[]): boolean {
-	let index = 0;
-	while (index < tokens.length && isShellAssignmentToken(tokens[index])) {
-		index += 1;
-	}
-	if (index >= tokens.length) {
-		return false;
-	}
-
-	let executableToken = tokens[index];
-	if (executableToken === 'env') {
-		index += 1;
-		while (index < tokens.length && isShellAssignmentToken(tokens[index])) {
-			index += 1;
-		}
-		executableToken = tokens[index] ?? '';
-	}
-	if (executableToken === 'npx' || executableToken === 'bunx') {
-		index += 1;
-		while (index < tokens.length && tokens[index].startsWith('-')) {
-			index += 1;
-		}
-		executableToken = tokens[index] ?? '';
-	}
-	if (executableToken === 'pnpm' || executableToken === 'yarn') {
-		index += 1;
-		if (tokens[index] !== 'dlx') {
-			return false;
-		}
-		index += 1;
-		while (index < tokens.length && tokens[index].startsWith('-')) {
-			index += 1;
-		}
-		executableToken = tokens[index] ?? '';
-	}
-	return DIRECT_AGENT_BROWSER_EXECUTABLE_PATTERN.test(executableToken);
-}
-
-// Best-effort detection for common direct launches only. This is an ergonomics guard,
-// not a general-purpose bash parser or security boundary.
-function looksLikeDirectAgentBrowserBash(command: string): boolean {
-	let currentToken = '';
-	let quoteState: ShellQuoteState;
-	let awaitingHeredocDelimiter: { stripTabs: boolean } | undefined;
-	let pendingHeredoc: { delimiter: string; stripTabs: boolean } | undefined;
-	let pendingHeredocLine = '';
-	let segmentTokens: string[] = [];
-
-	const acceptToken = (token: string) => {
-		if (token.length === 0) {
-			return;
-		}
-		if (awaitingHeredocDelimiter) {
-			pendingHeredoc = {
-				delimiter: stripOuterQuotes(token),
-				stripTabs: awaitingHeredocDelimiter.stripTabs,
-			};
-			awaitingHeredocDelimiter = undefined;
-			return;
-		}
-		segmentTokens.push(token);
-	};
-	const flushToken = () => {
-		acceptToken(currentToken);
-		currentToken = '';
-	};
-	const flushSegment = () => {
-		const launchesAgentBrowser = segmentLaunchesAgentBrowser(segmentTokens);
-		segmentTokens = [];
-		return launchesAgentBrowser;
-	};
-
-	for (let index = 0; index < command.length; index += 1) {
-		const char = command[index];
-		if (pendingHeredoc) {
-			if (char === '\n') {
-				const candidate = pendingHeredoc.stripTabs ? pendingHeredocLine.replace(/^\t+/, '') : pendingHeredocLine;
-				if (candidate === pendingHeredoc.delimiter) {
-					pendingHeredoc = undefined;
-				}
-				pendingHeredocLine = '';
-				continue;
-			}
-			pendingHeredocLine += char;
-			continue;
-		}
-
-		if (quoteState === 'single') {
-			currentToken += char;
-			if (char === "'") {
-				quoteState = undefined;
-			}
-			continue;
-		}
-		if (quoteState === 'double') {
-			currentToken += char;
-			if (char === '\\' && index + 1 < command.length) {
-				currentToken += command[index + 1];
-				index += 1;
-				continue;
-			}
-			if (char === '"') {
-				quoteState = undefined;
-			}
-			continue;
-		}
-		if (char === "'" || char === '"') {
-			currentToken += char;
-			quoteState = char === "'" ? 'single' : 'double';
-			continue;
-		}
-		if (char === '\\' && index + 1 < command.length) {
-			currentToken += char;
-			currentToken += command[index + 1];
-			index += 1;
-			continue;
-		}
-		if (char === '\n') {
-			flushToken();
-			if (flushSegment()) {
-				return true;
-			}
-			continue;
-		}
-		if (/\s/.test(char)) {
-			flushToken();
-			continue;
-		}
-		const threeCharOperator = command.slice(index, index + 3);
-		if (threeCharOperator === '<<-') {
-			flushToken();
-			awaitingHeredocDelimiter = { stripTabs: true };
-			index += 2;
-			continue;
-		}
-		const twoCharOperator = command.slice(index, index + 2);
-		if (twoCharOperator === '<<') {
-			flushToken();
-			awaitingHeredocDelimiter = { stripTabs: false };
-			index += 1;
-			continue;
-		}
-		if (twoCharOperator === '&&' || twoCharOperator === '||') {
-			flushToken();
-			if (flushSegment()) {
-				return true;
-			}
-			index += 1;
-			continue;
-		}
-		if (char === '|' || char === ';' || char === '&') {
-			flushToken();
-			if (flushSegment()) {
-				return true;
-			}
-			continue;
-		}
-		currentToken += char;
-	}
-
-	flushToken();
-	return flushSegment();
-}
-
-function isHarmlessAgentBrowserInspectionCommand(command: string): boolean {
-	return HARMLESS_AGENT_BROWSER_INSPECTION_PATTERN.test(command);
-}
-
-function isTruthyEnvValue(value: string | undefined): boolean {
-	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
-}
-
-async function isPackageDevelopmentCwd(cwd: string): Promise<boolean> {
-	try {
-		const packageJson = JSON.parse(await readFile(join(cwd, "package.json"), "utf8")) as { name?: unknown };
-		return packageJson.name === PACKAGE_NAME;
-	} catch {
-		return false;
-	}
-}
-
-async function isDirectAgentBrowserBashAllowed(cwd: string): Promise<boolean> {
-	return isTruthyEnvValue(process.env[DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV]) || await isPackageDevelopmentCwd(cwd);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
-function getBatchAnnotateValidationError(args: string[], stdin: string | undefined): string | undefined {
+function getBatchPreflightValidationError(args: string[], stdin: string | undefined): string | undefined {
 	const commandTokens = extractCommandTokens(args);
 	if (commandTokens[0] !== "batch" || stdin === undefined) {
 		return undefined;
@@ -575,14 +154,18 @@ function getBatchAnnotateValidationError(args: string[], stdin: string | undefin
 	if (parsed.error || parsed.steps === undefined) {
 		return undefined;
 	}
-	const badStepIndex = parsed.steps.findIndex((step) => Array.isArray(step) && step[0] === "screenshot" && step.includes("--annotate"));
-	if (badStepIndex < 0) {
-		return undefined;
+	for (const [index, step] of parsed.steps.entries()) {
+		if (!Array.isArray(step) || !step.every((token) => typeof token === "string") || step.length === 0) continue;
+		const stepValidationError = validateToolArgs(step);
+		if (stepValidationError) return `Unsupported batch step ${index + 1}: ${stepValidationError}`;
+		if (step[0] === "screenshot" && step.includes("--annotate")) {
+			return [
+				`Unsupported batch screenshot annotation in step ${index + 1}: put --annotate in top-level args, not inside the batch step.`,
+				`Use: { "args": ["--annotate", "batch"], "stdin": "[[\\"screenshot\\",\\"/path/to/image.png\\"]]" }`,
+			].join("\n");
+		}
 	}
-	return [
-		`Unsupported batch screenshot annotation in step ${badStepIndex + 1}: put --annotate in top-level args, not inside the batch step.`,
-		`Use: { "args": ["--annotate", "batch"], "stdin": "[[\\"screenshot\\",\\"/path/to/image.png\\"]]" }`,
-	].join("\n");
+	return undefined;
 }
 
 function restoreArtifactManifestFromBranch(branch: unknown[]): SessionArtifactManifest | undefined {
@@ -1208,8 +791,9 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		},
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const promptPolicy = buildPromptPolicy(getLatestUserPrompt(ctx.sessionManager.getBranch()));
+			const outputPath = isRecord(params) && typeof params.outputPath === "string" ? params.outputPath : undefined;
 			const resolvedInput = resolveAgentBrowserInput({
-				getBatchAnnotateValidationError,
+				getBatchPreflightValidationError,
 				managedSessionActive,
 				params,
 			});
@@ -1270,7 +854,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				? await managedSessionExecutionQueue.run(runElectronHostInput)
 				: await runElectronHostInput();
 			if (electronHostResult) {
-				return electronHostResult;
+				return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result: electronHostResult });
 			}
 
 			const explicitSessionName = extractExplicitSessionName(toolArgs);
@@ -1335,7 +919,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					});
 					if (serializeBrowserCommand) branchStateGeneration += 1;
 				}
-				return result;
+				return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result });
 			};
 
 			return serializeBrowserCommand