pi-agent-browser-native 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.3 - 2026-04-13
+
+### Fixed
+- direct headless local Chrome launches to `chatgpt.com` and `chat.openai.com` now inject a normal Chrome user agent when the caller did not explicitly choose one, keeping authenticated ChatGPT/OpenAI browsing working without forcing `--headed` or `--auto-connect`
+- profiled `open` / `goto` / `navigate` calls now best-effort switch back to the page that was just opened when restored profile tabs steal focus during launch, reducing confusing cross-tab drift in profile-backed sessions
+- command parsing now treats additional value-taking global flags like `--user-agent`, `--args`, `--allowed-domains`, `--action-policy`, and related launch options as launch metadata instead of accidentally parsing their values as subcommands
+- README, requirements, architecture notes, and tool-contract docs now describe the new headless ChatGPT/OpenAI compatibility behavior and the profiled-tab focus recovery path
+
 ## 0.2.2 - 2026-04-12
 
 ### Fixed

package/README.md

@@ -178,6 +178,8 @@ Validated workflow examples:
 - click a link and confirm the destination title
 - use an explicit `--session` across multiple tool calls
 - use an explicit `--profile` and verify persisted browser storage across restarts
+- open `chatgpt.com` headlessly with `--profile Default` without forcing `--headed` or `--auto-connect`
+- verify `/reload` and full restart + `/resume` keep following the same implicit managed browser session
 - run `batch` with JSON via `stdin`
 - run `eval --stdin`
 - take a screenshot with inline attachment support
@@ -188,9 +190,12 @@ Inspection commands like `agent_browser --help` and `--version` are always suppo
 Current cautions:
 - passing `--profile` is an explicit upstream choice; this extension does not add its own profile-cloning or isolation layer
 - startup-scoped flags like `--profile`, `--session-name`, and `--cdp` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
-- implicit `piab-*` sessions are extension-managed convenience sessions; they are best-effort closed on `pi` shutdown, get an idle timeout to reduce stale background daemons, clean up private temp spill artifacts on shutdown, and are reconstructed from persisted tool details on resume/reload so later default calls keep following the active managed browser
+- implicit `piab-*` sessions are extension-managed convenience sessions; they stay alive across `pi` shutdown/reload so later default calls can keep following the active managed browser on `/reload` or `/resume`, rely on the configured idle timeout to reduce stale background daemons, store persisted-session large snapshot spill files under a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` survives reload/resume without unbounded growth, and still clean up process-private temp spill artifacts on shutdown
 - `sessionMode: "fresh"` without an explicit `--session` rotates that extension-managed session to the new browser so later auto calls keep using it
+- for direct headless local Chrome launches to `chatgpt.com` and `chat.openai.com`, the extension injects a normal Chrome user agent when the caller did not explicitly provide `--user-agent`; this keeps the default headless workflow usable without forcing `--headed` or `--auto-connect`
+- after profiled `open` calls, the extension best-effort re-selects the tab that matches the returned page URL when restored profile tabs steal focus during launch
 - explicit caller-provided `--session` values are treated as user-managed and are not auto-closed by the extension
+- explicit caller-provided `--user-agent` values win over the ChatGPT/OpenAI compatibility workaround
 - tool progress/details redact sensitive invocation values such as `--headers`, proxy credentials, and auth-bearing URL parameters before echoing them back into Pi
 
 ### Switching from public browsing to a fresh profile/debug launch

package/docs/ARCHITECTURE.md

@@ -78,17 +78,18 @@ V1 ownership rule:
 - implicit auto-generated sessions are extension-managed convenience sessions
 - unnamed `sessionMode: "fresh"` launches rotate that extension-managed session to a new upstream browser
 - explicit/user-managed sessions are not auto-managed by default
-- extension-managed sessions should be reusable during an active `pi` session, but should still be cleaned up predictably
+- extension-managed sessions should be reusable during an active `pi` session and across `/reload` / `/resume`, while still being cleaned up predictably
 
 Practical policy:
-- on normal `pi` shutdown, best-effort close the current extension-managed session
-- also set an idle timeout on extension-managed sessions so abandoned daemons self-clean after inactivity
-- clean up private temp spill artifacts owned by the extension-managed session on shutdown
+- preserve the current extension-managed session across normal `pi` shutdown/reload so persisted sessions can keep following the live browser after `/reload` or `/resume`
+- set an idle timeout on extension-managed sessions so abandoned daemons self-clean after inactivity
+- clean up process-private temp spill artifacts on shutdown, but keep persisted-session snapshot spill files in a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` stays usable after reload/resume without unbounded growth
 - reconstruct the current extension-managed session from persisted tool details on resume/reload so later default calls keep following the active managed browser
 - if an unnamed fresh launch replaces an active extension-managed session, best-effort close the old managed session after the switch succeeds
 - leave explicit caller-provided `--session` choices alone unless the caller closes them explicitly
+- after profiled `open` / `goto` / `navigate` calls, verify the active tab still matches the returned page URL and best-effort switch back when restored profile tabs steal focus
 
-This is primarily about ownership clarity and avoiding surprise, not adding a heavy safety wrapper. If the extension invented the session, the extension should clean it up. If the caller explicitly chose the upstream session model, the extension should stay out of the way.
+This is primarily about ownership clarity and avoiding surprise, not adding a heavy safety wrapper. If the extension invented the session, the extension should own its lifecycle without breaking reload/resume semantics. If the caller explicitly chose the upstream session model, the extension should stay out of the way.
 
 ### Launch flags
 
@@ -97,6 +98,8 @@ The extension should surface that clearly and avoid hidden restart behavior in v
 
 That means explicit startup-scoping flags like `--profile`, `--session-name`, and `--cdp` should remain explicit upstream choices instead of being wrapped in extra hidden restart or cloning logic.
 
+The wrapper may still apply narrow compatibility normalizations when observed behavior justifies them and the result remains thin, local, and opt-out. For example, if a specific site starts rejecting the default local headless Chrome user agent while the same flow works with a normal Chrome UA, the extension may inject a domain-specific fallback UA only when the caller did not already choose `--user-agent`, `--headed`, `--cdp`, `--auto-connect`, or a provider-backed launch.
+
 If the implicit session is already active and one of those startup-scoped flags appears again while `sessionMode` is still `"auto"`, the extension should fail clearly instead of silently sending a command shape that upstream would ignore.
 
 That failure should include a structured recovery hint pointing to `sessionMode: "fresh"` as the first-line fix, while still allowing an explicit `--session` when the caller wants to name the new upstream session.

package/docs/RELEASE.md

@@ -57,13 +57,21 @@ Before publishing, also validate the explicit local-checkout path:
 2. Launch `pi --no-extensions -e .` from this repository root.
 3. Confirm the checkout extension loads from `extensions/agent-browser/index.ts`.
 4. Run a smoke prompt that exercises `agent_browser`.
+5. Validate managed-session continuity with both `/reload` and a full restart + `/resume`.
 
-Example prompt:
+Example smoke prompt:
 
 ```text
 Use the agent_browser tool to open https://react.dev and then take an interactive snapshot.
 ```
 
+Recommended lifecycle follow-up:
+
+1. Open a page with the implicit managed session and confirm the title.
+2. Run `/reload`, then ask for `snapshot -i` and confirm the same page is still active.
+3. Exit `pi`, relaunch it against the same session file or use `/resume`, then ask for `snapshot -i` again and confirm the same page is still active.
+4. Open a large page that compacts its snapshot output and confirm `details.fullOutputPath` still exists after the restart/resume flow.
+
 ## Post-publish install validation
 
 After publishing a release, validate the package-first install path explicitly:
@@ -73,7 +81,7 @@ pi install npm:pi-agent-browser-native@<version>
 pi -e npm:pi-agent-browser-native@<version>
 ```
 
-Then confirm `pi` exposes the native `agent_browser` tool and that a basic `open` + `snapshot -i` flow works.
+Then confirm `pi` exposes the native `agent_browser` tool, that a basic `open` + `snapshot -i` flow works, and that `/reload` plus restart/`/resume` keep following the same implicit managed browser session.
 
 ## Release notes checklist
 
@@ -83,4 +91,5 @@ Before publishing:
 - confirm README install guidance still leads with the package-first flow
 - confirm the explicit local-checkout instructions still work for pre-release validation
 - rerun `npm run verify:release`
+- manually exercise `/reload` and full restart + `/resume` continuity in local checkout validation
 - publish only after the tarball contents match expectations

package/docs/REQUIREMENTS.md

@@ -71,7 +71,8 @@ Define the product requirements and constraints for `pi-agent-browser-native`.
 
 - The primary confidence path is a real `pi` session driven in `tmux`.
 - For local checkout validation, launch `pi --no-extensions -e .` from the repository root so only the checkout copy loads.
-- Prefer full `pi` restart over `/reload` when validating extension changes.
+- Validate both `/reload` and a full `pi` restart with `/resume` when changes touch managed-session continuity, reload behavior, or persisted artifact paths.
+- Prefer full `pi` restart over `/reload` when validating extension changes beyond a quick reload smoke check.
 - Use `/resume` when needed after restart.
 - Keep testing broader than a single smoke site like `example.com`.
 - Maintain a concrete release/package verification workflow in `docs/RELEASE.md` and matching repository scripts.
@@ -84,6 +85,7 @@ The design should comfortably support workflows such as:
 - web research
 - using browser UIs for other LLMs such as ChatGPT, Grok, Gemini, and Claude
 - isolated authenticated browser sessions
+- headless authenticated ChatGPT/OpenAI browsing without forcing `--headed` or `--auto-connect`
 - upstream profile/debug workflows without adding a local profile-cloning layer in this package
 
 ## Implications for the implementation
@@ -94,6 +96,8 @@ The design should comfortably support workflows such as:
 - User-facing docs belong in `README.md` and the canonical published files under `docs/`.
 - Agent workflow and deeper testing procedures can stay in `AGENTS.md`, but published docs must not depend on that file being present.
 - Keep mitigations for legacy-skill coexistence simple; do not add extra moving parts unless observed behavior justifies them.
+- Prefer narrow, evidence-backed compatibility mitigations over broad stealth layers when a specific upstream site starts rejecting the default headless launch fingerprint.
+- Preserve the page that a profiled `open` just navigated to; if restored profile tabs steal focus during launch, the wrapper should best-effort switch back to the returned page URL before handing control back to the agent.
 
 ## Open design questions
 

package/docs/TOOL_CONTRACT.md

@@ -141,13 +141,13 @@ Additional structured fields can appear when relevant:
 - `batchFailure` and `batchSteps` for `batch` rendering, including mixed-success runs
 - `navigationSummary` for navigation-style commands like `click`, `back`, `forward`, and `reload`
 - `imagePath` / `imagePaths` for screenshots and batched image outputs
-- `fullOutputPath` / `fullOutputPaths` when large snapshot output is compacted and spilled to a private temp file
+- `fullOutputPath` / `fullOutputPaths` when large snapshot output is compacted and spilled to a private file; persisted sessions keep that path under a private session-scoped artifact directory with a bounded per-session budget so it survives reload/resume without unbounded growth
 - `sessionRecoveryHint` when startup-scoped flags need `sessionMode: "fresh"`
 - `inspection: true` plus `stdout` for successful plain-text inspection commands like `--help` and `--version`
 
 When the tool echoes `args` or `effectiveArgs` back into Pi, sensitive values such as `--headers`, proxy credentials, and auth-bearing URL parameters should be redacted first.
 
-For oversized snapshots, details should switch to a compact metadata object and include `fullOutputPath` pointing at a private temp JSON spill file with the full upstream snapshot payload.
+For oversized snapshots, details should switch to a compact metadata object and include `fullOutputPath` pointing at a private JSON spill file with the full upstream snapshot payload. Persisted sessions should keep that spill file under a private session-scoped artifact directory so the path remains usable after reload/restart, with the oldest persisted spill files evicted as needed to stay within the per-session budget.
 
 ## High-value result rendering
 
@@ -156,6 +156,7 @@ For oversized snapshots, details should switch to a compact metadata object and
 Worth doing in v1:
 - screenshots → inline image attachment
 - snapshots → origin + ref count + main-content-first compact preview, with the raw snapshot spill path kept in `details.fullOutputPath` when the inline result would otherwise be too large
+- extraction-style commands like `eval --stdin` and `get title` → scalar-first text with lightweight origin context when available
 - navigation actions like `click`, `back`, `forward`, and `reload` → lightweight post-action title/url summary when available
 - tab lists → compact summary/table
 - stream status → enabled/connected/port summary
@@ -173,16 +174,18 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - derive the base implicit session name from the official `pi` session id plus a cwd hash so same-named checkouts do not collide
 - respect explicit upstream `--session` with minimal interference
 - treat the extension-managed session as convenience state owned by the wrapper
-- on normal `pi` shutdown, best-effort close the current extension-managed session
+- preserve the current extension-managed session across normal `pi` shutdown/reload so persisted sessions can keep following the live browser on `/reload` or `/resume`
 - set an idle timeout on extension-managed sessions so abandoned daemons eventually self-clean
-- clean up private temp spill artifacts owned by the extension-managed session on shutdown
+- clean up process-private temp spill artifacts on shutdown, while keeping persisted-session snapshot spill files in a private session-scoped artifact directory so `details.fullOutputPath` survives reload/restart and the oldest spill files are evicted if the per-session artifact budget is exceeded
 - reconstruct the current extension-managed session from persisted tool details on resume/reload so later default calls keep following the active managed browser
 - when an unnamed `sessionMode: "fresh"` launch succeeds, make it the new extension-managed session so later default calls keep using it
 - if that unnamed fresh launch replaced an already-active managed session, best-effort close the old managed session after the switch succeeds
 - treat explicit caller-provided `--session` choices as user-managed
 - pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
+- after profiled `open` / `goto` / `navigate`, if upstream leaves a restored profile tab active instead of the page that was just opened, best-effort switch back to the tab whose URL matches the returned open result before returning control to the agent
 - treat successful plain-text inspection commands like `--help` and `--version` as stateless: do not inject the implicit managed session and do not let those calls claim the managed-session slot
 - if startup-scoped flags like `--profile`, `--session-name`, or `--cdp` are supplied after the implicit session is already active while `sessionMode` is `"auto"`, return a validation error with a structured recovery hint that recommends `sessionMode: "fresh"`
+- for direct headless local Chrome launches to `chatgpt.com` / `chat.openai.com`, allow a narrow compatibility fallback that injects a normal Chrome `--user-agent` only when the caller did not explicitly provide one and did not choose `--headed`, `--cdp`, `--auto-connect`, or a provider-backed launch
 
 ## Non-goals
 

package/extensions/agent-browser/index.ts

@@ -16,6 +16,7 @@ import { buildToolPresentation, getAgentBrowserErrorText, parseAgentBrowserEnvel
 import {
 	buildExecutionPlan,
 	buildPromptPolicy,
+	chooseOpenResultTabCorrection,
 	createEphemeralSessionSeed,
 	createFreshSessionName,
 	createImplicitSessionName,
@@ -30,8 +31,10 @@ import {
 	resolveManagedSessionState,
 	shouldAppendBrowserSystemPrompt,
 	validateToolArgs,
+	type CompatibilityWorkaround,
+	type OpenResultTabCorrection,
 } from "./lib/runtime.js";
-import { cleanupSecureTempArtifacts } from "./lib/temp.js";
+import { cleanupSecureTempArtifacts, type PersistentSessionArtifactStore } from "./lib/temp.js";
 
 const DEFAULT_SESSION_MODE = "auto" as const;
 
@@ -96,15 +99,184 @@ function buildInvocationPreview(effectiveArgs: string[]): string {
 	return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
 }
 
-const AGENT_BROWSER_BASH_PREFIX = String.raw`(?:env(?:\s+[A-Za-z_][A-Za-z0-9_]*=[^\s;&|]+)*\s+)?(?:(?:npx|bunx)(?:\s+-[^\s;&|]+|\s+--[^\s;&|]+(?:=[^\s;&|]+)?)*\s+|(?:pnpm|yarn)\s+dlx(?:\s+-[^\s;&|]+|\s+--[^\s;&|]+(?:=[^\s;&|]+)?)*\s+)?`;
-const AGENT_BROWSER_BASH_EXECUTABLE = String.raw`(?:[.~]|\.\.?|\/)?(?:[^\s;&|]+\/)?agent-browser`;
-const DIRECT_AGENT_BROWSER_BASH_PATTERN = new RegExp(
-	String.raw`(^|[\s;&|])${AGENT_BROWSER_BASH_PREFIX}${AGENT_BROWSER_BASH_EXECUTABLE}(?=\s|$)`,
-);
-const HARMLESS_AGENT_BROWSER_INSPECTION_PATTERN = /(command\s+-v|which|type\s+-P)\s+agent-browser\b/;
+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 {
-	return DIRECT_AGENT_BROWSER_BASH_PATTERN.test(command);
+	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 {
@@ -142,41 +314,53 @@ function extractStringResultField(data: unknown, fieldName: "title" | "url"): st
 	return text.length > 0 ? text : undefined;
 }
 
-async function collectNavigationSummary(options: {
+async function runSessionCommandData(options: {
+	args: string[];
 	cwd: string;
 	sessionName?: string;
 	signal?: AbortSignal;
-}): Promise<NavigationSummary | undefined> {
-	const { cwd, sessionName, signal } = options;
+}): Promise<unknown | undefined> {
+	const { args, cwd, sessionName, signal } = options;
 	if (!sessionName) return undefined;
 
-	const readField = async (fieldName: "title" | "url"): Promise<string | undefined> => {
-		const processResult = await runAgentBrowserProcess({
-			args: ["--json", "--session", sessionName, "get", fieldName],
-			cwd,
-			signal,
-		});
-		if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0) {
+	const processResult = await runAgentBrowserProcess({
+		args: ["--json", "--session", sessionName, ...args],
+		cwd,
+		signal,
+	});
+	if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0) {
+		return undefined;
+	}
+	const parsed = await parseAgentBrowserEnvelope({
+		stdout: processResult.stdout,
+		stdoutPath: processResult.stdoutSpillPath,
+	});
+	try {
+		if (parsed.parseError || parsed.envelope?.success === false) {
 			return undefined;
 		}
-		const parsed = await parseAgentBrowserEnvelope({
-			stdout: processResult.stdout,
-			stdoutPath: processResult.stdoutSpillPath,
-		});
-		try {
-			if (parsed.parseError || parsed.envelope?.success === false) {
-				return undefined;
-			}
-			return extractStringResultField(parsed.envelope?.data, fieldName);
-		} finally {
-			if (processResult.stdoutSpillPath) {
-				await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
-			}
+		return parsed.envelope?.data;
+	} finally {
+		if (processResult.stdoutSpillPath) {
+			await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
 		}
-	};
+	}
+}
 
-	const title = await readField("title");
-	const url = await readField("url");
+async function collectNavigationSummary(options: {
+	cwd: string;
+	sessionName?: string;
+	signal?: AbortSignal;
+}): Promise<NavigationSummary | undefined> {
+	const { cwd, sessionName, signal } = options;
+	const title = extractStringResultField(
+		await runSessionCommandData({ args: ["get", "title"], cwd, sessionName, signal }),
+		"title",
+	);
+	const url = extractStringResultField(
+		await runSessionCommandData({ args: ["get", "url"], cwd, sessionName, signal }),
+		"url",
+	);
 	if (!title && !url) return undefined;
 	return { title, url };
 }
@@ -188,6 +372,43 @@ function mergeNavigationSummaryIntoData(data: unknown, navigationSummary: Naviga
 	return { navigationSummary, result: data };
 }
 
+async function collectOpenResultTabCorrection(options: {
+	cwd: string;
+	sessionName?: string;
+	signal?: AbortSignal;
+	targetTitle?: string;
+	targetUrl?: string;
+}): Promise<OpenResultTabCorrection | undefined> {
+	const { cwd, sessionName, signal, targetTitle, targetUrl } = options;
+	const tabData = await runSessionCommandData({ args: ["tab", "list"], cwd, sessionName, signal });
+	if (!isRecord(tabData) || !Array.isArray(tabData.tabs)) {
+		return undefined;
+	}
+	const tabs = tabData.tabs.filter(isRecord).map((tab) => ({
+		active: tab.active === true,
+		index: typeof tab.index === "number" ? tab.index : undefined,
+		title: typeof tab.title === "string" ? tab.title : undefined,
+		url: typeof tab.url === "string" ? tab.url : undefined,
+	}));
+	return chooseOpenResultTabCorrection({ tabs, targetTitle, targetUrl });
+}
+
+async function applyOpenResultTabCorrection(options: {
+	correction: OpenResultTabCorrection;
+	cwd: string;
+	sessionName?: string;
+	signal?: AbortSignal;
+}): Promise<OpenResultTabCorrection | undefined> {
+	const { correction, cwd, sessionName, signal } = options;
+	const result = await runSessionCommandData({
+		args: ["tab", String(correction.selectedIndex)],
+		cwd,
+		sessionName,
+		signal,
+	});
+	return result === undefined ? undefined : correction;
+}
+
 function buildSharedBrowserPlaybookGuidelines(hasBraveApiKey: boolean): string[] {
 	return [
 		SHARED_BROWSER_PLAYBOOK_GUIDELINES[0],
@@ -209,6 +430,22 @@ function buildSessionDetailFields(sessionName: string | undefined, usedImplicitS
 	return sessionName ? { sessionName, usedImplicitSession } : {};
 }
 
+function getPersistentSessionArtifactStore(ctx: {
+	sessionManager: {
+		getSessionDir?: () => string;
+		getSessionFile?: () => string | undefined;
+		getSessionId: () => string | undefined;
+	};
+}): PersistentSessionArtifactStore | undefined {
+	const sessionFile = typeof ctx.sessionManager.getSessionFile === "function" ? ctx.sessionManager.getSessionFile() : undefined;
+	const sessionDir = typeof ctx.sessionManager.getSessionDir === "function" ? ctx.sessionManager.getSessionDir() : undefined;
+	const sessionId = ctx.sessionManager.getSessionId();
+	if (!sessionFile || !sessionDir || !sessionId) {
+		return undefined;
+	}
+	return { sessionDir, sessionId };
+}
+
 function redactRecoveryHint(recoveryHint: {
 	exampleArgs: string[];
 	exampleParams: { args: string[]; sessionMode: "fresh" };
@@ -267,13 +504,6 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", async () => {
-		if (managedSessionActive) {
-			await closeManagedSession({
-				cwd: managedSessionCwd,
-				sessionName: managedSessionName,
-				timeoutMs: implicitSessionCloseTimeoutMs,
-			});
-		}
 		managedSessionActive = false;
 		await cleanupSecureTempArtifacts();
 	});
@@ -332,6 +562,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			});
 			const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);
 			const redactedRecoveryHint = redactRecoveryHint(executionPlan.recoveryHint);
+			const compatibilityWorkaround: CompatibilityWorkaround | undefined = executionPlan.compatibilityWorkaround;
 			if (executionPlan.managedSessionName === freshSessionName) {
 				freshSessionOrdinal += 1;
 			}
@@ -354,6 +585,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			onUpdate?.({
 				content: [{ type: "text", text: `Running agent-browser ${buildInvocationPreview(redactedEffectiveArgs)}` }],
 				details: {
+					compatibilityWorkaround,
 					effectiveArgs: redactedEffectiveArgs,
 					sessionMode,
 					...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
@@ -374,6 +606,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					content: [{ type: "text", text: errorText }],
 					details: {
 						args: redactedArgs,
+						compatibilityWorkaround,
 						effectiveArgs: redactedEffectiveArgs,
 						sessionMode,
 						spawnError: processResult.spawnError.message,
@@ -410,6 +643,34 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					}
 				}
 
+				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(parsed.envelope?.data, "title");
+					const targetUrl = extractStringResultField(parsed.envelope?.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 priorManagedSessionCwd = managedSessionCwd;
 				const managedSessionState = resolveManagedSessionState({
 					command: executionPlan.commandInfo.command,
@@ -459,6 +720,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							cwd: ctx.cwd,
 							envelope: presentationEnvelope,
 							errorText,
+							persistentArtifactStore: getPersistentSessionArtifactStore(ctx),
 					  });
 				const redactedContent = presentation.content.map((item) =>
 					item.type === "text" ? { ...item, text: redactSensitiveText(item.text) } : item,
@@ -471,11 +733,13 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						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(parsed.envelope?.error),
 						inspection: plainTextInspection || undefined,
 						navigationSummary: redactSensitiveValue(navigationSummary),
+						openResultTabCorrection: redactSensitiveValue(openResultTabCorrection),
 						effectiveArgs: redactedEffectiveArgs,
 						exitCode: processResult.exitCode,
 						fullOutputPath: presentation.fullOutputPath,

package/extensions/agent-browser/lib/results/presentation.ts

@@ -10,6 +10,7 @@ import { readFile, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 
 import { parseCommandInfo, type CommandInfo } from "../runtime.js";
+import { type PersistentSessionArtifactStore } from "../temp.js";
 import { buildSnapshotPresentation, formatRawSnapshotText, formatSnapshotSummary } from "./snapshot.js";
 import {
 	type AgentBrowserBatchResult,
@@ -106,6 +107,63 @@ function getScreenshotSummary(data: Record<string, unknown>): string | undefined
 	return typeof data.path === "string" ? `Saved image: ${data.path}` : undefined;
 }
 
+function getScalarExtractionResult(data: Record<string, unknown>): string | undefined {
+	const { result } = data;
+	if (typeof result === "string") {
+		return result.trim().length > 0 ? result : undefined;
+	}
+	if (typeof result === "number" || typeof result === "boolean") {
+		return String(result);
+	}
+	return undefined;
+}
+
+function getExtractionOrigin(data: Record<string, unknown>): string | undefined {
+	if (typeof data.origin === "string" && data.origin.trim().length > 0) {
+		return data.origin.trim();
+	}
+	if (typeof data.url === "string" && data.url.trim().length > 0) {
+		return data.url.trim();
+	}
+	return undefined;
+}
+
+function formatGetSummaryLabel(subcommand: string | undefined): string {
+	if (!subcommand) {
+		return "Get result";
+	}
+	if (subcommand.toLowerCase() === "url") {
+		return "URL";
+	}
+	return `${subcommand.slice(0, 1).toUpperCase()}${subcommand.slice(1)}`;
+}
+
+function formatExtractionSummary(commandInfo: CommandInfo, data: Record<string, unknown>): string | undefined {
+	const scalarResult = getScalarExtractionResult(data);
+	if (!scalarResult) {
+		return undefined;
+	}
+	if (commandInfo.command === "get") {
+		return `${formatGetSummaryLabel(commandInfo.subcommand)}: ${scalarResult.split("\n", 1)[0] ?? scalarResult}`;
+	}
+	if (commandInfo.command === "eval") {
+		return `Eval result: ${scalarResult.split("\n", 1)[0] ?? scalarResult}`;
+	}
+	return undefined;
+}
+
+function formatExtractionText(commandInfo: CommandInfo, data: Record<string, unknown>): string | undefined {
+	if (commandInfo.command !== "get" && commandInfo.command !== "eval") {
+		return undefined;
+	}
+	const scalarResult = getScalarExtractionResult(data);
+	if (!scalarResult) {
+		return undefined;
+	}
+	const origin = getExtractionOrigin(data);
+	return origin && origin !== scalarResult ? `${scalarResult}\n\nOrigin: ${origin}` : scalarResult;
+}
+
 function isNavigationObservableCommand(command: string | undefined): boolean {
 	return command !== undefined && NAVIGATION_SUMMARY_COMMANDS.has(command);
 }
@@ -207,8 +265,9 @@ async function buildBatchStepPresentation(options: {
 	cwd: string;
 	index: number;
 	item: AgentBrowserBatchResult;
+	persistentArtifactStore?: PersistentSessionArtifactStore;
 }): Promise<{ details: BatchStepPresentationDetails; presentation: ToolPresentation }> {
-	const { cwd, index, item } = options;
+	const { cwd, index, item, persistentArtifactStore } = options;
 	const command = isStringArray(item.command) ? item.command : undefined;
 	const commandText = formatBatchStepCommand(command, index);
 
@@ -236,6 +295,7 @@ async function buildBatchStepPresentation(options: {
 		commandInfo: parseCommandInfo(command ?? []),
 		cwd,
 		envelope: { data: item.result, success: true },
+		persistentArtifactStore,
 	});
 	const fullOutputPaths = getPresentationPaths({
 		primaryPath: presentation.fullOutputPath,
@@ -268,12 +328,28 @@ async function buildBatchStepPresentation(options: {
 async function buildBatchPresentation(options: {
 	cwd: string;
 	data: AgentBrowserBatchResult[];
+	persistentArtifactStore?: PersistentSessionArtifactStore;
 	summary: string;
 }): Promise<ToolPresentation> {
-	const { cwd, data, summary } = options;
+	const { cwd, data, persistentArtifactStore, summary } = options;
 	const steps: Array<{ details: BatchStepPresentationDetails; presentation: ToolPresentation }> = [];
+	const protectedPersistentPaths: string[] = [];
 	for (const [index, item] of data.entries()) {
-		steps.push(await buildBatchStepPresentation({ cwd, index, item }));
+		const step = await buildBatchStepPresentation({
+			cwd,
+			index,
+			item,
+			persistentArtifactStore: persistentArtifactStore
+				? { ...persistentArtifactStore, protectedPaths: protectedPersistentPaths }
+				: undefined,
+		});
+		steps.push(step);
+		protectedPersistentPaths.push(
+			...getPresentationPaths({
+				primaryPath: step.presentation.fullOutputPath,
+				secondaryPaths: step.presentation.fullOutputPaths,
+			}),
+		);
 	}
 
 	const batchFailure = getBatchFailureDetails(steps);
@@ -354,6 +430,10 @@ function formatSummary(commandInfo: CommandInfo, data: unknown): string {
 		if (commandInfo.command === "screenshot" && typeof data.path === "string") {
 			return `Screenshot saved: ${data.path}`;
 		}
+		const extractionSummary = formatExtractionSummary(commandInfo, data);
+		if (extractionSummary) {
+			return extractionSummary;
+		}
 		const pageSummary = getPageSummary(data);
 		if (pageSummary) {
 			return pageSummary.split("\n", 1)[0] ?? "agent-browser result";
@@ -404,6 +484,11 @@ function formatContentText(commandInfo: CommandInfo, data: unknown): string {
 		if (screenshotSummary) return screenshotSummary;
 	}
 
+	const extractionText = formatExtractionText(commandInfo, data);
+	if (extractionText) {
+		return extractionText;
+	}
+
 	const pageSummary = getPageSummary(data);
 	if (pageSummary) {
 		return pageSummary;
@@ -459,8 +544,9 @@ export async function buildToolPresentation(options: {
 	cwd: string;
 	envelope?: AgentBrowserEnvelope;
 	errorText?: string;
+	persistentArtifactStore?: PersistentSessionArtifactStore;
 }): Promise<ToolPresentation> {
-	const { commandInfo, cwd, envelope, errorText } = options;
+	const { commandInfo, cwd, envelope, errorText, persistentArtifactStore } = options;
 	if (errorText) {
 		return {
 			content: [{ type: "text", text: errorText }],
@@ -472,9 +558,9 @@ export async function buildToolPresentation(options: {
 	const summary = formatSummary(commandInfo, data);
 	const presentation =
 		commandInfo.command === "batch" && Array.isArray(data)
-			? await buildBatchPresentation({ cwd, data: data as AgentBrowserBatchResult[], summary })
+			? await buildBatchPresentation({ cwd, data: data as AgentBrowserBatchResult[], persistentArtifactStore, summary })
 			: commandInfo.command === "snapshot" && isRecord(data)
-				? await buildSnapshotPresentation(data)
+				? await buildSnapshotPresentation(data, persistentArtifactStore)
 				: {
 						content: [{ type: "text" as const, text: formatContentText(commandInfo, data) }],
 						data,

package/extensions/agent-browser/lib/results/snapshot.ts

@@ -6,7 +6,7 @@
  * Invariants/Assumptions: Snapshot compaction should stay helpful even if upstream snapshot text formatting shifts, so structured parsing is best-effort and always has a resilient raw-outline fallback.
  */
 
-import { writeSecureTempFile } from "../temp.js";
+import { type PersistentSessionArtifactStore, writePersistentSessionArtifactFile, writeSecureTempFile } from "../temp.js";
 import { type ToolPresentation, compareRefIds, countLines, isRecord, normalizeWhitespace, truncateText } from "./shared.js";
 
 const SNAPSHOT_INLINE_MAX_CHARS = 6_000;
@@ -463,12 +463,18 @@ function canUseStructuredSnapshotPreview(snapshotLines: SnapshotLine[], refEntri
 	);
 }
 
-async function writeSnapshotSpillFile(data: Record<string, unknown>): Promise<string> {
-	return await writeSecureTempFile({
+async function writeSnapshotSpillFile(
+	data: Record<string, unknown>,
+	persistentArtifactStore: PersistentSessionArtifactStore | undefined,
+): Promise<string> {
+	const options = {
 		content: JSON.stringify(data, null, 2),
 		prefix: SNAPSHOT_SPILL_FILE_PREFIX,
 		suffix: ".json",
-	});
+	};
+	return persistentArtifactStore
+		? await writePersistentSessionArtifactFile({ ...options, store: persistentArtifactStore })
+		: await writeSecureTempFile(options);
 }
 
 export function formatSnapshotSummary(data: Record<string, unknown>): string {
@@ -487,7 +493,10 @@ export function formatRawSnapshotText(data: Record<string, unknown>): string {
 	return `Origin: ${origin}\nRefs: ${refs}\n\n${snapshot}`;
 }
 
-export async function buildSnapshotPresentation(data: Record<string, unknown>): Promise<ToolPresentation> {
+export async function buildSnapshotPresentation(
+	data: Record<string, unknown>,
+	persistentArtifactStore: PersistentSessionArtifactStore | undefined = undefined,
+): Promise<ToolPresentation> {
 	const summary = formatSnapshotSummary(data);
 	const rawText = formatRawSnapshotText(data);
 	if (!shouldCompactSnapshot(rawText, data)) {
@@ -501,7 +510,7 @@ export async function buildSnapshotPresentation(data: Record<string, unknown>):
 	let fullOutputPath: string | undefined;
 	let spillErrorText: string | undefined;
 	try {
-		fullOutputPath = await writeSnapshotSpillFile(data);
+		fullOutputPath = await writeSnapshotSpillFile(data, persistentArtifactStore);
 	} catch (error) {
 		spillErrorText = error instanceof Error ? error.message : String(error);
 	}

package/extensions/agent-browser/lib/runtime.ts

@@ -10,6 +10,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 
 const STARTUP_SCOPED_FLAGS = ["--cdp", "--profile", "--session-name"] as const;
+const OPEN_COMMANDS = new Set(["goto", "navigate", "open"]);
+const OPENAI_HEADLESS_COMPAT_HOSTS = new Set(["chat.openai.com", "chatgpt.com"]);
 const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
 const AGENT_BROWSER_IDLE_TIMEOUT_ENV = "AGENT_BROWSER_IDLE_TIMEOUT_MS";
 const IMPLICIT_SESSION_IDLE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_IDLE_TIMEOUT_MS";
@@ -57,7 +59,21 @@ const GLOBAL_FLAGS_WITH_VALUES = new Set([
 	"--color-scheme",
 	"--device",
 	"--port",
+	"--args",
+	"--user-agent",
+	"--allowed-domains",
+	"--action-policy",
+	"--confirm-actions",
+	"--max-output",
+	"--model",
 ]);
+const DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM: Partial<Record<NodeJS.Platform, string>> = {
+	darwin: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+	linux: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+	win32: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+};
+const FALLBACK_HEADLESS_COMPAT_USER_AGENT =
+	"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
 const SHELL_OPERATOR_TOKENS = new Set(["&&", "||", "|", ";", ">", ">>", "<"]);
 const MAX_PROJECT_SLUG_LENGTH = 24;
 const SESSION_NAME_CWD_HASH_LENGTH = 8;
@@ -84,8 +100,20 @@ export interface InvalidValueFlagDetails {
 	receivedToken?: string;
 }
 
+export interface CompatibilityWorkaround {
+	id: "chatgpt-headless-user-agent";
+	reason: string;
+}
+
+export interface OpenResultTabCorrection {
+	selectedIndex: number;
+	targetTitle?: string;
+	targetUrl: string;
+}
+
 export interface ExecutionPlan {
 	commandInfo: CommandInfo;
+	compatibilityWorkaround?: CompatibilityWorkaround;
 	effectiveArgs: string[];
 	invalidValueFlag?: InvalidValueFlagDetails;
 	managedSessionName?: string;
@@ -467,6 +495,96 @@ function hasFlagToken(args: string[], flag: string): boolean {
 	return args.some((token) => token === flag || token.startsWith(`${flag}=`));
 }
 
+function getFlagValue(args: string[], flag: string): string | undefined {
+	for (const [index, token] of args.entries()) {
+		if (token === flag) {
+			return args[index + 1];
+		}
+		if (token.startsWith(`${flag}=`)) {
+			return token.slice(flag.length + 1);
+		}
+	}
+	return undefined;
+}
+
+function isBooleanFlagEnabled(args: string[], flag: string): boolean {
+	for (const [index, token] of args.entries()) {
+		if (token === flag) {
+			const nextToken = args[index + 1]?.trim().toLowerCase();
+			if (nextToken === "false") {
+				return false;
+			}
+			return true;
+		}
+		if (token.startsWith(`${flag}=`)) {
+			return token.slice(flag.length + 1).trim().toLowerCase() !== "false";
+		}
+	}
+	return false;
+}
+
+function normalizeComparableUrl(url: string): string | undefined {
+	const normalizedUrl = url.trim();
+	if (normalizedUrl.length === 0) {
+		return undefined;
+	}
+	try {
+		const parsedUrl = new URL(normalizedUrl);
+		parsedUrl.hash = "";
+		return parsedUrl.toString();
+	} catch {
+		return undefined;
+	}
+}
+
+function parseComparableNavigationUrl(url: string): URL | undefined {
+	try {
+		return new URL(url);
+	} catch {
+		try {
+			return new URL(`https://${url}`);
+		} catch {
+			return undefined;
+		}
+	}
+}
+
+function getDefaultHeadlessCompatUserAgent(platform: NodeJS.Platform = process.platform): string {
+	return DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM[platform] ?? FALLBACK_HEADLESS_COMPAT_USER_AGENT;
+}
+
+function getCompatibilityWorkaround(args: string[], commandInfo: CommandInfo): CompatibilityWorkaround | undefined {
+	if (!commandInfo.command || !OPEN_COMMANDS.has(commandInfo.command) || !commandInfo.subcommand) {
+		return undefined;
+	}
+	if (hasFlagToken(args, "--user-agent")) {
+		return undefined;
+	}
+	if (isBooleanFlagEnabled(args, "--headed")) {
+		return undefined;
+	}
+	if (hasFlagToken(args, "--cdp") || hasFlagToken(args, "--provider") || hasFlagToken(args, "-p") || hasFlagToken(args, "--auto-connect")) {
+		return undefined;
+	}
+	const engine = getFlagValue(args, "--engine");
+	if (engine && engine !== "chrome") {
+		return undefined;
+	}
+	const parsedTargetUrl = parseComparableNavigationUrl(commandInfo.subcommand);
+	if (!parsedTargetUrl || !["http:", "https:"].includes(parsedTargetUrl.protocol)) {
+		return undefined;
+	}
+	const hostname = parsedTargetUrl.hostname.toLowerCase();
+	if (!OPENAI_HEADLESS_COMPAT_HOSTS.has(hostname)) {
+		return undefined;
+	}
+	return {
+		id: "chatgpt-headless-user-agent",
+		reason:
+			"OpenAI web properties currently challenge the default headless Chrome user agent; inject a normal Chrome user agent to preserve the default headless workflow without requiring headed mode or auto-connect.",
+	};
+}
+
 export function extractExplicitSessionName(args: string[]): string | undefined {
 	for (const [index, token] of args.entries()) {
 		if (token === "--session") {
@@ -556,6 +674,7 @@ export function buildExecutionPlan(
 	const explicitSessionName = extractExplicitSessionName(args);
 	const shouldCreateFreshManagedSession =
 		!explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && commandInfo.command !== "close";
+	const compatibilityWorkaround = getCompatibilityWorkaround(args, commandInfo);
 	let managedSessionName: string | undefined;
 	let recoveryHint: SessionRecoveryHint | undefined;
 	let sessionName = explicitSessionName;
@@ -587,10 +706,14 @@ export function buildExecutionPlan(
 		sessionName = options.freshSessionName;
 	}
 
+	if (compatibilityWorkaround) {
+		effectiveArgs.push("--user-agent", getDefaultHeadlessCompatUserAgent());
+	}
 	effectiveArgs.push(...args);
 
 	return {
 		commandInfo,
+		compatibilityWorkaround,
 		effectiveArgs,
 		managedSessionName,
 		plainTextInspection,
@@ -602,6 +725,48 @@ export function buildExecutionPlan(
 	};
 }
 
+export function chooseOpenResultTabCorrection(options: {
+	activeTabIndex?: number;
+	tabs: Array<{ active?: boolean; index?: number; title?: string; url?: string }>;
+	targetTitle?: string;
+	targetUrl?: string;
+}): OpenResultTabCorrection | undefined {
+	const normalizedTargetUrl =
+		typeof options.targetUrl === "string" ? normalizeComparableUrl(options.targetUrl) : undefined;
+	if (!normalizedTargetUrl) {
+		return undefined;
+	}
+
+	const tabsWithIndices = options.tabs.map((tab, index) => ({
+		...tab,
+		index: typeof tab.index === "number" ? tab.index : index,
+	}));
+	const activeTab =
+		tabsWithIndices.find((tab) => tab.active === true) ??
+		(typeof options.activeTabIndex === "number" ? tabsWithIndices.find((tab) => tab.index === options.activeTabIndex) : undefined);
+	if (activeTab && normalizeComparableUrl(activeTab.url ?? "") === normalizedTargetUrl) {
+		return undefined;
+	}
+
+	const matchingTabs = tabsWithIndices.filter((tab) => normalizeComparableUrl(tab.url ?? "") === normalizedTargetUrl);
+	if (matchingTabs.length === 0) {
+		return undefined;
+	}
+	const trimmedTargetTitle = typeof options.targetTitle === "string" ? options.targetTitle.trim() : "";
+	const titledMatch =
+		trimmedTargetTitle.length === 0
+			? undefined
+			: matchingTabs.find((tab) => typeof tab.title === "string" && tab.title.trim() === trimmedTargetTitle);
+	const selectedTab = titledMatch ?? matchingTabs[0];
+	return selectedTab.index === undefined
+		? undefined
+		: {
+			selectedIndex: selectedTab.index,
+			targetTitle: trimmedTargetTitle.length > 0 ? trimmedTargetTitle : undefined,
+			targetUrl: normalizedTargetUrl,
+		};
+}
+
 export function parseCommandInfo(args: string[]): CommandInfo {
 	const commands: string[] = [];
 

package/extensions/agent-browser/lib/temp.ts

@@ -1,14 +1,14 @@
 /**
- * Purpose: Create private temporary files for the pi-agent-browser extension without leaking artifacts broadly on disk.
- * Responsibilities: Maintain a process-private temp root, stamp explicit ownership markers, enforce an aggregate temp-artifact disk budget, create securely permissioned temp files, prune explicitly owned stale temp roots from prior runs, and best-effort clean all owned roots on process exit.
- * Scope: Temporary artifact lifecycle only; callers decide what data to write and when to delete long-lived references.
+ * Purpose: Create private temporary and persisted spill files for the pi-agent-browser extension without leaking artifacts broadly on disk.
+ * Responsibilities: Maintain a process-private temp root, stamp explicit ownership markers, enforce an aggregate temp-artifact disk budget, create securely permissioned temp files, create session-scoped persisted spill files for resumable sessions, prune explicitly owned stale temp roots from prior runs, and best-effort clean all owned roots on process exit.
+ * Scope: Artifact lifecycle helpers only; callers decide what data to write and when to delete or retain long-lived references.
  * Usage: Imported by result/process helpers when they need secure spill files instead of world-readable shared tmp paths.
- * Invariants/Assumptions: Temp artifacts live under the OS temp directory, each active run uses a dedicated 0700 directory, files are created with exclusive 0600 permissions, and stale pruning only touches roots with an explicit pi-agent-browser ownership marker.
+ * Invariants/Assumptions: Temp artifacts live under the OS temp directory, each active run uses a dedicated 0700 directory, files are created with exclusive 0600 permissions, session-scoped persisted artifacts stay under the pi session directory, and stale pruning only touches roots with an explicit pi-agent-browser ownership marker.
  */
 
 import { randomBytes } from "node:crypto";
 import { rmSync } from "node:fs";
-import { chmod, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -19,6 +19,15 @@ const TEMP_ROOT_MARKER_VERSION = 1;
 const STALE_TEMP_ROOT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
 const TEMP_ROOT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_TEMP_ROOT_MAX_BYTES";
 const DEFAULT_TEMP_ROOT_MAX_BYTES = 32 * 1_024 * 1_024;
+const SESSION_ARTIFACT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES";
+const DEFAULT_SESSION_ARTIFACT_MAX_BYTES = 32 * 1_024 * 1_024;
+const SESSION_ARTIFACTS_ROOT_DIR_NAME = ".pi-agent-browser-artifacts";
+
+export interface PersistentSessionArtifactStore {
+	protectedPaths?: readonly string[];
+	sessionDir: string;
+	sessionId: string;
+}
 
 interface TempRootOwnershipRecord {
 	createdAtMs: number;
@@ -69,18 +78,23 @@ function enqueueTempMutation<T>(task: () => Promise<T>): Promise<T> {
 	return nextTask;
 }
 
-async function getTempRootArtifactBytes(tempRoot: string): Promise<number> {
-	const entries = await readdir(tempRoot, { withFileTypes: true }).catch(() => []);
-	let totalBytes = 0;
+async function listArtifactFiles(directory: string, excludedNames: ReadonlySet<string> = new Set()): Promise<Array<{ mtimeMs: number; path: string; size: number }>> {
+	const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+	const files: Array<{ mtimeMs: number; path: string; size: number }> = [];
 	for (const entry of entries) {
-		if (!entry.isFile() || entry.name === TEMP_ROOT_MARKER_FILE_NAME) continue;
-		const path = join(tempRoot, entry.name);
+		if (!entry.isFile() || excludedNames.has(entry.name)) continue;
+		const path = join(directory, entry.name);
 		const stats = await stat(path).catch(() => undefined);
 		if (stats?.isFile()) {
-			totalBytes += stats.size;
+			files.push({ mtimeMs: stats.mtimeMs, path, size: stats.size });
 		}
 	}
-	return totalBytes;
+	return files;
+}
+
+async function getTempRootArtifactBytes(tempRoot: string): Promise<number> {
+	const files = await listArtifactFiles(tempRoot, new Set([TEMP_ROOT_MARKER_FILE_NAME]));
+	return files.reduce((totalBytes, file) => totalBytes + file.size, 0);
 }
 
 async function readTempRootOwnershipMarker(tempRoot: string): Promise<TempRootOwnershipRecord | undefined> {
@@ -153,6 +167,10 @@ export function getSecureTempRootMaxBytes(env: NodeJS.ProcessEnv = process.env):
 	return parsePositiveInteger(env[TEMP_ROOT_MAX_BYTES_ENV]) ?? DEFAULT_TEMP_ROOT_MAX_BYTES;
 }
 
+export function getPersistentSessionArtifactMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+	return parsePositiveInteger(env[SESSION_ARTIFACT_MAX_BYTES_ENV]) ?? DEFAULT_SESSION_ARTIFACT_MAX_BYTES;
+}
+
 async function assertSecureTempRootBudget(tempRoot: string, additionalBytes: number): Promise<void> {
 	if (additionalBytes <= 0) return;
 	const currentBytes = await getTempRootArtifactBytes(tempRoot);
@@ -173,6 +191,42 @@ export async function cleanupSecureTempArtifacts(): Promise<void> {
 	});
 }
 
+async function ensurePersistentSessionArtifactDir(store: PersistentSessionArtifactStore): Promise<string> {
+	const rootDir = join(store.sessionDir, SESSION_ARTIFACTS_ROOT_DIR_NAME);
+	const sessionDir = join(rootDir, store.sessionId);
+	await mkdir(rootDir, { recursive: true, mode: 0o700 });
+	await chmod(rootDir, 0o700).catch(() => undefined);
+	await mkdir(sessionDir, { recursive: true, mode: 0o700 });
+	await chmod(sessionDir, 0o700).catch(() => undefined);
+	return sessionDir;
+}
+
+async function prunePersistentSessionArtifactsToBudget(
+	sessionArtifactDir: string,
+	additionalBytes: number,
+	protectedPaths: ReadonlySet<string>,
+): Promise<void> {
+	if (additionalBytes <= 0) return;
+	const maxBytes = getPersistentSessionArtifactMaxBytes();
+	let files = await listArtifactFiles(sessionArtifactDir);
+	let totalBytes = files.reduce((total, file) => total + file.size, 0);
+	if (totalBytes + additionalBytes <= maxBytes) {
+		return;
+	}
+	files = files.sort((left, right) => left.mtimeMs - right.mtimeMs || left.path.localeCompare(right.path));
+	for (const file of files) {
+		if (protectedPaths.has(file.path)) {
+			continue;
+		}
+		await rm(file.path, { force: true }).catch(() => undefined);
+		totalBytes -= file.size;
+		if (totalBytes + additionalBytes <= maxBytes) {
+			return;
+		}
+	}
+	throw new Error(`pi-agent-browser persisted spill budget exceeded (${totalBytes + additionalBytes} bytes > ${maxBytes} byte limit).`);
+}
+
 async function getSessionTempRoot(): Promise<string> {
 	if (!sessionTempRootPromise) {
 		sessionTempRootPromise = (async () => {
@@ -228,6 +282,34 @@ export async function writeSecureTempFile(options: {
 	return path;
 }
 
+export async function writePersistentSessionArtifactFile(options: {
+	content: string | Uint8Array;
+	prefix: string;
+	store: PersistentSessionArtifactStore;
+	suffix: string;
+}): Promise<string> {
+	const { content, prefix, store, suffix } = options;
+	return await enqueueTempMutation(async () => {
+		const artifactDir = await ensurePersistentSessionArtifactDir(store);
+		await prunePersistentSessionArtifactsToBudget(
+			artifactDir,
+			getTempArtifactByteLength(content),
+			new Set((store.protectedPaths ?? []).filter((path) => dirname(path) === artifactDir)),
+		);
+		const path = join(artifactDir, `${prefix}-${randomBytes(8).toString("hex")}${suffix}`);
+		const fileHandle = await open(path, "wx", 0o600);
+		try {
+			await fileHandle.writeFile(content);
+		} catch (error) {
+			await rm(path, { force: true }).catch(() => undefined);
+			throw error;
+		} finally {
+			await fileHandle.close().catch(() => undefined);
+		}
+		return path;
+	});
+}
+
 export async function getSecureTempDebugState(): Promise<{ currentTempRoot?: string; ownedTempRoots: string[] }> {
 	return {
 		currentTempRoot: await sessionTempRootPromise?.catch(() => undefined),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",