pi-agent-browser-native 0.2.12 → 0.2.14

package/extensions/agent-browser/index.ts

@@ -6,11 +6,16 @@
  * Invariants/Assumptions: agent-browser is installed separately on PATH, the wrapper targets the current locally installed upstream version only, and no backward-compatibility shims are provided.
  */
 
-import { rm } from "node:fs/promises";
+import { readFile, rm } from "node:fs/promises";
 
-import { isToolCallEventType, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { isToolCallEventType, type AgentToolResult, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 
+import {
+	PROJECT_RULE_PROMPT,
+	buildToolPromptGuidelines,
+} from "./lib/playbook.js";
 import { runAgentBrowserProcess } from "./lib/process.js";
 import {
 	buildToolPresentation,
@@ -30,7 +35,9 @@ import {
 	getImplicitSessionCloseTimeoutMs,
 	getImplicitSessionIdleTimeoutMs,
 	getLatestUserPrompt,
+	hasLaunchScopedTabCorrectionFlag,
 	hasUsableBraveApiKey,
+	extractExplicitSessionName,
 	redactInvocationArgs,
 	redactSensitiveText,
 	redactSensitiveValue,
@@ -41,7 +48,20 @@ import {
 	type CompatibilityWorkaround,
 	type OpenResultTabCorrection,
 } from "./lib/runtime.js";
-import { cleanupSecureTempArtifacts, type PersistentSessionArtifactStore } from "./lib/temp.js";
+import {
+	cleanupSecureTempArtifacts,
+	type PersistentSessionArtifactEviction,
+	type PersistentSessionArtifactStore,
+	writePersistentSessionArtifactFile,
+	writeSecureTempFile,
+} from "./lib/temp.js";
+import {
+	type SessionArtifactManifest,
+	buildEvictedSessionArtifactEntries,
+	formatSessionArtifactRetentionSummary,
+	isSessionArtifactManifest,
+	mergeSessionArtifactManifest,
+} from "./lib/results/shared.js";
 
 const DEFAULT_SESSION_MODE = "auto" as const;
 
@@ -50,54 +70,20 @@ const AGENT_BROWSER_PARAMS = Type.Object({
 		description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators.",
 		minItems: 1,
 	}),
-	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content for commands like eval --stdin or batch." })),
+	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch and eval --stdin." })),
 	sessionMode: Type.Optional(
-		Type.Union([Type.Literal("auto"), Type.Literal("fresh")], {
+		StringEnum(["auto", "fresh"] as const, {
 			description:
-				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so startup-scoped flags like --profile, --session-name, or --cdp apply and later auto calls follow the new browser.",
+				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --session-name, --cdp, --state, or --auto-connect apply and later auto calls follow the new browser.",
 			default: DEFAULT_SESSION_MODE,
 		}),
 	),
 });
-const PROJECT_RULE_PROMPT =
-	"Project rule: when browser automation is needed, prefer the native `agent_browser` tool. Do not run direct `agent-browser` bash commands unless the user explicitly asks for a bash-oriented workflow or browser-integration debugging.";
-const QUICK_START_GUIDELINES = [
-	"Quick start mental model: args are the exact agent-browser CLI args after the binary; stdin is only for batch and eval --stdin; sessionMode=fresh switches the extension-managed session to a fresh upstream launch when you need new --profile, --session-name, or --cdp state.",
-	"Common first calls: { args: [\"open\", \"https://example.com\"] } then { args: [\"snapshot\", \"-i\"] }; after navigation, use { args: [\"click\", \"@e2\"] } then { args: [\"snapshot\", \"-i\"] }.",
-	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, and { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }.",
-	"High-value command reference: download <selector> <path> saves a file triggered by a click; get title/url/text/html/value/attr/count reads page state; screenshot [path] captures an image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab.",
-] as const;
-const BRAVE_SEARCH_PROMPT_GUIDELINE =
-	"When a non-empty BRAVE_API_KEY is available in the current environment, prefer the Brave Search API via bash/curl to discover specific destination URLs, then open the chosen URL with agent_browser instead of browsing a search engine results page just to find the target.";
-const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
-	"Standard workflow: open the page, snapshot -i, interact using refs, and re-snapshot after navigation or major DOM changes.",
-	"For authenticated or user-specific content like feeds, inboxes, dashboards, and accounts, prefer --profile Default on the first browser call and let the implicit session carry continuity. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.",
-	"Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.",
-	"When using --profile, --session-name, or --cdp, put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.",
-	"If you already used the implicit session and now need startup-scoped flags like --profile, --session-name, or --cdp, retry with sessionMode set to fresh or pass an explicit --session for the new launch. After a successful unnamed fresh launch, later auto calls follow that new session.",
-	"If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. Only use wait with an explicit argument like milliseconds, --load <state>, --url <matcher>, --fn <js>, or --text <matcher>.",
-	"For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.",
-	"For read-only browsing tasks, prefer extracting the answer from the current snapshot, structured ref labels, or eval --stdin on the current page before navigating away. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.",
-	"For downloads, prefer download <selector> <path> when an element click should save a file. Do not rely on click alone when you need the downloaded file on disk.",
-	"When using eval --stdin, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.",
-	"When using eval --stdin for extraction, return the value you want instead of relying on console.log as the primary result channel.",
-	"Do not call --help or other exploratory inspection commands unless the user explicitly asks for them or debugging the browser integration is necessary.",
-] as const;
-const TOOL_PROMPT_GUIDELINES_PREFIX = ["Use this tool whenever the task requires a real browser or live web content."] as const;
-const TOOL_PROMPT_GUIDELINES_SUFFIX = [
-	"Prefer this tool over bash for opening sites, reading docs on the web, clicking, filling, screenshots, eval, and batch workflows.",
-	"Do not fall back to osascript, AppleScript, or generic browser-driving bash commands when this tool can do the job.",
-	"Pass exact agent-browser CLI arguments in args, excluding the binary name.",
-	"Use stdin for commands like eval --stdin and batch instead of shell heredocs.",
-	"Let the extension-managed session handle the common path unless you explicitly need a fresh launch for upstream flags like --profile, --session-name, or --cdp.",
-	"Use sessionMode=fresh when switching from an existing implicit session to a new profile/debug launch without inventing a fixed explicit session name; later auto calls will follow that new session.",
-] as const;
-
 function buildMissingBinaryMessage(): string {
 	return [
 		"agent-browser is required but was not found on PATH.",
 		"This project does not bundle agent-browser.",
-		"Install it using the upstream docs:",
+		"Run `pi-agent-browser-doctor` for package/PATH diagnostics, then install agent-browser using the upstream docs:",
 		"- https://agent-browser.dev/",
 		"- https://github.com/vercel-labs/agent-browser",
 	].join("\n");
@@ -108,6 +94,20 @@ function buildInvocationPreview(effectiveArgs: string[]): string {
 	return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
 }
 
+function buildWrapperRecoveryHint(options: {
+	pinnedBatchUnwrapMode?: PinnedBatchUnwrapMode;
+	sessionTabCorrection?: OpenResultTabCorrection;
+}): string | undefined {
+	const wrapperManagedContexts = [
+		options.sessionTabCorrection ? "session tab correction" : undefined,
+		options.pinnedBatchUnwrapMode ? "pinned batch routing" : undefined,
+	].filter((item): item is string => item !== undefined);
+	if (wrapperManagedContexts.length === 0) {
+		return undefined;
+	}
+	return `Wrapper recovery hint: this call used ${wrapperManagedContexts.join(" and ")}. Inspect details.effectiveArgs and details.sessionTabCorrection; if the selected tab looks wrong, run tab list for the same session before retrying.`;
+}
+
 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*$/;
 
@@ -323,14 +323,54 @@ function extractStringResultField(data: unknown, fieldName: "title" | "url"): st
 	return text.length > 0 ? text : undefined;
 }
 
-const SESSION_TAB_PINNING_EXCLUDED_COMMANDS = new Set(["batch", "close", "goto", "navigate", "open", "session", "tab"]);
+const SESSION_TAB_PINNING_EXCLUDED_COMMANDS = new Set(["close", "goto", "navigate", "open", "session", "tab"]);
 const SESSION_TAB_POST_COMMAND_CORRECTION_EXCLUDED_COMMANDS = new Set(["batch", "close", "session", "tab"]);
 
+type PinnedBatchUnwrapMode = "single-command" | "user-batch";
+
+type AgentBrowserToolResult = AgentToolResult<unknown> & { isError?: boolean };
+
+type BatchCommandStep = [string, ...string[]];
+
+interface PinnedBatchPlan {
+	includeNavigationSummary: boolean;
+	steps: BatchCommandStep[];
+	unwrapMode: PinnedBatchUnwrapMode;
+}
+
 interface SessionTabTarget {
 	title?: string;
 	url: string;
 }
 
+interface OrderedSessionTabTarget {
+	order: number;
+	target: SessionTabTarget;
+}
+
+interface AboutBlankSessionMismatch {
+	activeUrl: "about:blank";
+	recoveryApplied: boolean;
+	recoveryHint: string;
+	targetTitle?: string;
+	targetUrl: string;
+}
+
+function getLatestSessionTabTargetOrder(targets: Map<string, OrderedSessionTabTarget>): number {
+	let latestOrder = 0;
+	for (const target of targets.values()) {
+		latestOrder = Math.max(latestOrder, target.order);
+	}
+	return latestOrder;
+}
+
+function shouldApplySessionTabTargetUpdate(options: {
+	current?: OrderedSessionTabTarget;
+	updateOrder: number;
+}): boolean {
+	return !options.current || options.updateOrder >= options.current.order;
+}
+
 function normalizeComparableUrl(url: string | undefined): string | undefined {
 	const normalizedUrl = url?.trim();
 	if (!normalizedUrl) {
@@ -345,6 +385,26 @@ function normalizeComparableUrl(url: string | undefined): string | undefined {
 	}
 }
 
+function isAboutBlankUrl(url: string | undefined): boolean {
+	return normalizeComparableUrl(url) === "about:blank";
+}
+
+function isAboutBlankSessionTabTarget(target: SessionTabTarget | undefined): boolean {
+	return isAboutBlankUrl(target?.url);
+}
+
+function commandExplicitlyTargetsAboutBlank(commandTokens: string[]): boolean {
+	return commandTokens.some((token) => isAboutBlankUrl(token));
+}
+
+function buildAboutBlankRecoveryHint(): string {
+	return "agent_browser detected that the active tab became about:blank while this session still had a prior intended tab. Run tab list for this session and re-select the intended tab, or retry with sessionMode=fresh if the tab is gone.";
+}
+
+function buildAboutBlankWarning(mismatch: AboutBlankSessionMismatch): string {
+	return `Warning: agent_browser detected that this session returned about:blank while the prior intended tab was ${mismatch.targetUrl}. ${mismatch.recoveryApplied ? "The wrapper re-selected the intended tab for the session." : "No matching tab could be re-selected; run tab list for the same session or retry with sessionMode=fresh."}`;
+}
+
 function normalizeSessionTabTarget(target: { title?: string; url?: string } | undefined): SessionTabTarget | undefined {
 	if (!target) {
 		return undefined;
@@ -371,8 +431,50 @@ function extractSessionTabTargetFromData(data: unknown): SessionTabTarget | unde
 	return undefined;
 }
 
-function restoreSessionTabTargetsFromBranch(branch: unknown[]): Map<string, SessionTabTarget> {
-	const restoredTargets = new Map<string, SessionTabTarget>();
+function extractBatchResultCommand(item: Record<string, unknown>): string[] {
+	return Array.isArray(item.command) ? item.command.filter((token): token is string => typeof token === "string") : [];
+}
+
+function extractSessionTabTargetFromBatchResults(data: unknown): SessionTabTarget | undefined {
+	if (!Array.isArray(data)) {
+		return undefined;
+	}
+
+	let currentTarget: SessionTabTarget | undefined;
+	let pendingTitle: string | undefined;
+	for (const item of data) {
+		if (!isRecord(item) || item.success === false) {
+			continue;
+		}
+		const [name, subcommand] = extractBatchResultCommand(item);
+		const result = item.result;
+
+		if (name === "get" && subcommand === "title") {
+			pendingTitle = extractStringResultField(result, "title");
+			continue;
+		}
+		if (name === "get" && subcommand === "url") {
+			const url = extractStringResultField(result, "url");
+			const target = normalizeSessionTabTarget({ title: pendingTitle, url });
+			if (target) {
+				currentTarget = target;
+			}
+			pendingTitle = undefined;
+			continue;
+		}
+
+		const resultTarget = extractSessionTabTargetFromData(result);
+		if (resultTarget) {
+			currentTarget = resultTarget;
+		}
+		pendingTitle = undefined;
+	}
+	return currentTarget;
+}
+
+function restoreSessionTabTargetsFromBranch(branch: unknown[]): Map<string, OrderedSessionTabTarget> {
+	const restoredTargets = new Map<string, OrderedSessionTabTarget>();
+	let restoredOrder = 0;
 	for (const entry of branch) {
 		if (!isRecord(entry) || entry.type !== "message") {
 			continue;
@@ -391,6 +493,7 @@ function restoreSessionTabTargetsFromBranch(branch: unknown[]): Map<string, Sess
 		}
 		const command = typeof details.command === "string" ? details.command : undefined;
 		if (command === "close" && message.isError !== true) {
+			restoredOrder += 1;
 			restoredTargets.delete(sessionName);
 			continue;
 		}
@@ -401,21 +504,152 @@ function restoreSessionTabTargetsFromBranch(branch: unknown[]): Map<string, Sess
 			  })
 			: undefined;
 		if (sessionTabTarget) {
-			restoredTargets.set(sessionName, sessionTabTarget);
+			restoredOrder += 1;
+			restoredTargets.set(sessionName, { order: restoredOrder, target: sessionTabTarget });
 		}
 	}
 	return restoredTargets;
 }
 
-function shouldPinSessionTabForCommand(options: { command?: string; sessionName?: string; stdin?: string }): boolean {
+function restoreArtifactManifestFromBranch(branch: unknown[]): SessionArtifactManifest | undefined {
+	let restoredManifest: SessionArtifactManifest | undefined;
+	for (const entry of branch) {
+		if (!isRecord(entry) || entry.type !== "message") continue;
+		const message = isRecord(entry.message) ? entry.message : undefined;
+		if (!message || message.toolName !== "agent_browser") continue;
+		const details = isRecord(message.details) ? message.details : undefined;
+		if (isSessionArtifactManifest(details?.artifactManifest)) {
+			restoredManifest = details.artifactManifest;
+		}
+	}
+	return restoredManifest;
+}
+
+function validateStdinCommandContract(options: { command?: string; commandTokens: string[]; stdin?: string }): string | undefined {
+	if (options.stdin === undefined) {
+		return undefined;
+	}
+	if (options.command === "batch") {
+		return undefined;
+	}
+	if (options.command === "eval" && options.commandTokens.includes("--stdin")) {
+		return undefined;
+	}
+	const commandLabel = options.command ? `\`${options.command}\`` : "the requested command";
+	return `agent_browser stdin is only supported for \`batch\` and \`eval --stdin\`; remove stdin from ${commandLabel} or use one of those command forms.`;
+}
+
+function supportsPinnedStdinCommand(options: { command?: string; commandTokens: string[]; stdin?: string }): boolean {
+	if (options.command === "batch") {
+		return options.stdin !== undefined;
+	}
+	if (options.stdin === undefined) {
+		return true;
+	}
+	if (options.command === "eval") {
+		return options.commandTokens.includes("--stdin");
+	}
+	return false;
+}
+
+function shouldPinSessionTabForCommand(options: {
+	command?: string;
+	commandTokens: string[];
+	sessionName?: string;
+	stdin?: string;
+}): boolean {
 	return (
 		options.sessionName !== undefined &&
-		options.stdin === undefined &&
 		options.command !== undefined &&
-		!SESSION_TAB_PINNING_EXCLUDED_COMMANDS.has(options.command)
+		!SESSION_TAB_PINNING_EXCLUDED_COMMANDS.has(options.command) &&
+		supportsPinnedStdinCommand(options)
 	);
 }
 
+function validateUserBatchStep(
+	step: unknown,
+	index: number,
+):
+	| { ok: true; step: BatchCommandStep }
+	| { ok: false; error: string } {
+	if (!Array.isArray(step)) {
+		return {
+			ok: false,
+			error: `agent_browser batch stdin step ${index} must be a non-empty array of string command tokens.`,
+		};
+	}
+	if (step.length === 0) {
+		return {
+			ok: false,
+			error: `agent_browser batch stdin step ${index} must not be empty.`,
+		};
+	}
+	const invalidTokenIndex = step.findIndex((token) => typeof token !== "string");
+	if (invalidTokenIndex !== -1) {
+		return {
+			ok: false,
+			error: `agent_browser batch stdin step ${index} token ${invalidTokenIndex} must be a string.`,
+		};
+	}
+	return { ok: true, step: step as BatchCommandStep };
+}
+
+function parseUserBatchStdin(stdin: string | undefined): { error?: string; steps?: BatchCommandStep[] } {
+	if (stdin === undefined) {
+		return { steps: [] };
+	}
+	try {
+		const parsed = JSON.parse(stdin) as unknown;
+		if (!Array.isArray(parsed)) {
+			return { error: "agent_browser batch stdin must be a JSON array of command steps." };
+		}
+		const steps: BatchCommandStep[] = [];
+		for (const [index, rawStep] of parsed.entries()) {
+			const validated = validateUserBatchStep(rawStep, index);
+			if (!validated.ok) {
+				return { error: validated.error };
+			}
+			steps.push(validated.step);
+		}
+		return { steps };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { error: `agent_browser batch stdin could not be parsed as JSON: ${message}` };
+	}
+}
+
+function buildPinnedBatchPlan(options: {
+	command?: string;
+	commandTokens: string[];
+	selectedTab: string;
+	stdin?: string;
+}): PinnedBatchPlan | { error: string } | undefined {
+	if (options.command === "batch") {
+		const parsed = parseUserBatchStdin(options.stdin);
+		if (parsed.error) {
+			return { error: parsed.error };
+		}
+		const tabSelectionStep: BatchCommandStep = ["tab", options.selectedTab];
+		return {
+			includeNavigationSummary: false,
+			steps: [tabSelectionStep, ...(parsed.steps ?? [])],
+			unwrapMode: "user-batch",
+		};
+	}
+	if (options.commandTokens.length === 0) {
+		return undefined;
+	}
+	const includeNavigationSummary = options.command !== undefined && NAVIGATION_SUMMARY_COMMANDS.has(options.command);
+	const tabSelectionStep: BatchCommandStep = ["tab", options.selectedTab];
+	const commandStep = options.commandTokens as BatchCommandStep;
+	const navigationSummarySteps: BatchCommandStep[] = includeNavigationSummary ? [["get", "title"], ["get", "url"]] : [];
+	return {
+		includeNavigationSummary,
+		steps: [tabSelectionStep, commandStep, ...navigationSummarySteps],
+		unwrapMode: "single-command",
+	};
+}
+
 function shouldCorrectSessionTabAfterCommand(options: { command?: string; sessionName?: string }): boolean {
 	return (
 		options.sessionName !== undefined &&
@@ -446,6 +680,7 @@ function deriveSessionTabTarget(options: {
 	}
 	return (
 		normalizeSessionTabTarget(options.navigationSummary) ??
+		extractSessionTabTargetFromBatchResults(options.data) ??
 		extractSessionTabTargetFromData(options.data) ??
 		options.previousTarget
 	);
@@ -454,6 +689,7 @@ function deriveSessionTabTarget(options: {
 function unwrapPinnedSessionBatchEnvelope(options: {
 	envelope?: AgentBrowserEnvelope;
 	includeNavigationSummary: boolean;
+	mode?: PinnedBatchUnwrapMode;
 }): { envelope?: AgentBrowserEnvelope; navigationSummary?: NavigationSummary; parseError?: string } {
 	if (!options.envelope) {
 		return {};
@@ -467,19 +703,29 @@ function unwrapPinnedSessionBatchEnvelope(options: {
 	const steps = options.envelope.data.filter(isRecord) as AgentBrowserBatchResult[];
 	const tabSelectionStep = steps[0];
 	const commandStep = steps[1];
-	if (!commandStep) {
+	if (tabSelectionStep?.success === false) {
 		return {
 			envelope: {
 				success: false,
-				error: "agent-browser did not return the corrected command result.",
+				error: tabSelectionStep.error ?? "agent-browser could not re-select the intended tab before running the command.",
 			},
 		};
 	}
-	if (tabSelectionStep?.success === false) {
+	if (options.mode === "user-batch") {
+		const userSteps = steps.slice(1);
+		return {
+			envelope: {
+				success: userSteps.every((step) => step.success !== false),
+				data: userSteps,
+				error: userSteps.find((step) => step.success === false)?.error,
+			},
+		};
+	}
+	if (!commandStep) {
 		return {
 			envelope: {
 				success: false,
-				error: tabSelectionStep.error ?? "agent-browser could not re-select the intended tab before running the command.",
+				error: "agent-browser did not return the corrected command result.",
 			},
 		};
 	}
@@ -514,14 +760,14 @@ async function runSessionCommandData(options: {
 		cwd,
 		signal,
 	});
-	if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0) {
-		return undefined;
-	}
-	const parsed = await parseAgentBrowserEnvelope({
-		stdout: processResult.stdout,
-		stdoutPath: processResult.stdoutSpillPath,
-	});
 	try {
+		if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0) {
+			return undefined;
+		}
+		const parsed = await parseAgentBrowserEnvelope({
+			stdout: processResult.stdout,
+			stdoutPath: processResult.stdoutSpillPath,
+		});
 		if (parsed.parseError || parsed.envelope?.success === false) {
 			return undefined;
 		}
@@ -619,23 +865,6 @@ async function applyOpenResultTabCorrection(options: {
 	return result === undefined ? undefined : correction;
 }
 
-function buildSharedBrowserPlaybookGuidelines(hasBraveApiKey: boolean): string[] {
-	return [
-		SHARED_BROWSER_PLAYBOOK_GUIDELINES[0],
-		...(hasBraveApiKey ? [BRAVE_SEARCH_PROMPT_GUIDELINE] : []),
-		...SHARED_BROWSER_PLAYBOOK_GUIDELINES.slice(1),
-	];
-}
-
-function buildToolPromptGuidelines(hasBraveApiKey: boolean): string[] {
-	return [
-		...TOOL_PROMPT_GUIDELINES_PREFIX,
-		...QUICK_START_GUIDELINES,
-		...buildSharedBrowserPlaybookGuidelines(hasBraveApiKey),
-		...TOOL_PROMPT_GUIDELINES_SUFFIX,
-	];
-}
-
 function buildSessionDetailFields(sessionName: string | undefined, usedImplicitSession: boolean): Record<string, unknown> {
 	return sessionName ? { sessionName, usedImplicitSession } : {};
 }
@@ -656,6 +885,70 @@ function getPersistentSessionArtifactStore(ctx: {
 	return { sessionDir, sessionId };
 }
 
+async function preserveParseFailureOutput(options: {
+	artifactManifest?: SessionArtifactManifest;
+	persistentArtifactStore?: PersistentSessionArtifactStore;
+	stdoutSpillPath?: string;
+}): Promise<{
+	artifactManifest?: SessionArtifactManifest;
+	artifactRetentionSummary?: string;
+	fullOutputPath?: string;
+	fullOutputUnavailable?: string;
+}> {
+	if (!options.stdoutSpillPath) {
+		return {};
+	}
+
+	try {
+		const rawOutput = await readFile(options.stdoutSpillPath);
+		const nowMs = Date.now();
+		let evictedArtifacts: PersistentSessionArtifactEviction[] = [];
+		let fullOutputPath: string;
+		let storageScope: "persistent-session" | "process-temp";
+		if (options.persistentArtifactStore) {
+			const result = await writePersistentSessionArtifactFile({
+				content: rawOutput,
+				prefix: "pi-agent-browser-parse-failure-output",
+				store: options.persistentArtifactStore,
+				suffix: ".txt",
+			});
+			fullOutputPath = result.path;
+			evictedArtifacts = result.evictedArtifacts;
+			storageScope = "persistent-session";
+		} else {
+			fullOutputPath = await writeSecureTempFile({
+				content: rawOutput,
+				prefix: "pi-agent-browser-parse-failure-output",
+				suffix: ".txt",
+			});
+			storageScope = "process-temp";
+		}
+		const artifactManifest = mergeSessionArtifactManifest({
+			base: options.artifactManifest,
+			entries: [
+				{
+					command: "agent-browser",
+					createdAtMs: nowMs,
+					kind: "spill",
+					path: fullOutputPath,
+					retentionState: storageScope === "persistent-session" ? "live" : "ephemeral",
+					storageScope,
+				},
+				...buildEvictedSessionArtifactEntries(evictedArtifacts, nowMs),
+			],
+			nowMs,
+		});
+		return {
+			artifactManifest,
+			artifactRetentionSummary: artifactManifest ? formatSessionArtifactRetentionSummary(artifactManifest) : undefined,
+			fullOutputPath,
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { fullOutputUnavailable: message };
+	}
+}
+
 function redactRecoveryHint(recoveryHint: {
 	exampleArgs: string[];
 	exampleParams: { args: string[]; sessionMode: "fresh" };
@@ -676,26 +969,53 @@ function redactRecoveryHint(recoveryHint: {
 	};
 }
 
+// Serializes managed-session read/modify/write work so overlapping tool calls cannot promote stale state or close an in-use session.
+class AsyncExecutionQueue {
+	private tail: Promise<void> = Promise.resolve();
+
+	run<T>(work: () => Promise<T>): Promise<T> {
+		const previous = this.tail;
+		let release!: () => void;
+		this.tail = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+
+		return (async () => {
+			await previous;
+			try {
+				return await work();
+			} finally {
+				release();
+			}
+		})();
+	}
+}
+
 async function closeManagedSession(options: { cwd: string; sessionName: string; timeoutMs: number }): Promise<void> {
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+	let stdoutSpillPath: string | undefined;
 	try {
-		await runAgentBrowserProcess({
+		const processResult = await runAgentBrowserProcess({
 			args: ["--session", options.sessionName, "close"],
 			cwd: options.cwd,
 			signal: controller.signal,
 		});
+		stdoutSpillPath = processResult.stdoutSpillPath;
 	} catch {
 		// Best-effort cleanup only.
 	} finally {
 		clearTimeout(timer);
+		if (stdoutSpillPath) {
+			await rm(stdoutSpillPath, { force: true }).catch(() => undefined);
+		}
 	}
 }
 
 export default function agentBrowserExtension(pi: ExtensionAPI) {
 	const ephemeralSessionSeed = createEphemeralSessionSeed();
 	const hasBraveApiKey = hasUsableBraveApiKey();
-	const toolPromptGuidelines = buildToolPromptGuidelines(hasBraveApiKey);
+	const toolPromptGuidelines = buildToolPromptGuidelines({ includeBraveSearch: hasBraveApiKey });
 	const implicitSessionIdleTimeoutMs = getImplicitSessionIdleTimeoutMs();
 	const implicitSessionCloseTimeoutMs = getImplicitSessionCloseTimeoutMs();
 	let managedSessionActive = false;
@@ -703,7 +1023,10 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 	let managedSessionName = managedSessionBaseName;
 	let managedSessionCwd = process.cwd();
 	let freshSessionOrdinal = 0;
-	let sessionTabTargets = new Map<string, SessionTabTarget>();
+	let sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
+	let sessionTabTargetUpdateOrder = 0;
+	let artifactManifest: SessionArtifactManifest | undefined;
+	const managedSessionExecutionQueue = new AsyncExecutionQueue();
 
 	pi.on("session_start", async (_event, ctx) => {
 		managedSessionBaseName = createImplicitSessionName(ctx.sessionManager.getSessionId(), ctx.cwd, ephemeralSessionSeed);
@@ -713,11 +1036,15 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		managedSessionCwd = ctx.cwd;
 		freshSessionOrdinal = restoredState.freshSessionOrdinal;
 		sessionTabTargets = restoreSessionTabTargetsFromBranch(ctx.sessionManager.getBranch());
+		sessionTabTargetUpdateOrder = getLatestSessionTabTargetOrder(sessionTabTargets);
+		artifactManifest = restoreArtifactManifestFromBranch(ctx.sessionManager.getBranch());
 	});
 
 	pi.on("session_shutdown", async () => {
 		managedSessionActive = false;
-		sessionTabTargets = new Map<string, SessionTabTarget>();
+		sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
+		sessionTabTargetUpdateOrder = 0;
+		artifactManifest = undefined;
 		await cleanupSecureTempArtifacts();
 	});
 
@@ -765,312 +1092,488 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				};
 			}
 
-			const sessionMode = params.sessionMode ?? DEFAULT_SESSION_MODE;
-			const freshSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1);
-			const executionPlan = buildExecutionPlan(params.args, {
-				freshSessionName,
-				managedSessionActive,
-				managedSessionName,
-				sessionMode,
-			});
-			const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);
-			const redactedRecoveryHint = redactRecoveryHint(executionPlan.recoveryHint);
-			const compatibilityWorkaround: CompatibilityWorkaround | undefined = executionPlan.compatibilityWorkaround;
-			if (executionPlan.managedSessionName === freshSessionName) {
-				freshSessionOrdinal += 1;
-			}
+			const tabTargetUpdateOrder = ++sessionTabTargetUpdateOrder;
+			const runTool = async (): Promise<AgentBrowserToolResult> => {
+				const sessionMode = params.sessionMode ?? DEFAULT_SESSION_MODE;
+				const freshSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1);
+				const executionPlan = buildExecutionPlan(params.args, {
+					freshSessionName,
+					managedSessionActive,
+					managedSessionName,
+					sessionMode,
+				});
+				const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);
+				const redactedRecoveryHint = redactRecoveryHint(executionPlan.recoveryHint);
+				const compatibilityWorkaround: CompatibilityWorkaround | undefined = executionPlan.compatibilityWorkaround;
+				if (executionPlan.managedSessionName === freshSessionName) {
+					freshSessionOrdinal += 1;
+				}
 
-			if (executionPlan.validationError) {
-				return {
-					content: [{ type: "text", text: executionPlan.validationError }],
-					details: {
-						args: redactedArgs,
-						invalidValueFlag: executionPlan.invalidValueFlag,
-						sessionMode,
-						sessionRecoveryHint: redactedRecoveryHint,
-						startupScopedFlags: executionPlan.startupScopedFlags,
-						validationError: executionPlan.validationError,
-					},
-					isError: true,
-				};
-			}
+				if (executionPlan.validationError) {
+					return {
+						content: [{ type: "text", text: executionPlan.validationError }],
+						details: {
+							args: redactedArgs,
+							invalidValueFlag: executionPlan.invalidValueFlag,
+							sessionMode,
+							sessionRecoveryHint: redactedRecoveryHint,
+							startupScopedFlags: executionPlan.startupScopedFlags,
+							validationError: executionPlan.validationError,
+						},
+						isError: true,
+					};
+				}
 
-			const priorSessionTabTarget = executionPlan.sessionName ? sessionTabTargets.get(executionPlan.sessionName) : undefined;
-			const includePinnedNavigationSummary =
-				executionPlan.commandInfo.command !== undefined && NAVIGATION_SUMMARY_COMMANDS.has(executionPlan.commandInfo.command);
-			let sessionTabCorrection: OpenResultTabCorrection | undefined;
-			let processArgs = executionPlan.effectiveArgs;
-			let processStdin = params.stdin;
-			if (
-				priorSessionTabTarget &&
-				shouldPinSessionTabForCommand({
+				const commandTokens = extractCommandTokens(params.args);
+				const stdinValidationError = validateStdinCommandContract({
 					command: executionPlan.commandInfo.command,
-					sessionName: executionPlan.sessionName,
+					commandTokens,
 					stdin: params.stdin,
-				})
-			) {
-				const plannedSessionTabSelection = await collectSessionTabSelection({
-					cwd: ctx.cwd,
-					sessionName: executionPlan.sessionName,
-					signal,
-					target: priorSessionTabTarget,
 				});
-				const commandTokens = extractCommandTokens(params.args);
-				if (plannedSessionTabSelection && commandTokens.length > 0 && executionPlan.sessionName) {
-					sessionTabCorrection = plannedSessionTabSelection;
-					processArgs = ["--json", "--session", executionPlan.sessionName, "batch"];
-					processStdin = JSON.stringify([
-						["tab", plannedSessionTabSelection.selectedTab],
-						commandTokens,
-						...(includePinnedNavigationSummary ? [["get", "title"], ["get", "url"]] : []),
-					]);
+				if (stdinValidationError) {
+					return {
+						content: [{ type: "text", text: stdinValidationError }],
+						details: {
+							args: redactedArgs,
+							command: executionPlan.commandInfo.command,
+							compatibilityWorkaround,
+							effectiveArgs: redactedEffectiveArgs,
+							sessionMode,
+							validationError: stdinValidationError,
+							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+						},
+						isError: true,
+					};
 				}
-			}
-			const redactedProcessArgs = redactInvocationArgs(processArgs);
 
-			onUpdate?.({
-				content: [{ type: "text", text: `Running agent-browser ${buildInvocationPreview(redactedProcessArgs)}` }],
-				details: {
-					compatibilityWorkaround,
-					effectiveArgs: redactedProcessArgs,
-					sessionMode,
-					sessionTabCorrection,
-					...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
-				},
-			});
-
-			const processResult = await runAgentBrowserProcess({
-				args: processArgs,
-				cwd: ctx.cwd,
-				env: executionPlan.managedSessionName ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: implicitSessionIdleTimeoutMs } : undefined,
-				signal,
-				stdin: processStdin,
-			});
+				const priorSessionTabTargetState = executionPlan.sessionName ? sessionTabTargets.get(executionPlan.sessionName) : undefined;
+				const priorSessionTabTarget = priorSessionTabTargetState?.target;
+				let pinnedBatchUnwrapMode: PinnedBatchUnwrapMode | undefined;
+				let includePinnedNavigationSummary = false;
+				let sessionTabCorrection: OpenResultTabCorrection | undefined;
+				let processArgs = executionPlan.effectiveArgs;
+				let processStdin = params.stdin;
+				if (
+					priorSessionTabTarget &&
+					shouldPinSessionTabForCommand({
+						command: executionPlan.commandInfo.command,
+						commandTokens,
+						sessionName: executionPlan.sessionName,
+						stdin: params.stdin,
+					})
+				) {
+					const plannedSessionTabSelection = await collectSessionTabSelection({
+						cwd: ctx.cwd,
+						sessionName: executionPlan.sessionName,
+						signal,
+						target: priorSessionTabTarget,
+					});
+					if (plannedSessionTabSelection && executionPlan.sessionName) {
+						if (executionPlan.commandInfo.command === "eval" && params.stdin !== undefined) {
+							const appliedSessionTabSelection = await applyOpenResultTabCorrection({
+								correction: plannedSessionTabSelection,
+								cwd: ctx.cwd,
+								sessionName: executionPlan.sessionName,
+								signal,
+							});
+							if (!appliedSessionTabSelection) {
+								const error = "agent-browser could not re-select the intended tab before running the command.";
+								return {
+									content: [{ type: "text", text: error }],
+									details: {
+										args: redactedArgs,
+										command: executionPlan.commandInfo.command,
+										compatibilityWorkaround,
+										effectiveArgs: redactedEffectiveArgs,
+										sessionMode,
+										sessionTabCorrection: plannedSessionTabSelection,
+										validationError: error,
+										...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+									},
+									isError: true,
+								};
+							}
+							sessionTabCorrection = appliedSessionTabSelection;
+						} else {
+							const pinnedBatchPlan = buildPinnedBatchPlan({
+								command: executionPlan.commandInfo.command,
+								commandTokens,
+								selectedTab: plannedSessionTabSelection.selectedTab,
+								stdin: params.stdin,
+							});
+							if (pinnedBatchPlan && "error" in pinnedBatchPlan) {
+								return {
+									content: [{ type: "text", text: pinnedBatchPlan.error }],
+									details: {
+										args: redactedArgs,
+										command: executionPlan.commandInfo.command,
+										compatibilityWorkaround,
+										effectiveArgs: redactedEffectiveArgs,
+										sessionMode,
+										sessionTabCorrection: plannedSessionTabSelection,
+										validationError: pinnedBatchPlan.error,
+										...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+									},
+									isError: true,
+								};
+							}
+							if (pinnedBatchPlan) {
+								sessionTabCorrection = plannedSessionTabSelection;
+								processArgs = ["--json", "--session", executionPlan.sessionName, "batch"];
+								processStdin = JSON.stringify(pinnedBatchPlan.steps);
+								includePinnedNavigationSummary = pinnedBatchPlan.includeNavigationSummary;
+								pinnedBatchUnwrapMode = pinnedBatchPlan.unwrapMode;
+							}
+						}
+					}
+				}
+				const redactedProcessArgs = redactInvocationArgs(processArgs);
 
-			if (processResult.spawnError?.message.includes("ENOENT")) {
-				const errorText = buildMissingBinaryMessage();
-				return {
-					content: [{ type: "text", text: errorText }],
+				onUpdate?.({
+					content: [{ type: "text", text: `Running agent-browser ${buildInvocationPreview(redactedProcessArgs)}` }],
 					details: {
-						args: redactedArgs,
 						compatibilityWorkaround,
 						effectiveArgs: redactedProcessArgs,
 						sessionMode,
 						sessionTabCorrection,
-						spawnError: processResult.spawnError.message,
+						...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 					},
-					isError: true,
-				};
-			}
+				});
 
-			try {
-				const parsed = await parseAgentBrowserEnvelope({
-					stdout: processResult.stdout,
-					stdoutPath: processResult.stdoutSpillPath,
+				const processResult = await runAgentBrowserProcess({
+					args: processArgs,
+					cwd: ctx.cwd,
+					env: executionPlan.managedSessionName ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: implicitSessionIdleTimeoutMs } : undefined,
+					signal,
+					stdin: processStdin,
 				});
-				let parseError = parsed.parseError;
-				let presentationEnvelope = parsed.envelope;
-				let navigationSummary: NavigationSummary | undefined;
-				if (sessionTabCorrection) {
-					const pinnedBatchResult = unwrapPinnedSessionBatchEnvelope({
-						envelope: parsed.envelope,
-						includeNavigationSummary: includePinnedNavigationSummary,
-					});
-					parseError = pinnedBatchResult.parseError ?? parseError;
-					presentationEnvelope = pinnedBatchResult.envelope ?? presentationEnvelope;
-					navigationSummary = pinnedBatchResult.navigationSummary;
-				}
-				const processSucceeded = !processResult.aborted && !processResult.spawnError && processResult.exitCode === 0;
-				const plainTextInspection = executionPlan.plainTextInspection && processSucceeded;
-				const parseSucceeded = plainTextInspection || parseError === undefined;
-				const envelopeSuccess = plainTextInspection ? true : presentationEnvelope?.success !== false;
-				const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
-				const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
-
-				if (succeeded && !navigationSummary && shouldCaptureNavigationSummary(executionPlan.commandInfo.command, presentationEnvelope?.data)) {
-					navigationSummary = await collectNavigationSummary({
-						cwd: ctx.cwd,
-						sessionName: executionPlan.sessionName,
-						signal,
-					});
-				}
-				if (navigationSummary && presentationEnvelope) {
-					presentationEnvelope = {
-						...presentationEnvelope,
-						data: mergeNavigationSummaryIntoData(presentationEnvelope.data, navigationSummary),
+
+				if (processResult.spawnError?.message.includes("ENOENT")) {
+					const errorText = buildMissingBinaryMessage();
+					return {
+						content: [{ type: "text", text: errorText }],
+						details: {
+							args: redactedArgs,
+							compatibilityWorkaround,
+							effectiveArgs: redactedProcessArgs,
+							sessionMode,
+							sessionTabCorrection,
+							spawnError: processResult.spawnError.message,
+						},
+						isError: true,
 					};
 				}
 
-				let openResultTabCorrection: OpenResultTabCorrection | undefined;
-				if (
-					succeeded &&
-					executionPlan.sessionName &&
-					params.args.some((token) => token === "--profile" || token.startsWith("--profile=")) &&
-					(executionPlan.commandInfo.command === "goto" ||
-						executionPlan.commandInfo.command === "navigate" ||
-						executionPlan.commandInfo.command === "open")
-				) {
-					const targetTitle = extractStringResultField(presentationEnvelope?.data, "title");
-					const targetUrl = extractStringResultField(presentationEnvelope?.data, "url");
-					const plannedTabCorrection = await collectOpenResultTabCorrection({
-						cwd: ctx.cwd,
-						sessionName: executionPlan.sessionName,
-						signal,
-						targetTitle,
-						targetUrl,
+				try {
+					const persistentArtifactStore = getPersistentSessionArtifactStore(ctx);
+					const parsed = await parseAgentBrowserEnvelope({
+						stdout: processResult.stdout,
+						stdoutPath: processResult.stdoutSpillPath,
 					});
-					if (plannedTabCorrection) {
-						openResultTabCorrection = await applyOpenResultTabCorrection({
-							correction: plannedTabCorrection,
+					let parseError = parsed.parseError;
+					let presentationEnvelope = parsed.envelope;
+					let navigationSummary: NavigationSummary | undefined;
+					if (pinnedBatchUnwrapMode) {
+						const pinnedBatchResult = unwrapPinnedSessionBatchEnvelope({
+							envelope: parsed.envelope,
+							includeNavigationSummary: includePinnedNavigationSummary,
+							mode: pinnedBatchUnwrapMode,
+						});
+						parseError = pinnedBatchResult.parseError ?? parseError;
+						presentationEnvelope = pinnedBatchResult.envelope ?? presentationEnvelope;
+						navigationSummary = pinnedBatchResult.navigationSummary;
+					}
+					const parseFailureOutput = parseError
+						? await preserveParseFailureOutput({
+								artifactManifest,
+								persistentArtifactStore,
+								stdoutSpillPath: processResult.stdoutSpillPath,
+							})
+						: {};
+					const processSucceeded = !processResult.aborted && !processResult.spawnError && processResult.exitCode === 0;
+					const plainTextInspection = executionPlan.plainTextInspection && processSucceeded;
+					const parseSucceeded = plainTextInspection || parseError === undefined;
+					const envelopeSuccess = plainTextInspection ? true : presentationEnvelope?.success !== false;
+					const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
+					const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
+
+					if (succeeded && !navigationSummary && shouldCaptureNavigationSummary(executionPlan.commandInfo.command, presentationEnvelope?.data)) {
+						navigationSummary = await collectNavigationSummary({
 							cwd: ctx.cwd,
 							sessionName: executionPlan.sessionName,
 							signal,
 						});
 					}
-				}
+					if (navigationSummary && presentationEnvelope) {
+						presentationEnvelope = {
+							...presentationEnvelope,
+							data: mergeNavigationSummaryIntoData(presentationEnvelope.data, navigationSummary),
+						};
+					}
 
-				const observedSessionTabTarget =
-					normalizeSessionTabTarget(navigationSummary) ?? extractSessionTabTargetFromData(presentationEnvelope?.data);
-				const currentSessionTabTarget = deriveSessionTabTarget({
-					command: executionPlan.commandInfo.command,
-					data: presentationEnvelope?.data,
-					navigationSummary,
-					previousTarget: priorSessionTabTarget,
-				});
-				if (
-					succeeded &&
-					priorSessionTabTarget &&
-					!sessionTabCorrection &&
-					observedSessionTabTarget &&
-					shouldCorrectSessionTabAfterCommand({
+					let openResultTabCorrection: OpenResultTabCorrection | undefined;
+					if (
+						succeeded &&
+						executionPlan.sessionName &&
+						hasLaunchScopedTabCorrectionFlag(params.args) &&
+						(executionPlan.commandInfo.command === "goto" ||
+							executionPlan.commandInfo.command === "navigate" ||
+							executionPlan.commandInfo.command === "open")
+					) {
+						const targetTitle = extractStringResultField(presentationEnvelope?.data, "title");
+						const targetUrl = extractStringResultField(presentationEnvelope?.data, "url");
+						const plannedTabCorrection = await collectOpenResultTabCorrection({
+							cwd: ctx.cwd,
+							sessionName: executionPlan.sessionName,
+							signal,
+							targetTitle,
+							targetUrl,
+						});
+						if (plannedTabCorrection) {
+							openResultTabCorrection = await applyOpenResultTabCorrection({
+								correction: plannedTabCorrection,
+								cwd: ctx.cwd,
+								sessionName: executionPlan.sessionName,
+								signal,
+							});
+						}
+					}
+
+					const observedSessionTabTarget =
+						normalizeSessionTabTarget(navigationSummary) ??
+						extractSessionTabTargetFromBatchResults(presentationEnvelope?.data) ??
+						extractSessionTabTargetFromData(presentationEnvelope?.data);
+					let currentSessionTabTarget = deriveSessionTabTarget({
 						command: executionPlan.commandInfo.command,
-						sessionName: executionPlan.sessionName,
-					})
-				) {
-					const postCommandTabCorrection = await collectSessionTabSelection({
-						cwd: ctx.cwd,
-						sessionName: executionPlan.sessionName,
-						signal,
-						target: observedSessionTabTarget,
+						data: presentationEnvelope?.data,
+						navigationSummary,
+						previousTarget: priorSessionTabTarget,
 					});
-					if (postCommandTabCorrection) {
-						const appliedPostCommandCorrection = await applyOpenResultTabCorrection({
-							correction: postCommandTabCorrection,
+					let aboutBlankSessionMismatch: AboutBlankSessionMismatch | undefined;
+					const shouldTreatAboutBlankAsMismatch =
+						succeeded &&
+						priorSessionTabTarget !== undefined &&
+						!isAboutBlankSessionTabTarget(priorSessionTabTarget) &&
+						isAboutBlankSessionTabTarget(observedSessionTabTarget ?? currentSessionTabTarget) &&
+						!commandExplicitlyTargetsAboutBlank(commandTokens);
+					if (shouldTreatAboutBlankAsMismatch && priorSessionTabTarget) {
+						const aboutBlankRecovery = await collectSessionTabSelection({
 							cwd: ctx.cwd,
 							sessionName: executionPlan.sessionName,
 							signal,
+							target: priorSessionTabTarget,
 						});
-						if (appliedPostCommandCorrection && !sessionTabCorrection) {
-							sessionTabCorrection = appliedPostCommandCorrection;
+						const appliedAboutBlankRecovery = aboutBlankRecovery
+							? await applyOpenResultTabCorrection({
+									correction: aboutBlankRecovery,
+									cwd: ctx.cwd,
+									sessionName: executionPlan.sessionName,
+									signal,
+							  })
+							: undefined;
+						if (appliedAboutBlankRecovery) {
+							sessionTabCorrection = appliedAboutBlankRecovery;
 						}
+						aboutBlankSessionMismatch = {
+							activeUrl: "about:blank",
+							recoveryApplied: appliedAboutBlankRecovery !== undefined,
+							recoveryHint: buildAboutBlankRecoveryHint(),
+							targetTitle: priorSessionTabTarget.title,
+							targetUrl: priorSessionTabTarget.url,
+						};
+						currentSessionTabTarget = priorSessionTabTarget;
 					}
-				}
-				if (executionPlan.sessionName) {
-					if (executionPlan.commandInfo.command === "close" && succeeded) {
-						sessionTabTargets.delete(executionPlan.sessionName);
-					} else if (currentSessionTabTarget) {
-						sessionTabTargets.set(executionPlan.sessionName, currentSessionTabTarget);
+					if (
+						succeeded &&
+						priorSessionTabTarget &&
+						!sessionTabCorrection &&
+						!aboutBlankSessionMismatch &&
+						!commandExplicitlyTargetsAboutBlank(commandTokens) &&
+						observedSessionTabTarget &&
+						shouldCorrectSessionTabAfterCommand({
+							command: executionPlan.commandInfo.command,
+							sessionName: executionPlan.sessionName,
+						})
+					) {
+						const postCommandTabCorrection = await collectSessionTabSelection({
+							cwd: ctx.cwd,
+							sessionName: executionPlan.sessionName,
+							signal,
+							target: observedSessionTabTarget,
+						});
+						if (postCommandTabCorrection) {
+							const appliedPostCommandCorrection = await applyOpenResultTabCorrection({
+								correction: postCommandTabCorrection,
+								cwd: ctx.cwd,
+								sessionName: executionPlan.sessionName,
+								signal,
+							});
+							if (appliedPostCommandCorrection && !sessionTabCorrection) {
+								sessionTabCorrection = appliedPostCommandCorrection;
+							}
+						}
+					}
+					if (executionPlan.sessionName) {
+						const activeSessionTabTargetState = sessionTabTargets.get(executionPlan.sessionName);
+						if (shouldApplySessionTabTargetUpdate({ current: activeSessionTabTargetState, updateOrder: tabTargetUpdateOrder })) {
+							if (executionPlan.commandInfo.command === "close" && succeeded) {
+								sessionTabTargets.delete(executionPlan.sessionName);
+							} else if (currentSessionTabTarget) {
+								sessionTabTargets.set(executionPlan.sessionName, { order: tabTargetUpdateOrder, target: currentSessionTabTarget });
+							}
+						}
 					}
-				}
 
-				const priorManagedSessionCwd = managedSessionCwd;
-				const managedSessionState = resolveManagedSessionState({
-					command: executionPlan.commandInfo.command,
-					managedSessionName: executionPlan.managedSessionName,
-					priorActive: managedSessionActive,
-					priorSessionName: managedSessionName,
-					succeeded,
-				});
-				const replacedManagedSessionName = managedSessionState.replacedSessionName;
-				managedSessionActive = managedSessionState.active;
-				managedSessionName = managedSessionState.sessionName;
-				if (executionPlan.managedSessionName && succeeded) {
-					managedSessionCwd = ctx.cwd;
-				}
-				if (replacedManagedSessionName) {
-					sessionTabTargets.delete(replacedManagedSessionName);
-					await closeManagedSession({
-						cwd: priorManagedSessionCwd,
-						sessionName: replacedManagedSessionName,
-						timeoutMs: implicitSessionCloseTimeoutMs,
+					const priorManagedSessionCwd = managedSessionCwd;
+					const managedSessionState = resolveManagedSessionState({
+						command: executionPlan.commandInfo.command,
+						managedSessionName: executionPlan.managedSessionName,
+						priorActive: managedSessionActive,
+						priorSessionName: managedSessionName,
+						succeeded,
 					});
-				}
-
-				const errorText = getAgentBrowserErrorText({
-					aborted: processResult.aborted,
-					envelope: presentationEnvelope,
-					exitCode: processResult.exitCode,
-					parseError,
-					plainTextInspection,
-					spawnError: processResult.spawnError,
-					stderr: processResult.stderr,
-				});
-
-				const presentation = plainTextInspection
-					? {
-						batchFailure: undefined,
-						batchSteps: undefined,
-						content: [{ type: "text" as const, text: inspectionText ?? "" }],
-						data: undefined,
-						fullOutputPath: undefined,
-						fullOutputPaths: undefined,
-						imagePath: undefined,
-						imagePaths: undefined,
-						summary: `${redactedArgs.join(" ")} completed`,
-					  }
-					: await buildToolPresentation({
-							commandInfo: executionPlan.commandInfo,
-							cwd: ctx.cwd,
-							envelope: presentationEnvelope,
-							errorText,
-							persistentArtifactStore: getPersistentSessionArtifactStore(ctx),
-					  });
-				const redactedContent = presentation.content.map((item) =>
-					item.type === "text" ? { ...item, text: redactSensitiveText(item.text) } : item,
-				);
+					const replacedManagedSessionName = managedSessionState.replacedSessionName;
+					managedSessionActive = managedSessionState.active;
+					managedSessionName = managedSessionState.sessionName;
+					if (executionPlan.managedSessionName && succeeded) {
+						managedSessionCwd = ctx.cwd;
+					}
+					if (replacedManagedSessionName) {
+						sessionTabTargets.delete(replacedManagedSessionName);
+						await closeManagedSession({
+							cwd: priorManagedSessionCwd,
+							sessionName: replacedManagedSessionName,
+							timeoutMs: implicitSessionCloseTimeoutMs,
+						});
+					}
 
-				return {
-					content: redactedContent,
-					details: {
-						args: redactedArgs,
-						batchFailure: redactSensitiveValue(presentation.batchFailure),
-						batchSteps: redactSensitiveValue(presentation.batchSteps),
+					const errorText = getAgentBrowserErrorText({
+						aborted: processResult.aborted,
 						command: executionPlan.commandInfo.command,
-						compatibilityWorkaround,
-						subcommand: executionPlan.commandInfo.subcommand,
-						data: redactSensitiveValue(presentation.data),
-						error: plainTextInspection ? undefined : redactSensitiveValue(presentationEnvelope?.error),
-						inspection: plainTextInspection || undefined,
-						navigationSummary: redactSensitiveValue(navigationSummary),
-						openResultTabCorrection: redactSensitiveValue(openResultTabCorrection),
 						effectiveArgs: redactedProcessArgs,
+						envelope: presentationEnvelope,
 						exitCode: processResult.exitCode,
-						fullOutputPath: presentation.fullOutputPath,
-						fullOutputPaths: presentation.fullOutputPaths,
-						imagePath: presentation.imagePath,
-						imagePaths: presentation.imagePaths,
-						parseError: plainTextInspection ? undefined : parseError,
-						sessionMode,
-						sessionTabCorrection: redactSensitiveValue(sessionTabCorrection),
-						sessionTabTarget: redactSensitiveValue(currentSessionTabTarget),
-						...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
-						sessionRecoveryHint: redactedRecoveryHint,
-						startupScopedFlags: executionPlan.startupScopedFlags,
-						stderr: processResult.stderr ? redactSensitiveText(processResult.stderr) : undefined,
-						stdout: plainTextInspection
-							? redactSensitiveText(inspectionText ?? "")
-							: parseSucceeded
-								? undefined
-								: redactSensitiveText(processResult.stdout),
-						summary: redactSensitiveText(presentation.summary),
-					},
-					isError: !succeeded,
-				};
-			} finally {
-				if (processResult.stdoutSpillPath) {
-					await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
+						parseError,
+						plainTextInspection,
+						spawnError: processResult.spawnError,
+						stderr: processResult.stderr,
+						wrapperRecoveryHint: buildWrapperRecoveryHint({ pinnedBatchUnwrapMode, sessionTabCorrection }),
+					});
+
+					const presentation = plainTextInspection
+						? {
+							artifacts: undefined,
+							batchFailure: undefined,
+							batchSteps: undefined,
+							content: [{ type: "text" as const, text: inspectionText ?? "" }],
+							data: undefined,
+							fullOutputPath: undefined,
+							fullOutputPaths: undefined,
+							imagePath: undefined,
+							imagePaths: undefined,
+							savedFile: undefined,
+							savedFilePath: undefined,
+							summary: `${redactedArgs.join(" ")} completed`,
+						  }
+						: await buildToolPresentation({
+								artifactManifest,
+								commandInfo: executionPlan.commandInfo,
+								cwd: ctx.cwd,
+								envelope: presentationEnvelope,
+								errorText,
+								persistentArtifactStore,
+						  });
+					if (parseFailureOutput.artifactManifest) {
+						presentation.artifactManifest = parseFailureOutput.artifactManifest;
+						presentation.artifactRetentionSummary = parseFailureOutput.artifactRetentionSummary;
+					}
+					if (parseFailureOutput.fullOutputPath || parseFailureOutput.fullOutputUnavailable) {
+						const existingText = presentation.content[0]?.type === "text" ? presentation.content[0].text : "";
+						const noticeLines = [
+							parseFailureOutput.fullOutputPath
+								? `Full output path: ${parseFailureOutput.fullOutputPath}`
+								: `Full raw output unavailable: ${parseFailureOutput.fullOutputUnavailable}`,
+							parseFailureOutput.artifactRetentionSummary,
+						].filter((item): item is string => item !== undefined);
+						const notice = noticeLines.join("\n");
+						presentation.content[0] = {
+							type: "text",
+							text: existingText.length > 0 ? `${existingText}\n\n${notice}` : notice,
+						};
+					}
+					if (presentation.artifactManifest) {
+						artifactManifest = presentation.artifactManifest;
+					}
+					const contentWithSessionWarnings = aboutBlankSessionMismatch ? [...presentation.content] : presentation.content;
+					if (aboutBlankSessionMismatch) {
+						const warning = buildAboutBlankWarning(aboutBlankSessionMismatch);
+						if (contentWithSessionWarnings[0]?.type === "text") {
+							contentWithSessionWarnings[0] = {
+								...contentWithSessionWarnings[0],
+								text: `${warning}\n\n${contentWithSessionWarnings[0].text}`,
+							};
+						} else {
+							contentWithSessionWarnings.unshift({ type: "text", text: warning });
+						}
+					}
+					const redactedContent = contentWithSessionWarnings.map((item) =>
+						item.type === "text" ? { ...item, text: redactSensitiveText(item.text) } : item,
+					);
+
+					return {
+						content: redactedContent,
+						details: {
+							args: redactedArgs,
+							artifactManifest: redactSensitiveValue(presentation.artifactManifest),
+							artifactRetentionSummary: presentation.artifactRetentionSummary,
+							artifacts: redactSensitiveValue(presentation.artifacts),
+							batchFailure: redactSensitiveValue(presentation.batchFailure),
+							batchSteps: redactSensitiveValue(presentation.batchSteps),
+							command: executionPlan.commandInfo.command,
+							compatibilityWorkaround,
+							subcommand: executionPlan.commandInfo.subcommand,
+							data: redactSensitiveValue(presentation.data),
+							error: plainTextInspection ? undefined : redactSensitiveValue(presentationEnvelope?.error),
+							inspection: plainTextInspection || undefined,
+							navigationSummary: redactSensitiveValue(navigationSummary),
+							aboutBlankSessionMismatch: redactSensitiveValue(aboutBlankSessionMismatch),
+							openResultTabCorrection: redactSensitiveValue(openResultTabCorrection),
+							effectiveArgs: redactedProcessArgs,
+							exitCode: processResult.exitCode,
+							fullOutputPath: parseFailureOutput.fullOutputPath ?? presentation.fullOutputPath,
+							fullOutputPaths: presentation.fullOutputPaths,
+							fullOutputUnavailable: parseFailureOutput.fullOutputUnavailable,
+							imagePath: presentation.imagePath,
+							imagePaths: presentation.imagePaths,
+							parseError: plainTextInspection ? undefined : parseError,
+							savedFile: redactSensitiveValue(presentation.savedFile),
+							savedFilePath: presentation.savedFilePath ? redactSensitiveText(presentation.savedFilePath) : undefined,
+							sessionMode,
+							sessionTabCorrection: redactSensitiveValue(sessionTabCorrection),
+							sessionTabTarget: redactSensitiveValue(currentSessionTabTarget),
+							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+							sessionRecoveryHint: redactedRecoveryHint,
+							startupScopedFlags: executionPlan.startupScopedFlags,
+							stderr: processResult.stderr ? redactSensitiveText(processResult.stderr) : undefined,
+							stdout: plainTextInspection
+								? redactSensitiveText(inspectionText ?? "")
+								: parseSucceeded
+									? undefined
+									: redactSensitiveText(processResult.stdout),
+							summary: redactSensitiveText(presentation.summary),
+						},
+						isError: !succeeded,
+					};
+				} finally {
+					if (processResult.stdoutSpillPath) {
+						await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
+					}
 				}
-			}
+			};
+
+			return extractExplicitSessionName(params.args)
+				? runTool()
+				: managedSessionExecutionQueue.run(runTool);
 		},
 	});
 }