pi-agent-browser-native 0.2.11 → 0.2.13

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

@@ -1,6 +1,6 @@
 /**
  * Purpose: Share stable result-rendering types and small data-shaping helpers across the focused result modules.
- * Responsibilities: Define upstream envelope/presentation types, provide safe record/string utilities, and expose lightweight text helpers used by envelope parsing, snapshot compaction, and presentation rendering.
+ * Responsibilities: Define upstream envelope/presentation types, provide safe string utilities, and expose lightweight text helpers used by envelope parsing, snapshot compaction, and presentation rendering.
  * Scope: Shared result helpers only; higher-level parsing, snapshot compaction, and image attachment orchestration live in neighboring modules.
  * Usage: Imported by the focused result modules that back the public `lib/results.ts` facade.
  * Invariants/Assumptions: Helpers stay generic, side-effect free, and small enough to reuse without reintroducing a new god module.
@@ -9,7 +9,7 @@
 export interface AgentBrowserEnvelope {
 	data?: unknown;
 	error?: unknown;
-	success?: boolean;
+	success: boolean;
 }
 
 export interface AgentBrowserBatchResult {
@@ -19,7 +19,164 @@ export interface AgentBrowserBatchResult {
 	success?: boolean;
 }
 
+export type FileArtifactKind = "download" | "file" | "har" | "image" | "pdf" | "profile" | "trace" | "video";
+
+export interface FileArtifactMetadata {
+	absolutePath: string;
+	command?: string;
+	exists?: boolean;
+	extension?: string;
+	kind: FileArtifactKind;
+	mediaType?: string;
+	path: string;
+	sizeBytes?: number;
+	subcommand?: string;
+}
+
+export interface SavedFilePresentationDetails {
+	command: "download" | "pdf" | "wait";
+	kind: "download" | "pdf";
+	metadata?: Record<string, unknown>;
+	path: string;
+	subcommand?: string;
+}
+
+export type ArtifactRetentionState = "evicted" | "ephemeral" | "live" | "missing";
+
+export type ArtifactStorageScope = "explicit-path" | "persistent-session" | "process-temp";
+
+export interface SessionArtifactManifestEntry {
+	absolutePath?: string;
+	command?: string;
+	createdAtMs: number;
+	evictedAtMs?: number;
+	exists?: boolean;
+	extension?: string;
+	kind: FileArtifactKind | "spill";
+	mediaType?: string;
+	path: string;
+	retentionState: ArtifactRetentionState;
+	sizeBytes?: number;
+	storageScope: ArtifactStorageScope;
+	subcommand?: string;
+}
+
+export interface SessionArtifactManifest {
+	entries: SessionArtifactManifestEntry[];
+	evictedCount: number;
+	liveCount: number;
+	maxEntries: number;
+	updatedAtMs: number;
+	version: 1;
+}
+
+export const SESSION_ARTIFACT_MANIFEST_VERSION = 1;
+export const SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES";
+export const DEFAULT_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES = 100;
+
+function parsePositiveSafeInteger(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) return undefined;
+	return parsed;
+}
+
+export function getSessionArtifactManifestMaxEntries(env: NodeJS.ProcessEnv = process.env): number {
+	return parsePositiveSafeInteger(env[SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES_ENV]) ?? DEFAULT_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isManifestEntry(value: unknown): value is SessionArtifactManifestEntry {
+	if (!isRecord(value)) return false;
+	if (typeof value.path !== "string" || value.path.trim().length === 0) return false;
+	if (typeof value.createdAtMs !== "number" || !Number.isFinite(value.createdAtMs)) return false;
+	if (!["evicted", "ephemeral", "live", "missing"].includes(String(value.retentionState))) return false;
+	if (!["explicit-path", "persistent-session", "process-temp"].includes(String(value.storageScope))) return false;
+	if (typeof value.kind !== "string" || value.kind.trim().length === 0) return false;
+	return true;
+}
+
+export function isSessionArtifactManifest(value: unknown): value is SessionArtifactManifest {
+	if (!isRecord(value)) return false;
+	if (value.version !== SESSION_ARTIFACT_MANIFEST_VERSION) return false;
+	if (!Array.isArray(value.entries) || !value.entries.every(isManifestEntry)) return false;
+	if (typeof value.updatedAtMs !== "number" || !Number.isFinite(value.updatedAtMs)) return false;
+	if (typeof value.maxEntries !== "number" || !Number.isSafeInteger(value.maxEntries) || value.maxEntries <= 0) return false;
+	if (typeof value.liveCount !== "number" || !Number.isSafeInteger(value.liveCount) || value.liveCount < 0) return false;
+	if (typeof value.evictedCount !== "number" || !Number.isSafeInteger(value.evictedCount) || value.evictedCount < 0) return false;
+	return true;
+}
+
+export function buildEvictedSessionArtifactEntries(
+	evictedArtifacts: Array<{ mtimeMs: number; path: string; sizeBytes: number }>,
+	nowMs: number,
+): SessionArtifactManifestEntry[] {
+	return evictedArtifacts.map((artifact) => ({
+		createdAtMs: artifact.mtimeMs,
+		evictedAtMs: nowMs,
+		kind: "spill",
+		path: artifact.path,
+		retentionState: "evicted",
+		sizeBytes: artifact.sizeBytes,
+		storageScope: "persistent-session",
+	}));
+}
+
+export function formatSessionArtifactRetentionSummary(manifest: SessionArtifactManifest): string {
+	const ephemeralCount = manifest.entries.filter((entry) => entry.retentionState === "ephemeral").length;
+	const missingCount = manifest.entries.filter((entry) => entry.retentionState === "missing").length;
+	const parts = [`${manifest.liveCount} live`, `${manifest.evictedCount} evicted`];
+	if (ephemeralCount > 0) parts.push(`${ephemeralCount} ephemeral`);
+	if (missingCount > 0) parts.push(`${missingCount} missing`);
+	return `Session artifacts: ${parts.join(", ")} (${manifest.entries.length}/${manifest.maxEntries} recent).`;
+}
+
+export function mergeSessionArtifactManifest(options: {
+	base?: SessionArtifactManifest;
+	entries?: SessionArtifactManifestEntry[];
+	nowMs?: number;
+}): SessionArtifactManifest | undefined {
+	const nowMs = options.nowMs ?? Date.now();
+	const maxEntries = getSessionArtifactManifestMaxEntries();
+	const getEntryKey = (entry: SessionArtifactManifestEntry) =>
+		entry.storageScope === "explicit-path" && entry.absolutePath ? `${entry.storageScope}:${entry.absolutePath}` : `${entry.storageScope}:${entry.path}`;
+	const byPath = new Map<string, SessionArtifactManifestEntry>();
+	for (const entry of options.base?.entries ?? []) {
+		byPath.set(getEntryKey(entry), entry);
+	}
+	for (const entry of options.entries ?? []) {
+		const key = getEntryKey(entry);
+		const existing = byPath.get(key);
+		byPath.set(key, {
+			...existing,
+			...entry,
+			createdAtMs: existing?.createdAtMs ?? entry.createdAtMs,
+			evictedAtMs: entry.retentionState === "evicted" ? (entry.evictedAtMs ?? nowMs) : entry.evictedAtMs,
+		});
+	}
+	if (byPath.size === 0) return undefined;
+	const entries = [...byPath.values()]
+		.sort((left, right) => {
+			const leftTime = left.evictedAtMs ?? left.createdAtMs;
+			const rightTime = right.evictedAtMs ?? right.createdAtMs;
+			return rightTime - leftTime || left.path.localeCompare(right.path);
+		})
+		.slice(0, maxEntries);
+	return {
+		entries,
+		evictedCount: entries.filter((entry) => entry.retentionState === "evicted").length,
+		liveCount: entries.filter((entry) => entry.retentionState === "live").length,
+		maxEntries,
+		updatedAtMs: nowMs,
+		version: SESSION_ARTIFACT_MANIFEST_VERSION,
+	};
+}
+
 export interface BatchStepPresentationDetails {
+	artifacts?: FileArtifactMetadata[];
 	command?: string[];
 	commandText: string;
 	data?: unknown;
@@ -28,6 +185,8 @@ export interface BatchStepPresentationDetails {
 	imagePath?: string;
 	imagePaths?: string[];
 	index: number;
+	savedFile?: SavedFilePresentationDetails;
+	savedFilePath?: string;
 	success: boolean;
 	summary: string;
 	text: string;
@@ -41,6 +200,9 @@ export interface BatchFailurePresentationDetails {
 }
 
 export interface ToolPresentation {
+	artifactManifest?: SessionArtifactManifest;
+	artifactRetentionSummary?: string;
+	artifacts?: FileArtifactMetadata[];
 	batchFailure?: BatchFailurePresentationDetails;
 	batchSteps?: BatchStepPresentationDetails[];
 	content: Array<{ text: string; type: "text" } | { data: string; mimeType: string; type: "image" }>;
@@ -49,13 +211,11 @@ export interface ToolPresentation {
 	fullOutputPaths?: string[];
 	imagePath?: string;
 	imagePaths?: string[];
+	savedFile?: SavedFilePresentationDetails;
+	savedFilePath?: string;
 	summary: string;
 }
 
-export function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 export function stringifyUnknown(value: unknown): string {
 	if (typeof value === "string") return value;
 	if (typeof value === "number" || typeof value === "boolean") return String(value);
@@ -67,15 +227,6 @@ export function stringifyUnknown(value: unknown): string {
 	}
 }
 
-export function parsePositiveInteger(rawValue: string | undefined): number | undefined {
-	if (typeof rawValue !== "string") return undefined;
-	const normalizedValue = rawValue.trim();
-	if (!/^\d+$/.test(normalizedValue)) return undefined;
-	const parsedValue = Number(normalizedValue);
-	if (!Number.isSafeInteger(parsedValue) || parsedValue <= 0) return undefined;
-	return parsedValue;
-}
-
 export function countLines(text: string): number {
 	return text.length === 0 ? 0 : text.split("\n").length;
 }

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

@@ -6,8 +6,25 @@
  * 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 { type PersistentSessionArtifactStore, writePersistentSessionArtifactFile, writeSecureTempFile } from "../temp.js";
-import { type ToolPresentation, compareRefIds, countLines, isRecord, normalizeWhitespace, truncateText } from "./shared.js";
+import { isRecord } from "../parsing.js";
+import {
+	type PersistentSessionArtifactEviction,
+	type PersistentSessionArtifactStore,
+	writePersistentSessionArtifactFile,
+	writeSecureTempFile,
+} from "../temp.js";
+import {
+	type SessionArtifactManifest,
+	type SessionArtifactManifestEntry,
+	type ToolPresentation,
+	buildEvictedSessionArtifactEntries,
+	compareRefIds,
+	countLines,
+	formatSessionArtifactRetentionSummary,
+	mergeSessionArtifactManifest,
+	normalizeWhitespace,
+	truncateText,
+} from "./shared.js";
 
 const SNAPSHOT_INLINE_MAX_CHARS = 6_000;
 const SNAPSHOT_INLINE_MAX_LINES = 80;
@@ -463,18 +480,49 @@ function canUseStructuredSnapshotPreview(snapshotLines: SnapshotLine[], refEntri
 	);
 }
 
+interface SnapshotSpillWriteResult {
+	evictedArtifacts: PersistentSessionArtifactEviction[];
+	path: string;
+	storageScope: "persistent-session" | "process-temp";
+}
+
 async function writeSnapshotSpillFile(
 	data: Record<string, unknown>,
 	persistentArtifactStore: PersistentSessionArtifactStore | undefined,
-): Promise<string> {
+): Promise<SnapshotSpillWriteResult> {
 	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);
+	if (persistentArtifactStore) {
+		const result = await writePersistentSessionArtifactFile({ ...options, store: persistentArtifactStore });
+		return { ...result, storageScope: "persistent-session" };
+	}
+	return { evictedArtifacts: [], path: await writeSecureTempFile(options), storageScope: "process-temp" };
+}
+
+function applySnapshotArtifactManifest(options: {
+	baseManifest?: SessionArtifactManifest;
+	command?: string;
+	fullOutputPath?: string;
+	spill?: SnapshotSpillWriteResult;
+}): { artifactManifest?: SessionArtifactManifest; artifactRetentionSummary?: string } {
+	if (!options.fullOutputPath || !options.spill) return {};
+	const nowMs = Date.now();
+	const entries: SessionArtifactManifestEntry[] = [
+		{
+			command: options.command,
+			createdAtMs: nowMs,
+			kind: "spill",
+			path: options.fullOutputPath,
+			retentionState: options.spill.storageScope === "persistent-session" ? "live" : "ephemeral",
+			storageScope: options.spill.storageScope,
+		},
+		...buildEvictedSessionArtifactEntries(options.spill.evictedArtifacts, nowMs),
+	];
+	const artifactManifest = mergeSessionArtifactManifest({ base: options.baseManifest, entries, nowMs });
+	return artifactManifest ? { artifactManifest, artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest) } : {};
 }
 
 export function formatSnapshotSummary(data: Record<string, unknown>): string {
@@ -496,6 +544,7 @@ export function formatRawSnapshotText(data: Record<string, unknown>): string {
 export async function buildSnapshotPresentation(
 	data: Record<string, unknown>,
 	persistentArtifactStore: PersistentSessionArtifactStore | undefined = undefined,
+	artifactManifest: SessionArtifactManifest | undefined = undefined,
 ): Promise<ToolPresentation> {
 	const summary = formatSnapshotSummary(data);
 	const rawText = formatRawSnapshotText(data);
@@ -508,9 +557,11 @@ export async function buildSnapshotPresentation(
 	}
 
 	let fullOutputPath: string | undefined;
+	let spill: SnapshotSpillWriteResult | undefined;
 	let spillErrorText: string | undefined;
 	try {
-		fullOutputPath = await writeSnapshotSpillFile(data, persistentArtifactStore);
+		spill = await writeSnapshotSpillFile(data, persistentArtifactStore);
+		fullOutputPath = spill.path;
 	} catch (error) {
 		spillErrorText = error instanceof Error ? error.message : String(error);
 	}
@@ -618,7 +669,18 @@ export async function buildSnapshotPresentation(
 			: `Full raw snapshot unavailable: ${spillErrorText ?? "temp spill file could not be created."}`,
 	);
 
+	const manifestFields = applySnapshotArtifactManifest({
+		baseManifest: artifactManifest,
+		command: "snapshot",
+		fullOutputPath,
+		spill,
+	});
+	if (manifestFields.artifactRetentionSummary) {
+		lines.push("", manifestFields.artifactRetentionSummary);
+	}
+
 	return {
+		...manifestFields,
 		content: [{ type: "text", text: lines.join("\n") }],
 		data: {
 			compacted: true,

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

@@ -8,4 +8,10 @@
 
 export { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "./results/envelope.js";
 export { buildToolPresentation } from "./results/presentation.js";
-export type { AgentBrowserBatchResult, AgentBrowserEnvelope, ToolPresentation } from "./results/shared.js";
+export type {
+	AgentBrowserBatchResult,
+	AgentBrowserEnvelope,
+	FileArtifactKind,
+	FileArtifactMetadata,
+	ToolPresentation,
+} from "./results/shared.js";

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

@@ -3,13 +3,63 @@
  * Responsibilities: Validate raw tool arguments, derive extension-managed session names from the pi session identity, restore managed-session state from persisted tool details, redact sensitive invocation text, classify browser-oriented prompts, and build the effective CLI argument list passed to the upstream agent-browser binary.
  * Scope: Pure runtime-planning helpers only; no subprocess execution or filesystem access lives here.
  * Usage: Imported by the extension entrypoint and unit tests before spawning the upstream CLI.
- * Invariants/Assumptions: The wrapper stays thin, preserves upstream command vocabulary, keeps plain-text inspection stateless, and only injects `--json` plus an extension-managed `--session` when appropriate.
+ * Invariants/Assumptions: The wrapper stays thin, preserves upstream command vocabulary, keeps plain-text inspection stateless,
+ * and only injects wrapper-owned flags: `--json`, an extension-managed `--session` when appropriate, and the narrow
+ * OpenAI/ChatGPT headless compatibility `--user-agent` when that workaround applies.
  */
 
 import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 
-const STARTUP_SCOPED_FLAGS = ["--cdp", "--profile", "--session-name"] as const;
+import { isRecord } from "./parsing.js";
+
+/**
+ * Launch-scoped flags that select the upstream browser session/auth mechanism at launch time.
+ *
+ * These flags must not be silently appended after an already-active extension-managed session
+ * because upstream ignores or conflicts with them once a session is reused. Every flag here
+ * participates in implicit-session validation blocking and recovery-hint generation.
+ *
+ * Intentionally excluded from the tab-correction subset:
+ * - `--auto-connect` attaches to a running browser but is a general-purpose debug/attach mode,
+ *   not a state-restore mechanism that typically leaves restored tabs stealing focus.
+ * - `--cdp` connects to an arbitrary endpoint; similar reasoning to `--auto-connect`.
+ *
+ * Other flags like `--headed`, `--engine`, `--executable-path`, `--user-agent`, and
+ * `--download-path` are first-launch-sensitive but not alternate session/auth attach
+ * mechanisms, so they are intentionally excluded from the full launch-scoped set.
+ */
+const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
+	{
+		flag: "--auto-connect",
+		reason: "attaches to an already-running browser at launch time instead of reusing an existing named session",
+	},
+	{
+		flag: "--cdp",
+		reason: "selects the browser/CDP endpoint used when an upstream session is launched",
+	},
+	{
+		flag: "--profile",
+		reason: "selects Chrome profile state for the upstream launch",
+	},
+	{
+		flag: "--session-name",
+		reason: "selects upstream saved auth/session state for the launch",
+	},
+	{
+		flag: "--state",
+		reason: "loads persisted upstream browser/auth state at launch time",
+	},
+] as const;
+
+const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag).join(", ");
+
+/**
+ * The subset of launch-scoped flags that can restore browser/auth state with pre-existing tabs
+ * and are plausible wrong-active-tab sources after a fresh launch. These trigger post-open
+ * tab-correction (the `tab list` + re-select cycle).
+ */
+const LAUNCH_SCOPED_TAB_CORRECTION_FLAGS = new Set(["--profile", "--session-name", "--state"] as const);
 const OPEN_COMMANDS = new Set(["goto", "navigate", "open"]);
 const OPENAI_HEADLESS_COMPAT_HOSTS = new Set(["chat.com", "chat.openai.com", "chatgpt.com"]);
 const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
@@ -140,10 +190,6 @@ export interface PromptPolicy {
 	allowLegacyAgentBrowserBash: boolean;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 function isStringArray(value: unknown): value is string[] {
 	return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
@@ -164,23 +210,26 @@ function redactUrlToken(token: string): string {
 		return token;
 	}
 
+	let mutated = false;
 	if (parsed.username.length > 0) {
 		parsed.username = "[REDACTED]";
+		mutated = true;
 	}
 	if (parsed.password.length > 0) {
 		parsed.password = "[REDACTED]";
+		mutated = true;
 	}
 
 	for (const [name] of parsed.searchParams) {
 		if (shouldRedactQueryParam(name)) {
 			parsed.searchParams.set(name, "[REDACTED]");
+			mutated = true;
 		}
 	}
 
 	const hashText = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash;
 	if (hashText.includes("=")) {
 		const hashParams = new URLSearchParams(hashText);
-		let mutated = false;
 		for (const [name] of hashParams) {
 			if (shouldRedactQueryParam(name)) {
 				hashParams.set(name, "[REDACTED]");
@@ -199,10 +248,95 @@ function redactLooseUrlMatches(text: string): string {
 	return text.replace(/\b(?:https?|wss?):\/\/[^\s"'`<>\])]+/g, (match) => redactUrlToken(match));
 }
 
+function findBalancedJsonEnd(text: string, startIndex: number): number | undefined {
+	const opener = text[startIndex];
+	const closer = opener === "{" ? "}" : opener === "[" ? "]" : undefined;
+	if (!closer) return undefined;
+	const stack = [closer];
+	let inString = false;
+	let escaped = false;
+	for (let index = startIndex + 1; index < text.length; index += 1) {
+		const char = text[index];
+		if (inString) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === '"') {
+				inString = false;
+			}
+			continue;
+		}
+		if (char === '"') {
+			inString = true;
+			continue;
+		}
+		if (char === "{") {
+			stack.push("}");
+			continue;
+		}
+		if (char === "[") {
+			stack.push("]");
+			continue;
+		}
+		if (char === "}" || char === "]") {
+			if (stack.pop() !== char) return undefined;
+			if (stack.length === 0) return index;
+		}
+	}
+	return undefined;
+}
+
+function redactEmbeddedStructuredText(text: string): string {
+	let output = "";
+	let cursor = 0;
+	while (cursor < text.length) {
+		const char = text[cursor];
+		if (char !== "{" && char !== "[") {
+			output += char;
+			cursor += 1;
+			continue;
+		}
+		const endIndex = findBalancedJsonEnd(text, cursor);
+		if (endIndex === undefined) {
+			output += char;
+			cursor += 1;
+			continue;
+		}
+		const candidate = text.slice(cursor, endIndex + 1);
+		try {
+			const parsed = JSON.parse(candidate) as unknown;
+			const redacted = typeof parsed === "string" ? redactSensitiveText(parsed) : JSON.stringify(redactSensitiveValue(parsed));
+			const original = typeof parsed === "string" ? parsed : JSON.stringify(parsed);
+			output += redacted === original ? candidate : redacted;
+		} catch {
+			output += candidate;
+		}
+		cursor = endIndex + 1;
+	}
+	return output;
+}
+
+function redactStandaloneBasicCredential(text: string): string {
+	return text.replace(/\b(Basic)\s+([A-Za-z0-9+/=]{12,})/gi, (match, label: string, credential: string) => {
+		if (!/[0-9+/=]/.test(credential)) return match;
+		return `${label} [REDACTED]`;
+	});
+}
+
 export function redactSensitiveText(text: string): string {
-	return redactLooseUrlMatches(text)
-		.replace(/\b(Bearer)\s+[^\s",]+/gi, "$1 [REDACTED]")
-		.replace(/\b(Basic)\s+[^\s",]+/gi, "$1 [REDACTED]");
+	return redactEmbeddedStructuredText(
+		redactStandaloneBasicCredential(
+			redactLooseUrlMatches(text)
+				.replace(/\b(Bearer)\s+[^\s",]+/gi, "$1 [REDACTED]")
+				.replace(/\b(Authorization\s*:\s*Basic)\s+[^\s",]+/gi, "$1 [REDACTED]")
+				.replace(/\b(Cookie|Set-Cookie)\s*:\s*[^\n\r"]+/gi, "$1: [REDACTED]"),
+		),
+	);
 }
 
 export function redactSensitiveValue(value: unknown): unknown {
@@ -327,6 +461,27 @@ function isRestorableManagedSessionName(sessionName: string, fallbackSessionName
 	return sessionName === fallbackSessionName || sessionName.startsWith(`${fallbackSessionName}-fresh-`);
 }
 
+function getManagedSessionRestoreRank(options: {
+	fallbackSessionName: string;
+	freshSessionRanks: Map<string, number>;
+	sessionName: string;
+}): number | undefined {
+	const { fallbackSessionName, freshSessionRanks, sessionName } = options;
+	if (sessionName === fallbackSessionName) {
+		return 0;
+	}
+	if (!sessionName.startsWith(`${fallbackSessionName}-fresh-`)) {
+		return undefined;
+	}
+	const existingRank = freshSessionRanks.get(sessionName);
+	if (existingRank !== undefined) {
+		return existingRank;
+	}
+	const nextRank = freshSessionRanks.size + 1;
+	freshSessionRanks.set(sessionName, nextRank);
+	return nextRank;
+}
+
 export function restoreManagedSessionStateFromBranch(
 	branch: unknown[],
 	fallbackSessionName: string,
@@ -335,7 +490,9 @@ export function restoreManagedSessionStateFromBranch(
 		active: false,
 		sessionName: fallbackSessionName,
 	};
+	let activeRestoreRank = 0;
 	let freshSessionOrdinal = 0;
+	const freshSessionRanks = new Map<string, number>();
 
 	for (const entry of branch) {
 		if (!isRecord(entry) || entry.type !== "message") {
@@ -369,10 +526,31 @@ export function restoreManagedSessionStateFromBranch(
 			continue;
 		}
 
+		const restoreRank = getManagedSessionRestoreRank({
+			fallbackSessionName,
+			freshSessionRanks,
+			sessionName: managedSessionName,
+		});
+		if (restoreRank === undefined) {
+			continue;
+		}
+
 		const messageIsError = typeof message.isError === "boolean" ? message.isError : undefined;
 		const exitCode = typeof details.exitCode === "number" ? details.exitCode : undefined;
 		const succeeded = messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
 		const command = typeof details.command === "string" ? details.command : parseCommandInfo(args).command;
+		if (succeeded && sessionMode === "fresh") {
+			freshSessionOrdinal += 1;
+		}
+		const staleCompletion = succeeded && command !== "close" && restoreRank < activeRestoreRank;
+		if (staleCompletion) {
+			continue;
+		}
+		const staleClose = command === "close" && restoredState.active && managedSessionName !== restoredState.sessionName;
+		if (staleClose) {
+			continue;
+		}
+
 		restoredState = resolveManagedSessionState({
 			command,
 			managedSessionName,
@@ -380,8 +558,8 @@ export function restoreManagedSessionStateFromBranch(
 			priorSessionName: restoredState.sessionName,
 			succeeded,
 		});
-		if (succeeded && sessionMode === "fresh") {
-			freshSessionOrdinal += 1;
+		if (succeeded && command !== "close" && restoredState.active) {
+			activeRestoreRank = restoreRank;
 		}
 	}
 
@@ -619,7 +797,18 @@ export function extractExplicitSessionName(args: string[]): string | undefined {
 }
 
 export function getStartupScopedFlags(args: string[]): string[] {
-	return STARTUP_SCOPED_FLAGS.filter((flag) => hasFlagToken(args, flag));
+	return LAUNCH_SCOPED_FLAG_DEFINITIONS
+		.map((definition) => definition.flag)
+		.filter((flag) => hasFlagToken(args, flag));
+}
+
+export function hasLaunchScopedTabCorrectionFlag(args: string[]): boolean {
+	return args.some((token) => {
+		for (const flag of LAUNCH_SCOPED_TAB_CORRECTION_FLAGS) {
+			if (token === flag || token.startsWith(`${flag}=`)) return true;
+		}
+		return false;
+	});
 }
 
 export function buildPromptPolicy(prompt: string): PromptPolicy {
@@ -708,11 +897,11 @@ export function buildExecutionPlan(
 				exampleArgs: args,
 				exampleParams: { args, sessionMode: "fresh" },
 				reason:
-					"Startup-scoped flags like --profile, --session-name, and --cdp need a fresh upstream launch once the extension-managed session is already active.",
+					`Launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}) need a fresh upstream launch once the extension-managed session is already active.`,
 				recommendedSessionMode: "fresh",
 			};
 			validationError = [
-				`The current extension-managed agent-browser session is already running, so startup-scoped flags ${startupScopedFlags.join(", ")} would be ignored by upstream agent-browser.`,
+				`The current extension-managed agent-browser session is already running, so launch-scoped flags ${startupScopedFlags.join(", ")} would be ignored by upstream agent-browser.`,
 				"Retry this call with `sessionMode: \"fresh\"` to force a fresh upstream launch, or pass an explicit `--session ...` if you want to name the new session yourself.",
 			].join(" ");
 		} else {