pi-agent-browser-native 0.2.24 → 0.2.26

package/extensions/agent-browser/index.ts

@@ -6,7 +6,7 @@
  * 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 { copyFile, mkdir, readFile, rm, stat } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, rm, stat } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -27,11 +27,14 @@ import {
 } from "./lib/playbook.js";
 import { SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS, runAgentBrowserProcess } from "./lib/process.js";
 import {
+	buildAgentBrowserNextActions,
+	buildAgentBrowserResultCategoryDetails,
 	buildToolPresentation,
 	getAgentBrowserErrorText,
 	parseAgentBrowserEnvelope,
 	type AgentBrowserBatchResult,
 	type AgentBrowserEnvelope,
+	type AgentBrowserNextAction,
 } from "./lib/results.js";
 import {
 	buildExecutionPlan,
@@ -54,6 +57,7 @@ import {
 	resolveManagedSessionState,
 	shouldAppendBrowserSystemPrompt,
 	validateToolArgs,
+	type CommandInfo,
 	type CompatibilityWorkaround,
 	type OpenResultTabCorrection,
 } from "./lib/runtime.js";
@@ -70,22 +74,211 @@ import {
 	formatSessionArtifactRetentionSummary,
 	isSessionArtifactManifest,
 	mergeSessionArtifactManifest,
+	summarizeNetworkFailures,
 } from "./lib/results/shared.js";
 
 const DEFAULT_SESSION_MODE = "auto" as const;
 const DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV = "PI_AGENT_BROWSER_ALLOW_DIRECT_BASH";
 const PACKAGE_NAME = "pi-agent-browser-native";
 
+const AGENT_BROWSER_SEMANTIC_ACTIONS = ["check", "click", "fill", "select", "uncheck"] as const;
+const AGENT_BROWSER_SEMANTIC_LOCATORS = ["alt", "label", "placeholder", "role", "testid", "text", "title"] as const;
+const AGENT_BROWSER_JOB_STEP_ACTIONS = ["open", "click", "fill", "wait", "assertText", "assertUrl", "waitForDownload", "screenshot"] as const;
+const SOURCE_LOOKUP_WORKSPACE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+const SOURCE_LOOKUP_IGNORED_DIRECTORIES = new Set([".git", "node_modules", "dist", "build", "coverage", ".next", "out", "tmp", "temp"]);
+const SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES = 2_000;
+const SOURCE_LOOKUP_MAX_WORKSPACE_FILES = 5_000;
+
+type AgentBrowserSemanticActionName = (typeof AGENT_BROWSER_SEMANTIC_ACTIONS)[number];
+type AgentBrowserSemanticLocator = (typeof AGENT_BROWSER_SEMANTIC_LOCATORS)[number];
+type AgentBrowserJobStepAction = (typeof AGENT_BROWSER_JOB_STEP_ACTIONS)[number];
+type AgentBrowserSourceLookupStatus = "candidates-found" | "no-candidates" | "unsupported";
+type AgentBrowserNetworkSourceLookupStatus = "failed-requests-found" | "no-failed-requests" | "no-candidates";
+
+interface AgentBrowserSemanticActionInput {
+	action: AgentBrowserSemanticActionName;
+	locator: AgentBrowserSemanticLocator;
+	value: string;
+	text?: string;
+	role?: string;
+	name?: string;
+	session?: string;
+}
+
+interface CompiledAgentBrowserSemanticAction {
+	action: AgentBrowserSemanticActionName;
+	locator: AgentBrowserSemanticLocator;
+	args: string[];
+}
+
+interface CompiledAgentBrowserJobStep {
+	action: AgentBrowserJobStepAction;
+	args: string[];
+}
+
+interface CompiledAgentBrowserJob {
+	args: string[];
+	stdin: string;
+	steps: CompiledAgentBrowserJobStep[];
+}
+
+interface CompiledAgentBrowserQaPreset extends CompiledAgentBrowserJob {
+	checks: {
+		checkConsole: boolean;
+		checkErrors: boolean;
+		checkNetwork: boolean;
+		expectedText: string[];
+		expectedSelector?: string;
+		screenshotPath?: string;
+		url: string;
+	};
+}
+
+interface CompiledAgentBrowserSourceLookupStep {
+	action: "dom" | "react";
+	args: string[];
+}
+
+interface CompiledAgentBrowserSourceLookup {
+	args: string[];
+	stdin: string;
+	steps: CompiledAgentBrowserSourceLookupStep[];
+	query: {
+		componentName?: string;
+		includeDomHints: boolean;
+		maxWorkspaceFiles: number;
+		reactFiberId?: string;
+		selector?: string;
+	};
+}
+
+interface AgentBrowserSourceLookupCandidate {
+	column?: number;
+	componentName?: string;
+	confidence: "high" | "medium" | "low";
+	evidence: string[];
+	file?: string;
+	line?: number;
+	source: "react-inspect" | "dom-attribute" | "workspace-search";
+}
+
+interface AgentBrowserSourceLookupAnalysis {
+	candidates: AgentBrowserSourceLookupCandidate[];
+	limitations: string[];
+	status: AgentBrowserSourceLookupStatus;
+	summary: string;
+}
+
+interface CompiledAgentBrowserNetworkSourceLookup {
+	args: string[];
+	stdin: string;
+	steps: Array<{ action: "network"; args: string[] }>;
+	query: {
+		filter?: string;
+		maxWorkspaceFiles: number;
+		requestId?: string;
+		url?: string;
+	};
+}
+
+interface AgentBrowserNetworkSourceLookupRequest {
+	error?: string;
+	method?: string;
+	requestId?: string;
+	status?: number;
+	url?: string;
+}
+
+interface AgentBrowserNetworkSourceLookupCandidate {
+	confidence: "high" | "medium" | "low";
+	evidence: string[];
+	file?: string;
+	line?: number;
+	requestUrl?: string;
+	source: "initiator" | "workspace-search";
+}
+
+interface AgentBrowserNetworkSourceLookupAnalysis {
+	candidates: AgentBrowserNetworkSourceLookupCandidate[];
+	failedRequests: AgentBrowserNetworkSourceLookupRequest[];
+	limitations: string[];
+	status: AgentBrowserNetworkSourceLookupStatus;
+	summary: string;
+}
+
 const AGENT_BROWSER_PARAMS = Type.Object({
-	args: Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name." }), {
-		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; only supported for batch, eval --stdin, and auth save --password-stdin." })),
+
+	args: Type.Optional(
+		Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name." }), {
+			description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators. Required unless semanticAction, job, qa, sourceLookup, or networkSourceLookup is provided.",
+			minItems: 1,
+		}),
+	),
+	semanticAction: Type.Optional(
+		Type.Object({
+			action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS, {
+				description: "Intent action to compile to an existing agent-browser find command.",
+			}),
+			locator: StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, {
+				description: "Upstream find locator family to use.",
+			}),
+			value: Type.String({ description: "Locator value, such as visible text, label text, placeholder text, test id, title, alt text, or role." }),
+			text: Type.Optional(Type.String({ description: "Text/value argument for fill or select actions." })),
+			role: Type.Optional(Type.String({ description: "Role locator value; when set it must match value for locator=role." })),
+			name: Type.Optional(Type.String({ description: "Accessible name filter for locator=role; compiles to --name <name>." })),
+			session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the compiled find command." })),
+		}),
+	),
+	qa: Type.Optional(
+		Type.Object({
+			url: Type.String({ description: "URL to open for a lightweight QA preset." }),
+			expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Text that must appear on the page." })),
+			expectedSelector: Type.Optional(Type.String({ description: "Selector or @ref that must appear on the page." })),
+			screenshotPath: Type.Optional(Type.String({ description: "Optional evidence screenshot path captured at the end of the QA preset." })),
+			checkConsole: Type.Optional(Type.Boolean({ description: "Whether to fail on console error messages. Defaults to true." })),
+			checkErrors: Type.Optional(Type.Boolean({ description: "Whether to fail on page errors. Defaults to true." })),
+			checkNetwork: Type.Optional(Type.Boolean({ description: "Whether to inspect network requests and fail on actionable request failures; benign icon misses warn. Defaults to true." })),
+		}),
+	),
+	sourceLookup: Type.Optional(
+		Type.Object({
+			selector: Type.Optional(Type.String({ description: "Visible selector or @ref whose DOM metadata should be inspected for source hints." })),
+			reactFiberId: Type.Optional(Type.String({ description: "React fiber id to inspect with upstream react inspect. Requires a session opened with --enable react-devtools." })),
+			componentName: Type.Optional(Type.String({ description: "Component name to correlate with react tree output and bounded local workspace search." })),
+			includeDomHints: Type.Optional(Type.Boolean({ description: "Whether selector lookups should inspect DOM HTML attributes for source-like metadata. Defaults to true." })),
+			maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Maximum local source files to scan when componentName is provided. Defaults to 2000 and cannot exceed 5000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+		}),
+	),
+	networkSourceLookup: Type.Optional(
+		Type.Object({
+			filter: Type.Optional(Type.String({ description: "Optional upstream network requests filter pattern." })),
+			requestId: Type.Optional(Type.String({ description: "Optional network request id to inspect with network request <id>." })),
+			url: Type.Optional(Type.String({ description: "Optional failed request URL or URL fragment to correlate with local source." })),
+			maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Maximum local source files to scan for URL literals. Defaults to 2000 and cannot exceed 5000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+		}),
+	),
+	job: Type.Optional(
+		Type.Object({
+			steps: Type.Array(
+				Type.Object({
+					action: StringEnum(AGENT_BROWSER_JOB_STEP_ACTIONS, {
+						description: "Constrained one-call job step compiled to existing upstream batch commands.",
+					}),
+					url: Type.Optional(Type.String({ description: "URL for open steps, or URL pattern for assertUrl steps." })),
+					selector: Type.Optional(Type.String({ description: "Selector or @ref for click/fill/get-like steps." })),
+					text: Type.Optional(Type.String({ description: "Text for fill steps or visible text for assertText steps." })),
+					path: Type.Optional(Type.String({ description: "Artifact/download path for waitForDownload or screenshot steps." })),
+					milliseconds: Type.Optional(Type.Number({ description: "Milliseconds for wait steps." })),
+				}),
+				{ minItems: 1 },
+			),
+		}),
+	),
+	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch, eval --stdin, auth save --password-stdin, and is generated internally by job, qa, sourceLookup, or networkSourceLookup mode." })),
 	sessionMode: Type.Optional(
 		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 launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable 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, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
 			default: DEFAULT_SESSION_MODE,
 		}),
 	),
@@ -105,6 +298,725 @@ function buildInvocationPreview(effectiveArgs: string[]): string {
 	return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
 }
 
+function getRequiredJobString(step: Record<string, unknown>, field: "path" | "selector" | "text" | "url", action: AgentBrowserJobStepAction): { value?: string; error?: string } {
+	const value = step[field];
+	if (typeof value !== "string" || value.trim().length === 0) {
+		return { error: `job step ${action} requires a non-empty ${field} string.` };
+	}
+	return { value };
+}
+
+function compileAgentBrowserJob(input: unknown): { compiled?: CompiledAgentBrowserJob; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "job must be an object." };
+	}
+	const rawSteps = input.steps;
+	if (!Array.isArray(rawSteps) || rawSteps.length === 0) {
+		return { error: "job.steps must be a non-empty array." };
+	}
+	const steps: CompiledAgentBrowserJobStep[] = [];
+	for (const [index, rawStep] of rawSteps.entries()) {
+		if (!isRecord(rawStep)) {
+			return { error: `job.steps[${index}] must be an object.` };
+		}
+		const action = rawStep.action;
+		if (typeof action !== "string" || !AGENT_BROWSER_JOB_STEP_ACTIONS.includes(action as AgentBrowserJobStepAction)) {
+			return { error: `job.steps[${index}].action must be one of: ${AGENT_BROWSER_JOB_STEP_ACTIONS.join(", ")}.` };
+		}
+		const jobAction = action as AgentBrowserJobStepAction;
+		let args: string[];
+		if (jobAction === "open") {
+			const result = getRequiredJobString(rawStep, "url", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["open", result.value as string];
+		} else if (jobAction === "click") {
+			const result = getRequiredJobString(rawStep, "selector", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["click", result.value as string];
+		} else if (jobAction === "fill") {
+			const selector = getRequiredJobString(rawStep, "selector", jobAction);
+			if (selector.error) return { error: `job.steps[${index}]: ${selector.error}` };
+			const text = getRequiredJobString(rawStep, "text", jobAction);
+			if (text.error) return { error: `job.steps[${index}]: ${text.error}` };
+			args = ["fill", selector.value as string, text.value as string];
+		} else if (jobAction === "wait") {
+			const milliseconds = rawStep.milliseconds;
+			if (typeof milliseconds !== "number" || !Number.isInteger(milliseconds) || milliseconds <= 0) {
+				return { error: `job.steps[${index}]: job step wait requires a positive integer milliseconds value.` };
+			}
+			args = ["wait", String(milliseconds)];
+		} else if (jobAction === "assertText") {
+			const result = getRequiredJobString(rawStep, "text", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--text", result.value as string];
+		} else if (jobAction === "assertUrl") {
+			const result = getRequiredJobString(rawStep, "url", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--url", result.value as string];
+		} else if (jobAction === "waitForDownload") {
+			const result = getRequiredJobString(rawStep, "path", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--download", result.value as string];
+		} else {
+			const result = getRequiredJobString(rawStep, "path", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["screenshot", result.value as string];
+		}
+		steps.push({ action: jobAction, args });
+	}
+	return { compiled: { args: ["batch"], stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
+}
+
+interface AgentBrowserQaPresetAnalysis {
+	failedChecks: string[];
+	passed: boolean;
+	summary: string;
+	warnings: string[];
+}
+
+function getBatchResultItems(data: unknown): Array<Record<string, unknown>> {
+	return Array.isArray(data) ? data.filter(isRecord) : [];
+}
+
+function getCommandNameFromBatchItem(item: Record<string, unknown>): string | undefined {
+	const command = item.command;
+	return Array.isArray(command) && typeof command[0] === "string" ? command[0] : undefined;
+}
+
+function analyzeQaPresetResults(data: unknown): AgentBrowserQaPresetAnalysis | undefined {
+	const items = getBatchResultItems(data);
+	if (items.length === 0) return undefined;
+	const failedChecks: string[] = [];
+	const warnings: string[] = [];
+	for (const item of items) {
+		if (item.success === false) {
+			failedChecks.push(`${getCommandNameFromBatchItem(item) ?? "step"} failed`);
+		}
+		const result = isRecord(item.result) ? item.result : undefined;
+		const commandName = getCommandNameFromBatchItem(item);
+		if (commandName === "errors" && Array.isArray(result?.errors) && result.errors.length > 0) {
+			failedChecks.push(`${result.errors.length} page error(s)`);
+		}
+		if (commandName === "console" && Array.isArray(result?.messages)) {
+			const errorCount = result.messages.filter((message) => isRecord(message) && /error/i.test(String(message.type ?? message.level ?? ""))).length;
+			if (errorCount > 0) failedChecks.push(`${errorCount} console error message(s)`);
+		}
+		if (commandName === "network" && Array.isArray(result?.requests)) {
+			const networkFailures = summarizeNetworkFailures(result.requests);
+			if (networkFailures.actionableCount > 0) failedChecks.push(`${networkFailures.actionableCount} actionable failed network request(s)`);
+			if (networkFailures.benignCount > 0) warnings.push(`${networkFailures.benignCount} benign network request failure(s) ignored`);
+		}
+	}
+	const uniqueFailures = [...new Set(failedChecks)];
+	const uniqueWarnings = [...new Set(warnings)];
+	return {
+		failedChecks: uniqueFailures,
+		passed: uniqueFailures.length === 0,
+		summary: uniqueFailures.length === 0
+			? uniqueWarnings.length === 0 ? "QA preset passed." : `QA preset passed with warnings: ${uniqueWarnings.join("; ")}.`
+			: `QA preset failed: ${uniqueFailures.join("; ")}.`,
+		warnings: uniqueWarnings,
+	};
+}
+
+function compileAgentBrowserQaPreset(input: unknown): { compiled?: CompiledAgentBrowserQaPreset; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "qa must be an object." };
+	}
+	const url = input.url;
+	if (typeof url !== "string" || url.trim().length === 0) {
+		return { error: "qa.url must be a non-empty string." };
+	}
+	const expectedText = input.expectedText === undefined
+		? []
+		: typeof input.expectedText === "string"
+			? [input.expectedText]
+			: Array.isArray(input.expectedText)
+				? input.expectedText
+				: undefined;
+	if (!expectedText || expectedText.some((text) => typeof text !== "string" || text.trim().length === 0)) {
+		return { error: "qa.expectedText must be a non-empty string or array of non-empty strings when provided." };
+	}
+	const expectedSelector = input.expectedSelector;
+	if (expectedSelector !== undefined && (typeof expectedSelector !== "string" || expectedSelector.trim().length === 0)) {
+		return { error: "qa.expectedSelector must be a non-empty string when provided." };
+	}
+	const screenshotPath = input.screenshotPath;
+	if (screenshotPath !== undefined && (typeof screenshotPath !== "string" || screenshotPath.trim().length === 0)) {
+		return { error: "qa.screenshotPath must be a non-empty string when provided." };
+	}
+	for (const field of ["checkConsole", "checkErrors", "checkNetwork"] as const) {
+		if (input[field] !== undefined && typeof input[field] !== "boolean") {
+			return { error: `qa.${field} must be a boolean when provided.` };
+		}
+	}
+	const checkConsole = input.checkConsole !== false;
+	const checkErrors = input.checkErrors !== false;
+	const checkNetwork = input.checkNetwork !== false;
+	const steps: CompiledAgentBrowserJobStep[] = [];
+	if (checkNetwork) steps.push({ action: "wait", args: ["network", "requests", "--clear"] });
+	if (checkConsole) steps.push({ action: "wait", args: ["console", "--clear"] });
+	if (checkErrors) steps.push({ action: "wait", args: ["errors", "--clear"] });
+	steps.push(
+		{ action: "open", args: ["open", url] },
+		{ action: "wait", args: ["wait", "--load", "networkidle"] },
+	);
+	for (const text of expectedText) {
+		steps.push({ action: "assertText", args: ["wait", "--text", text] });
+	}
+	if (typeof expectedSelector === "string") {
+		steps.push({ action: "wait", args: ["wait", expectedSelector] });
+	}
+	if (checkNetwork) steps.push({ action: "wait", args: ["network", "requests"] });
+	if (checkConsole) steps.push({ action: "wait", args: ["console"] });
+	if (checkErrors) steps.push({ action: "wait", args: ["errors"] });
+	if (typeof screenshotPath === "string") steps.push({ action: "screenshot", args: ["screenshot", screenshotPath] });
+	return {
+		compiled: {
+			args: ["batch"],
+			checks: { checkConsole, checkErrors, checkNetwork, expectedSelector, expectedText, screenshotPath, url },
+			stdin: JSON.stringify(steps.map((step) => step.args)),
+			steps,
+		},
+	};
+}
+
+function compileAgentBrowserSourceLookup(input: unknown): { compiled?: CompiledAgentBrowserSourceLookup; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "sourceLookup must be an object." };
+	}
+	const selector = input.selector;
+	const reactFiberId = input.reactFiberId;
+	const componentName = input.componentName;
+	if (selector !== undefined && (typeof selector !== "string" || selector.trim().length === 0)) {
+		return { error: "sourceLookup.selector must be a non-empty string when provided." };
+	}
+	if (reactFiberId !== undefined && (typeof reactFiberId !== "string" || reactFiberId.trim().length === 0)) {
+		return { error: "sourceLookup.reactFiberId must be a non-empty string when provided." };
+	}
+	if (componentName !== undefined && (typeof componentName !== "string" || componentName.trim().length === 0)) {
+		return { error: "sourceLookup.componentName must be a non-empty string when provided." };
+	}
+	if (selector === undefined && reactFiberId === undefined && componentName === undefined) {
+		return { error: "sourceLookup requires selector, reactFiberId, or componentName." };
+	}
+	if (input.includeDomHints !== undefined && typeof input.includeDomHints !== "boolean") {
+		return { error: "sourceLookup.includeDomHints must be a boolean when provided." };
+	}
+	const rawMaxWorkspaceFiles = input.maxWorkspaceFiles;
+	if (rawMaxWorkspaceFiles !== undefined && (typeof rawMaxWorkspaceFiles !== "number" || !Number.isInteger(rawMaxWorkspaceFiles) || rawMaxWorkspaceFiles <= 0)) {
+		return { error: "sourceLookup.maxWorkspaceFiles must be a positive integer when provided." };
+	}
+	if (typeof rawMaxWorkspaceFiles === "number" && rawMaxWorkspaceFiles > SOURCE_LOOKUP_MAX_WORKSPACE_FILES) {
+		return { error: `sourceLookup.maxWorkspaceFiles must be ${SOURCE_LOOKUP_MAX_WORKSPACE_FILES} or less.` };
+	}
+	const includeDomHints = input.includeDomHints !== false;
+	const maxWorkspaceFiles = (rawMaxWorkspaceFiles as number | undefined) ?? SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES;
+	const steps: CompiledAgentBrowserSourceLookupStep[] = [];
+	if (typeof selector === "string") {
+		steps.push({ action: "dom", args: ["is", "visible", selector] });
+		if (includeDomHints) {
+			steps.push({ action: "dom", args: ["get", "html", selector] });
+		}
+	}
+	if (typeof reactFiberId === "string") {
+		steps.push({ action: "react", args: ["react", "inspect", reactFiberId] });
+	}
+	if (typeof componentName === "string") {
+		steps.push({ action: "react", args: ["react", "tree"] });
+	}
+	return {
+		compiled: {
+			args: ["batch"],
+			query: { componentName, includeDomHints, maxWorkspaceFiles, reactFiberId, selector },
+			stdin: JSON.stringify(steps.map((step) => step.args)),
+			steps,
+		},
+	};
+}
+
+function extractStringField(value: Record<string, unknown>, names: string[]): string | undefined {
+	for (const name of names) {
+		const field = value[name];
+		if (typeof field === "string" && field.trim().length > 0) return field;
+	}
+	return undefined;
+}
+
+function extractNumberField(value: Record<string, unknown>, names: string[]): number | undefined {
+	for (const name of names) {
+		const field = value[name];
+		if (typeof field === "number" && Number.isFinite(field)) return field;
+		if (typeof field === "string" && /^\d+$/.test(field)) return Number(field);
+	}
+	return undefined;
+}
+
+function candidateKey(candidate: AgentBrowserSourceLookupCandidate): string {
+	return [candidate.source, candidate.file ?? "", candidate.line ?? "", candidate.column ?? "", candidate.componentName ?? ""].join(":");
+}
+
+function addSourceLookupCandidate(candidates: AgentBrowserSourceLookupCandidate[], candidate: AgentBrowserSourceLookupCandidate): void {
+	if (!candidates.some((existing) => candidateKey(existing) === candidateKey(candidate))) {
+		candidates.push(candidate);
+	}
+}
+
+function collectSourceCandidatesFromValue(value: unknown, source: "react-inspect" | "dom-attribute", candidates: AgentBrowserSourceLookupCandidate[], evidence: string[], depth = 0): void {
+	if (depth > 6 || value === undefined || value === null) return;
+	if (typeof value === "string") {
+		const sourcePattern = /([A-Za-z0-9_./@-]+\.(?:tsx|jsx|ts|js))(?:[:#](\d+))?(?:[:#](\d+))?/g;
+		for (const match of value.matchAll(sourcePattern)) {
+			addSourceLookupCandidate(candidates, {
+				column: match[3] ? Number(match[3]) : undefined,
+				confidence: source === "react-inspect" ? "high" : "medium",
+				evidence,
+				file: match[1],
+				line: match[2] ? Number(match[2]) : undefined,
+				source,
+			});
+		}
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) collectSourceCandidatesFromValue(item, source, candidates, evidence, depth + 1);
+		return;
+	}
+	if (!isRecord(value)) return;
+	const file = extractStringField(value, ["file", "fileName", "filename", "filePath", "path", "source", "url"]);
+	if (file && /\.(?:tsx|jsx|ts|js)(?:$|[:?#])/.test(file)) {
+		addSourceLookupCandidate(candidates, {
+			column: extractNumberField(value, ["column", "columnNumber", "col"]),
+			confidence: source === "react-inspect" ? "high" : "medium",
+			evidence,
+			file,
+			line: extractNumberField(value, ["line", "lineNumber"]),
+			source,
+		});
+	}
+	for (const nested of Object.values(value)) {
+		collectSourceCandidatesFromValue(nested, source, candidates, evidence, depth + 1);
+	}
+}
+
+function getHtmlAttributeValue(html: string, name: string): string | undefined {
+	const pattern = new RegExp(`${name}=["']([^"']+)["']`, "i");
+	return pattern.exec(html)?.[1];
+}
+
+function collectDomSourceCandidates(html: unknown, candidates: AgentBrowserSourceLookupCandidate[]): void {
+	if (typeof html !== "string") return;
+	const file = getHtmlAttributeValue(html, "(?:data-source-file|data-file|data-component-file|data-source)");
+	if (file && /\.(?:tsx|jsx|ts|js)$/.test(file)) {
+		const line = getHtmlAttributeValue(html, "(?:data-source-line|data-line)");
+		const column = getHtmlAttributeValue(html, "(?:data-source-column|data-column)");
+		addSourceLookupCandidate(candidates, {
+			column: column && /^\d+$/.test(column) ? Number(column) : undefined,
+			confidence: "medium",
+			evidence: ["selector HTML contained source-like data attributes"],
+			file,
+			line: line && /^\d+$/.test(line) ? Number(line) : undefined,
+			source: "dom-attribute",
+		});
+	}
+	collectSourceCandidatesFromValue(html, "dom-attribute", candidates, ["selector HTML contained source-like text"]);
+}
+
+async function walkWorkspaceSourceFiles(root: string, maxFiles: number): Promise<string[]> {
+	const files: string[] = [];
+	async function visit(directory: string): Promise<void> {
+		if (files.length >= maxFiles) return;
+		let entries: Array<{ isDirectory: () => boolean; isFile: () => boolean; name: string }>;
+		try {
+			entries = await readdir(directory, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (files.length >= maxFiles) return;
+			const path = join(directory, entry.name);
+			if (entry.isDirectory()) {
+				if (!SOURCE_LOOKUP_IGNORED_DIRECTORIES.has(entry.name)) await visit(path);
+			} else if (entry.isFile() && SOURCE_LOOKUP_WORKSPACE_EXTENSIONS.has(extname(entry.name))) {
+				files.push(path);
+			}
+		}
+	}
+	await visit(root);
+	return files;
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+async function collectWorkspaceComponentCandidates(query: CompiledAgentBrowserSourceLookup["query"], cwd: string, candidates: AgentBrowserSourceLookupCandidate[], limitations: string[]): Promise<void> {
+	if (!query.componentName) return;
+	const files = await walkWorkspaceSourceFiles(cwd, query.maxWorkspaceFiles);
+	if (files.length >= query.maxWorkspaceFiles) {
+		limitations.push(`Workspace source scan stopped at ${query.maxWorkspaceFiles} files.`);
+	}
+	const componentPattern = new RegExp(`(?:function|class)\\s+${escapeRegExp(query.componentName)}\\b|(?:const|let|var)\\s+${escapeRegExp(query.componentName)}\\s*=|export\\s+default\\s+function\\s+${escapeRegExp(query.componentName)}\\b`);
+	for (const file of files) {
+		let text: string;
+		try {
+			text = await readFile(file, "utf8");
+		} catch {
+			continue;
+		}
+		const match = componentPattern.exec(text);
+		if (!match) continue;
+		const line = text.slice(0, match.index).split("\n").length;
+		addSourceLookupCandidate(candidates, {
+			componentName: query.componentName,
+			confidence: "low",
+			evidence: [`local workspace contains a matching ${query.componentName} declaration`],
+			file,
+			line,
+			source: "workspace-search",
+		});
+		if (candidates.filter((candidate) => candidate.source === "workspace-search").length >= 10) break;
+	}
+}
+
+function validateLookupMaxWorkspaceFiles(value: unknown, fieldName: string): { value?: number; error?: string } {
+	if (value === undefined) return { value: SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES };
+	if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+		return { error: `${fieldName} must be a positive integer when provided.` };
+	}
+	if (value > SOURCE_LOOKUP_MAX_WORKSPACE_FILES) {
+		return { error: `${fieldName} must be ${SOURCE_LOOKUP_MAX_WORKSPACE_FILES} or less.` };
+	}
+	return { value };
+}
+
+async function analyzeSourceLookupResults(data: unknown, compiled: CompiledAgentBrowserSourceLookup, cwd: string): Promise<AgentBrowserSourceLookupAnalysis> {
+	const items = getBatchResultItems(data);
+	const candidates: AgentBrowserSourceLookupCandidate[] = [];
+	const limitations = [
+		"Experimental lookup only reports candidates with evidence; it cannot guarantee a DOM node maps to one source file.",
+		"React source hints require the page to be opened with --enable react-devtools and source information from the app build.",
+	];
+	let unsupported = false;
+	for (const item of items) {
+		const command = Array.isArray(item.command) ? item.command : [];
+		const result = isRecord(item.result) && "data" in item.result ? item.result.data : item.result;
+		if (item.success === false && command[0] === "react") unsupported = true;
+		if (command[0] === "react" && command[1] === "inspect") {
+			collectSourceCandidatesFromValue(result, "react-inspect", candidates, ["react inspect returned source-like metadata"]);
+		}
+		if (command[0] === "get" && command[1] === "html") {
+			collectDomSourceCandidates(result, candidates);
+		}
+	}
+	await collectWorkspaceComponentCandidates(compiled.query, cwd, candidates, limitations);
+	const status: AgentBrowserSourceLookupStatus = candidates.length > 0 ? "candidates-found" : unsupported ? "unsupported" : "no-candidates";
+	return {
+		candidates,
+		limitations,
+		status,
+		summary: candidates.length > 0
+			? `Source lookup found ${candidates.length} candidate location(s).`
+			: unsupported
+				? "Source lookup could not inspect React metadata in this session."
+				: "Source lookup found no candidate locations.",
+	};
+}
+
+function compileAgentBrowserNetworkSourceLookup(input: unknown): { compiled?: CompiledAgentBrowserNetworkSourceLookup; error?: string } {
+	if (!isRecord(input)) return { error: "networkSourceLookup must be an object." };
+	const filter = input.filter;
+	const requestId = input.requestId;
+	const url = input.url;
+	if (filter !== undefined && (typeof filter !== "string" || filter.trim().length === 0)) return { error: "networkSourceLookup.filter must be a non-empty string when provided." };
+	if (requestId !== undefined && (typeof requestId !== "string" || requestId.trim().length === 0)) return { error: "networkSourceLookup.requestId must be a non-empty string when provided." };
+	if (url !== undefined && (typeof url !== "string" || url.trim().length === 0)) return { error: "networkSourceLookup.url must be a non-empty string when provided." };
+	if (filter === undefined && requestId === undefined && url === undefined) return { error: "networkSourceLookup requires requestId, filter, or url." };
+	const maxWorkspaceFiles = validateLookupMaxWorkspaceFiles(input.maxWorkspaceFiles, "networkSourceLookup.maxWorkspaceFiles");
+	if (maxWorkspaceFiles.error) return { error: maxWorkspaceFiles.error };
+	const steps: Array<{ action: "network"; args: string[] }> = [];
+	if (typeof requestId === "string") {
+		steps.push({ action: "network", args: ["network", "request", requestId] });
+	}
+	const effectiveFilter = typeof filter === "string" ? filter : typeof url === "string" ? url : undefined;
+	if (effectiveFilter) {
+		steps.push({ action: "network", args: ["network", "requests", "--filter", effectiveFilter] });
+	}
+	return { compiled: { args: ["batch"], query: { filter, maxWorkspaceFiles: maxWorkspaceFiles.value as number, requestId, url }, stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
+}
+
+function getResultPayload(item: Record<string, unknown>): unknown {
+	return isRecord(item.result) && "data" in item.result ? item.result.data : item.result;
+}
+
+function networkRequestMatchesQuery(url: string | undefined, queryText: string | undefined): boolean {
+	return queryText === undefined || url === undefined || url.includes(queryText) || queryText.includes(url);
+}
+
+function isFailedNetworkRecord(request: Record<string, unknown>): boolean {
+	const status = typeof request.status === "number" ? request.status : undefined;
+	const error = typeof request.error === "string" ? request.error : undefined;
+	return request.failed === true || error !== undefined || (status !== undefined && status >= 400);
+}
+
+function getFailedNetworkRequests(data: unknown, queryText?: string): AgentBrowserNetworkSourceLookupRequest[] {
+	const failed: AgentBrowserNetworkSourceLookupRequest[] = [];
+	for (const item of getBatchResultItems(data)) {
+		const payload = getResultPayload(item);
+		const requests = isRecord(payload) && Array.isArray(payload.requests) ? payload.requests : Array.isArray(payload) ? payload : isRecord(payload) ? [payload] : [];
+		for (const request of requests) {
+			if (!isRecord(request)) continue;
+			const url = typeof request.url === "string" ? request.url : undefined;
+			if (!networkRequestMatchesQuery(url, queryText) || !isFailedNetworkRecord(request)) continue;
+			failed.push({
+				error: typeof request.error === "string" ? request.error : undefined,
+				method: typeof request.method === "string" ? request.method : undefined,
+				requestId: typeof request.id === "string" ? request.id : typeof request.requestId === "string" ? request.requestId : undefined,
+				status: typeof request.status === "number" ? request.status : undefined,
+				url,
+			});
+		}
+	}
+	return failed;
+}
+
+function addNetworkCandidate(candidates: AgentBrowserNetworkSourceLookupCandidate[], candidate: AgentBrowserNetworkSourceLookupCandidate): void {
+	const key = [candidate.source, candidate.file ?? "", candidate.line ?? "", candidate.requestUrl ?? ""].join(":");
+	if (!candidates.some((existing) => [existing.source, existing.file ?? "", existing.line ?? "", existing.requestUrl ?? ""].join(":") === key)) candidates.push(candidate);
+}
+
+function collectInitiatorCandidates(data: unknown, failedRequests: AgentBrowserNetworkSourceLookupRequest[], candidates: AgentBrowserNetworkSourceLookupCandidate[]): void {
+	const failedRequestIds = new Set(failedRequests.map((request) => request.requestId).filter((value): value is string => value !== undefined));
+	const failedRequestUrls = new Set(failedRequests.map((request) => request.url).filter((value): value is string => value !== undefined));
+	for (const item of getBatchResultItems(data)) {
+		const payload = getResultPayload(item);
+		const requestValues = isRecord(payload) && Array.isArray(payload.requests) ? payload.requests : [payload];
+		for (const value of requestValues) {
+			if (!isRecord(value)) continue;
+			const requestUrl = typeof value.url === "string" ? value.url : undefined;
+			const requestId = typeof value.id === "string" ? value.id : typeof value.requestId === "string" ? value.requestId : undefined;
+			const correlatesWithFailedRequest = (requestId !== undefined && failedRequestIds.has(requestId)) || (requestUrl !== undefined && failedRequestUrls.has(requestUrl));
+			if (!correlatesWithFailedRequest && !isFailedNetworkRecord(value)) continue;
+			for (const field of [value.initiator, value.stack, value.source, value.trace]) {
+				const localCandidates: AgentBrowserSourceLookupCandidate[] = [];
+				collectSourceCandidatesFromValue(field, "dom-attribute", localCandidates, ["failed network request included source-like initiator metadata"]);
+				for (const candidate of localCandidates) {
+					addNetworkCandidate(candidates, { confidence: "medium", evidence: candidate.evidence, file: candidate.file, line: candidate.line, requestUrl, source: "initiator" });
+				}
+			}
+		}
+	}
+}
+
+async function collectWorkspaceRequestCandidates(query: CompiledAgentBrowserNetworkSourceLookup["query"], failedRequests: AgentBrowserNetworkSourceLookupRequest[], cwd: string, candidates: AgentBrowserNetworkSourceLookupCandidate[], limitations: string[]): Promise<void> {
+	const needles = [...new Set([query.url, query.filter, ...failedRequests.map((request) => request.url)].filter((value): value is string => typeof value === "string" && value.length > 0).flatMap((value) => {
+		try {
+			const parsed = new URL(value);
+			return [value, parsed.pathname].filter((item) => item && item !== "/");
+		} catch {
+			return [value];
+		}
+	}))].slice(0, 8);
+	if (needles.length === 0) return;
+	const files = await walkWorkspaceSourceFiles(cwd, query.maxWorkspaceFiles);
+	if (files.length >= query.maxWorkspaceFiles) limitations.push(`Workspace source scan stopped at ${query.maxWorkspaceFiles} files.`);
+	for (const file of files) {
+		let text: string;
+		try { text = await readFile(file, "utf8"); } catch { continue; }
+		for (const needle of needles) {
+			const index = text.indexOf(needle);
+			if (index === -1) continue;
+			addNetworkCandidate(candidates, { confidence: "low", evidence: [`local workspace contains request URL literal ${needle}`], file, line: text.slice(0, index).split("\n").length, requestUrl: needle, source: "workspace-search" });
+			if (candidates.filter((candidate) => candidate.source === "workspace-search").length >= 10) return;
+		}
+	}
+}
+
+function redactNetworkSourceLookupUrl(value: string | undefined): string | undefined {
+	if (!value) return value;
+	try {
+		const isRelative = value.startsWith("/");
+		const url = new URL(value, isRelative ? "https://redacted.invalid" : undefined);
+		url.username = url.username ? "[REDACTED]" : "";
+		url.password = url.password ? "[REDACTED]" : "";
+		for (const key of [...url.searchParams.keys()]) {
+			url.searchParams.set(key, "[REDACTED]");
+		}
+		if (/(?:token|secret|password|passwd|pwd|key|auth|session|jwt|credential)/i.test(url.hash)) {
+			url.hash = "#[REDACTED]";
+		}
+		return isRelative ? `${url.pathname}${url.search}${url.hash}` : url.toString();
+	} catch {
+		return redactSensitiveText(value
+			.replace(/([a-z][a-z0-9+.-]*:\/\/)\S+:\S+@/gi, "$1[REDACTED]@")
+			.replace(/([?&][^=]+)=([^&#\s"'\]]+)/g, "$1=[REDACTED]"));
+	}
+}
+
+function redactNetworkSourceLookupArgs(args: string[]): string[] {
+	return redactInvocationArgs(args).map((arg) => redactNetworkSourceLookupUrl(arg) ?? arg);
+}
+
+function redactNetworkSourceLookupSurface(value: unknown): unknown {
+	if (typeof value === "string") return redactNetworkSourceLookupUrl(value) ?? value;
+	if (Array.isArray(value)) return value.map((item) => redactNetworkSourceLookupSurface(item));
+	if (!isRecord(value)) return value;
+	return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactNetworkSourceLookupSurface(item)]));
+}
+
+function redactNetworkSourceLookupAnalysis(analysis: AgentBrowserNetworkSourceLookupAnalysis): AgentBrowserNetworkSourceLookupAnalysis {
+	return {
+		...analysis,
+		candidates: analysis.candidates.map((candidate) => ({
+			...candidate,
+			evidence: candidate.evidence.map((item) => redactNetworkSourceLookupUrl(item) ?? redactSensitiveText(item)),
+			file: redactNetworkSourceLookupUrl(candidate.file),
+			requestUrl: redactNetworkSourceLookupUrl(candidate.requestUrl),
+		})),
+		failedRequests: analysis.failedRequests.map((request) => ({ ...request, error: redactNetworkSourceLookupUrl(request.error), url: redactNetworkSourceLookupUrl(request.url) })),
+	};
+}
+
+async function analyzeNetworkSourceLookupResults(data: unknown, compiled: CompiledAgentBrowserNetworkSourceLookup, cwd: string): Promise<AgentBrowserNetworkSourceLookupAnalysis> {
+	const limitations = [
+		"Experimental network source hints report candidates only; failed requests can be triggered indirectly by frameworks, caches, service workers, or third-party scripts.",
+		"Initiator/source-map metadata is upstream/browser-build dependent and may be absent.",
+	];
+	const failedRequests = getFailedNetworkRequests(data, compiled.query.url ?? compiled.query.filter);
+	const candidates: AgentBrowserNetworkSourceLookupCandidate[] = [];
+	collectInitiatorCandidates(data, failedRequests, candidates);
+	await collectWorkspaceRequestCandidates(compiled.query, failedRequests, cwd, candidates, limitations);
+	const status: AgentBrowserNetworkSourceLookupStatus = failedRequests.length === 0 ? "no-failed-requests" : candidates.length > 0 ? "failed-requests-found" : "no-candidates";
+	return { candidates, failedRequests, limitations, status, summary: failedRequests.length === 0 ? "Network source lookup found no failed requests." : candidates.length > 0 ? `Network source lookup found ${failedRequests.length} failed request(s) and ${candidates.length} candidate source hint(s).` : `Network source lookup found ${failedRequests.length} failed request(s) but no source candidates.` };
+}
+
+function appendSemanticActionTextArg(args: string[], action: string, text: string | undefined): void {
+	if ((action === "fill" || action === "select") && text) {
+		args.push(text);
+	}
+}
+
+function getCompiledSemanticActionCommandIndex(compiled: CompiledAgentBrowserSemanticAction): number {
+	return compiled.args[0] === "--session" ? 2 : 0;
+}
+
+function getCompiledSemanticActionTextArg(compiled: CompiledAgentBrowserSemanticAction): string | undefined {
+	if (compiled.action !== "fill" && compiled.action !== "select") return undefined;
+	const commandIndex = getCompiledSemanticActionCommandIndex(compiled);
+	if (commandIndex < 0) return undefined;
+	const markerIndex = compiled.args.indexOf("--name");
+	return markerIndex >= 0 ? compiled.args[markerIndex - 1] : compiled.args[commandIndex + 4];
+}
+
+function getCompiledSemanticActionSessionPrefix(compiled: CompiledAgentBrowserSemanticAction): string[] {
+	const commandIndex = getCompiledSemanticActionCommandIndex(compiled);
+	return commandIndex > 0 ? compiled.args.slice(0, commandIndex) : [];
+}
+
+const SEMANTIC_ACTION_CANDIDATE_ACTION_IDS = new Set([
+	"try-searchbox-name-candidate",
+	"try-textbox-name-candidate",
+	"try-button-name-candidate",
+	"try-link-name-candidate",
+	"try-labeled-textbox-candidate",
+]);
+
+function formatSemanticActionCandidateText(actions: AgentBrowserNextAction[]): string | undefined {
+	const candidateActions = actions.filter((action) => SEMANTIC_ACTION_CANDIDATE_ACTION_IDS.has(action.id) && action.params?.args);
+	if (candidateActions.length === 0) return undefined;
+	return [
+		"Agent-browser candidate fallbacks:",
+		...candidateActions.map((action) => `- ${action.id}: agent_browser ${JSON.stringify({ args: action.params?.args })} — ${action.reason}`),
+	].join("\n");
+}
+
+function buildSemanticActionCandidateActions(compiled: CompiledAgentBrowserSemanticAction): AgentBrowserNextAction[] {
+	const commandIndex = getCompiledSemanticActionCommandIndex(compiled);
+	if (commandIndex < 0) return [];
+	const locator = compiled.args[commandIndex + 1];
+	const value = compiled.args[commandIndex + 2];
+	if (!locator || !value) return [];
+	const text = getCompiledSemanticActionTextArg(compiled);
+	const sessionPrefix = getCompiledSemanticActionSessionPrefix(compiled);
+	const buildRoleCandidate = (role: string, id: string, reason: string): AgentBrowserNextAction => {
+		const args = [...sessionPrefix, "find", "role", role, compiled.action];
+		appendSemanticActionTextArg(args, compiled.action, text);
+		args.push("--name", value);
+		return {
+			id,
+			params: { args: redactInvocationArgs(args) },
+			reason,
+			safety: "Candidate locator fallback only; inspect the page if multiple elements could match the same accessible name.",
+			tool: "agent_browser" as const,
+		};
+	};
+
+	if (locator === "placeholder" && compiled.action === "fill") {
+		return [
+			buildRoleCandidate("searchbox", "try-searchbox-name-candidate", "Retry against a searchbox with the same accessible name; many search inputs expose names instead of placeholders."),
+			buildRoleCandidate("textbox", "try-textbox-name-candidate", "Retry against a textbox with the same accessible name when placeholder lookup misses."),
+		];
+	}
+	if (locator === "text" && compiled.action === "click") {
+		return [
+			buildRoleCandidate("button", "try-button-name-candidate", "Retry against a button with the same accessible name when text lookup misses."),
+			buildRoleCandidate("link", "try-link-name-candidate", "Retry against a link with the same accessible name when text lookup misses."),
+		];
+	}
+	if (locator === "label" && compiled.action === "fill") {
+		return [buildRoleCandidate("textbox", "try-labeled-textbox-candidate", "Retry against a textbox with the same accessible name when label lookup misses.")];
+	}
+	return [];
+}
+
+function compileAgentBrowserSemanticAction(input: unknown): { compiled?: CompiledAgentBrowserSemanticAction; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "semanticAction must be an object." };
+	}
+	const action = input.action;
+	const locator = input.locator;
+	const value = input.value;
+	const text = input.text;
+	const role = input.role;
+	const name = input.name;
+	const session = input.session;
+	if (typeof action !== "string" || !AGENT_BROWSER_SEMANTIC_ACTIONS.includes(action as AgentBrowserSemanticActionName)) {
+		return { error: `semanticAction.action must be one of: ${AGENT_BROWSER_SEMANTIC_ACTIONS.join(", ")}.` };
+	}
+	if (typeof locator !== "string" || !AGENT_BROWSER_SEMANTIC_LOCATORS.includes(locator as AgentBrowserSemanticLocator)) {
+		return { error: `semanticAction.locator must be one of: ${AGENT_BROWSER_SEMANTIC_LOCATORS.join(", ")}.` };
+	}
+	if (typeof value !== "string" || value.trim().length === 0) {
+		return { error: "semanticAction.value must be a non-empty string." };
+	}
+	if (text !== undefined && typeof text !== "string") {
+		return { error: "semanticAction.text must be a string when provided." };
+	}
+	if ((action === "fill" || action === "select") && (typeof text !== "string" || text.length === 0)) {
+		return { error: `semanticAction.text is required for ${action}.` };
+	}
+	if (action !== "fill" && action !== "select" && text !== undefined) {
+		return { error: `semanticAction.text is only supported for fill and select actions.` };
+	}
+	if (role !== undefined && (locator !== "role" || role !== value)) {
+		return { error: "semanticAction.role is only supported for locator=role and must match value." };
+	}
+	if (name !== undefined && (locator !== "role" || typeof name !== "string" || name.length === 0)) {
+		return { error: "semanticAction.name is only supported as a non-empty string for locator=role." };
+	}
+	if (session !== undefined && (typeof session !== "string" || session.trim().length === 0)) {
+		return { error: "semanticAction.session must be a non-empty string when provided." };
+	}
+	const args = typeof session === "string" ? ["--session", session, "find", locator, value, action] : ["find", locator, value, action];
+	if (action === "fill" || action === "select") {
+		args.push(text as string);
+	}
+	if (locator === "role" && typeof name === "string") {
+		args.push("--name", name);
+	}
+	return { compiled: { action: action as AgentBrowserSemanticActionName, locator: locator as AgentBrowserSemanticLocator, args } };
+}
+
 const TUI_COLLAPSED_OUTPUT_MAX_LINES = 10;
 const TUI_INVOCATION_PREVIEW_MAX_CHARS = 120;
 const ANSI_CONTROL_SEQUENCE_PATTERN = /\x1B(?:\][^\x07\x1B]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|P[^\x1B]*(?:\x1B\\)|_[^\x1B]*(?:\x1B\\)|\^[^\x1B]*(?:\x1B\\)|[@-Z\\-_])/g;
@@ -178,7 +1090,15 @@ function formatVisualTruncationNotice(remainingLines: number, totalLines: number
 
 function formatAgentBrowserRenderCall(args: unknown, theme: Theme): string {
 	const input = isRecord(args) ? args : {};
-	const rawArgs = Array.isArray(input.args) ? input.args.filter((value): value is string => typeof value === "string") : [];
+	const semanticAction = compileAgentBrowserSemanticAction(input.semanticAction);
+	const job = compileAgentBrowserJob(input.job);
+	const qa = compileAgentBrowserQaPreset(input.qa);
+	const sourceLookup = compileAgentBrowserSourceLookup(input.sourceLookup);
+	const networkSourceLookup = compileAgentBrowserNetworkSourceLookup(input.networkSourceLookup);
+	const generatedBatch = networkSourceLookup.compiled ?? sourceLookup.compiled ?? job.compiled ?? qa.compiled;
+	const rawArgs = Array.isArray(input.args)
+		? input.args.filter((value): value is string => typeof value === "string")
+		: (semanticAction.compiled?.args ?? generatedBatch?.args ?? []);
 	const redactedArgs = redactInvocationArgs(rawArgs);
 	const invocation = sanitizeDisplayText(redactedArgs.join(" ")).replace(/\s+/g, " ").trim();
 	const invocationPreview =
@@ -475,6 +1395,72 @@ interface NavigationSummary {
 	url?: string;
 }
 
+interface OverlayBlockerCandidate {
+	args: string[];
+	name?: string;
+	reason: string;
+	ref: string;
+	role?: string;
+}
+
+interface OverlayBlockerDiagnostic {
+	candidates: OverlayBlockerCandidate[];
+	snapshot: SessionRefSnapshot;
+	summary: string;
+}
+
+interface SelectorTextVisibilityDiagnostic {
+	firstMatchVisible?: boolean;
+	firstVisibleTextPreview?: string;
+	matchCount: number;
+	selector: string;
+	summary: string;
+	visibleCount: number;
+}
+
+interface TimeoutArtifactEvidence {
+	absolutePath: string;
+	exists: boolean;
+	path: string;
+	sizeBytes?: number;
+	stepIndex: number;
+}
+
+interface TimeoutPartialProgress {
+	artifacts: TimeoutArtifactEvidence[];
+	currentPage?: {
+		title?: string;
+		url?: string;
+	};
+	steps?: Array<{ args: string[]; index: number }>;
+	summary: string;
+}
+
+interface EvalStdinHint {
+	reason: string;
+	suggestion: string;
+}
+
+interface ArtifactCleanupGuidance {
+	explicitArtifactPaths: string[];
+	note: string;
+	owner: "host-file-tools";
+	summary: string;
+}
+
+interface ManagedSessionOutcome {
+	activeAfter: boolean;
+	activeBefore: boolean;
+	attemptedSessionName?: string;
+	currentSessionName: string;
+	previousSessionName: string;
+	replacedSessionName?: string;
+	sessionMode: "auto" | "fresh";
+	status: "abandoned" | "closed" | "created" | "preserved" | "replaced" | "unchanged";
+	succeeded: boolean;
+	summary: string;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
@@ -878,7 +1864,7 @@ function shouldCaptureNavigationSummary(command: string | undefined, data: unkno
 	);
 }
 
-function extractStringResultField(data: unknown, fieldName: "title" | "url"): string | undefined {
+function extractStringResultField(data: unknown, fieldName: "result" | "title" | "url"): string | undefined {
 	if (typeof data === "string") {
 		const text = data.trim();
 		return text.length > 0 ? text : undefined;
@@ -915,6 +1901,21 @@ interface OrderedSessionTabTarget {
 	target: SessionTabTarget;
 }
 
+interface SessionRefSnapshot {
+	refIds: string[];
+	target?: SessionTabTarget;
+}
+
+interface OrderedSessionRefSnapshot extends SessionRefSnapshot {
+	order: number;
+}
+
+interface StaleRefPreflight {
+	message: string;
+	refIds: string[];
+	snapshot?: SessionRefSnapshot;
+}
+
 interface AboutBlankSessionMismatch {
 	activeUrl: "about:blank";
 	recoveryApplied: boolean;
@@ -923,7 +1924,7 @@ interface AboutBlankSessionMismatch {
 	targetUrl: string;
 }
 
-function getLatestSessionTabTargetOrder(targets: Map<string, OrderedSessionTabTarget>): number {
+function getLatestSessionTabTargetOrder(targets: Map<string, { order: number }>): number {
 	let latestOrder = 0;
 	for (const target of targets.values()) {
 		latestOrder = Math.max(latestOrder, target.order);
@@ -932,7 +1933,7 @@ function getLatestSessionTabTargetOrder(targets: Map<string, OrderedSessionTabTa
 }
 
 function shouldApplySessionTabTargetUpdate(options: {
-	current?: OrderedSessionTabTarget;
+	current?: { order: number };
 	updateOrder: number;
 }): boolean {
 	return !options.current || options.updateOrder >= options.current.order;
@@ -1072,10 +2073,70 @@ function restoreSessionTabTargetsFromBranch(branch: unknown[]): Map<string, Orde
 			: undefined;
 		if (sessionTabTarget) {
 			restoredOrder += 1;
-			restoredTargets.set(sessionName, { order: restoredOrder, target: sessionTabTarget });
+			restoredTargets.set(sessionName, { order: restoredOrder, target: sessionTabTarget });
+		}
+	}
+	return restoredTargets;
+}
+
+function extractRefSnapshotFromData(data: unknown): SessionRefSnapshot | undefined {
+	if (!isRecord(data)) return undefined;
+	const refIds = isRecord(data.refs) ? Object.keys(data.refs).filter((refId) => /^e\d+$/.test(refId)) : [];
+	if (refIds.length === 0) return undefined;
+	return {
+		refIds,
+		target: extractSessionTabTargetFromData(data),
+	};
+}
+
+function extractRefSnapshotFromBatchResults(data: unknown): SessionRefSnapshot | undefined {
+	if (!Array.isArray(data)) return undefined;
+	let latestSnapshot: SessionRefSnapshot | undefined;
+	for (const item of data) {
+		if (!isRecord(item) || item.success === false) continue;
+		const [name] = extractBatchResultCommand(item);
+		if (name !== "snapshot") continue;
+		latestSnapshot = extractRefSnapshotFromData(item.result) ?? latestSnapshot;
+	}
+	return latestSnapshot;
+}
+
+function restoreSessionRefSnapshotsFromBranch(branch: unknown[]): Map<string, OrderedSessionRefSnapshot> {
+	const restoredSnapshots = new Map<string, OrderedSessionRefSnapshot>();
+	let restoredOrder = 0;
+	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 (!details) continue;
+		const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
+		if (!sessionName) continue;
+		const command = typeof details.command === "string" ? details.command : undefined;
+		if (command === "close" && message.isError !== true) {
+			restoredOrder += 1;
+			restoredSnapshots.delete(sessionName);
+			continue;
+		}
+		const refSnapshot = isRecord(details.refSnapshot)
+			? {
+				refIds: Array.isArray(details.refSnapshot.refIds)
+					? details.refSnapshot.refIds.filter((refId): refId is string => typeof refId === "string" && /^e\d+$/.test(refId))
+					: [],
+				target: isRecord(details.refSnapshot.target)
+					? normalizeSessionTabTarget({
+							title: typeof details.refSnapshot.target.title === "string" ? details.refSnapshot.target.title : undefined,
+							url: typeof details.refSnapshot.target.url === "string" ? details.refSnapshot.target.url : undefined,
+					  })
+					: undefined,
+			  }
+			: undefined;
+		if (refSnapshot && refSnapshot.refIds.length > 0) {
+			restoredOrder += 1;
+			restoredSnapshots.set(sessionName, { ...refSnapshot, order: restoredOrder });
 		}
 	}
-	return restoredTargets;
+	return restoredSnapshots;
 }
 
 function restoreArtifactManifestFromBranch(branch: unknown[]): SessionArtifactManifest | undefined {
@@ -1227,6 +2288,46 @@ function parseUserBatchStdin(stdin: string | undefined): { error?: string; steps
 	}
 }
 
+const REF_INVALIDATING_BATCH_COMMANDS = new Set([
+	"back",
+	"check",
+	"click",
+	"dblclick",
+	"drag",
+	"fill",
+	"forward",
+	"goto",
+	"keyboard",
+	"mouse",
+	"navigate",
+	"open",
+	"press",
+	"reload",
+	"select",
+	"type",
+	"uncheck",
+	"upload",
+]);
+
+const REF_GUARDED_COMMANDS = new Set([
+	"check",
+	"click",
+	"dblclick",
+	"download",
+	"drag",
+	"fill",
+	"focus",
+	"hover",
+	"keyboard",
+	"mouse",
+	"press",
+	"scrollintoview",
+	"select",
+	"type",
+	"uncheck",
+	"upload",
+]);
+
 function getStaleRefArgs(commandTokens: string[], stdin?: string): string[] {
 	if (commandTokens[0] !== "batch" || stdin === undefined) {
 		return commandTokens;
@@ -1238,6 +2339,101 @@ function getStaleRefArgs(commandTokens: string[], stdin?: string): string[] {
 	return parsed.steps.flatMap((step) => step);
 }
 
+function collectRefsFromTokens(tokens: string[]): string[] {
+	return tokens.filter((token) => /^@e\d+\b/.test(token)).map((token) => token.slice(1));
+}
+
+function getGuardedRefUsage(commandTokens: string[], stdin?: string): string[] {
+	const collectFromStep = (step: string[]) => REF_GUARDED_COMMANDS.has(step[0] ?? "") ? collectRefsFromTokens(step) : [];
+	if (commandTokens[0] !== "batch" || stdin === undefined) {
+		return collectFromStep(commandTokens);
+	}
+	const parsed = parseUserBatchStdin(stdin);
+	if (parsed.error || parsed.steps === undefined) {
+		return collectFromStep(commandTokens);
+	}
+	const refsBeforeInBatchSnapshot: string[] = [];
+	for (const step of parsed.steps) {
+		if ((step[0] ?? "") === "snapshot") break;
+		refsBeforeInBatchSnapshot.push(...collectFromStep(step));
+	}
+	return refsBeforeInBatchSnapshot;
+}
+
+function targetsMatch(left: SessionTabTarget | undefined, right: SessionTabTarget | undefined): boolean {
+	if (!left || !right) return true;
+	return normalizeComparableUrl(left.url) === normalizeComparableUrl(right.url);
+}
+
+function getBatchRefInvalidationMessage(commandTokens: string[], stdin?: string): string | undefined {
+	if (commandTokens[0] !== "batch" || stdin === undefined) return undefined;
+	const parsed = parseUserBatchStdin(stdin);
+	if (parsed.error || parsed.steps === undefined) return undefined;
+	let priorStepInvalidatesRefs = false;
+	for (const step of parsed.steps) {
+		if ((step[0] ?? "") === "snapshot") {
+			priorStepInvalidatesRefs = false;
+		}
+		const refIds = collectRefsFromTokens(step);
+		if (refIds.length > 0 && REF_GUARDED_COMMANDS.has(step[0] ?? "") && priorStepInvalidatesRefs) {
+			return `Batch step ${step[0]} uses page-scoped ref ${refIds.map((refId) => `@${refId}`).join(", ")} after an earlier batch step can navigate or mutate the page. Split the batch, run snapshot -i after the page-changing step, then retry with current refs.`;
+		}
+		if (REF_INVALIDATING_BATCH_COMMANDS.has(step[0] ?? "")) {
+			priorStepInvalidatesRefs = true;
+		}
+	}
+	return undefined;
+}
+
+function buildStaleRefPreflight(options: {
+	commandTokens: string[];
+	currentTarget?: SessionTabTarget;
+	refSnapshot?: SessionRefSnapshot;
+	stdin?: string;
+}): StaleRefPreflight | undefined {
+	const usedRefIds = [...new Set(getGuardedRefUsage(options.commandTokens, options.stdin))];
+	const batchInvalidationMessage = getBatchRefInvalidationMessage(options.commandTokens, options.stdin);
+	if (batchInvalidationMessage && usedRefIds.length > 0) {
+		return {
+			message: batchInvalidationMessage,
+			refIds: usedRefIds,
+			snapshot: options.refSnapshot,
+		};
+	}
+	if (usedRefIds.length === 0 || !options.refSnapshot) return undefined;
+	if (!targetsMatch(options.refSnapshot.target, options.currentTarget)) {
+		return {
+			message: `Ref ${usedRefIds.map((refId) => `@${refId}`).join(", ")} came from a snapshot for ${options.refSnapshot.target?.url ?? "a prior page"}, but the current session target is ${options.currentTarget?.url ?? "unknown"}. Run snapshot -i again before using page-scoped refs.`,
+			refIds: usedRefIds,
+			snapshot: options.refSnapshot,
+		};
+	}
+	const knownRefs = new Set(options.refSnapshot.refIds);
+	const missingRefs = usedRefIds.filter((refId) => !knownRefs.has(refId));
+	if (missingRefs.length > 0) {
+		return {
+			message: `Ref ${missingRefs.map((refId) => `@${refId}`).join(", ")} was not present in the latest snapshot for this session. Run snapshot -i again before using page-scoped refs.`,
+			refIds: missingRefs,
+			snapshot: options.refSnapshot,
+		};
+	}
+	return undefined;
+}
+
+function sessionPrefixArgs(sessionName: string | undefined, args: string[]): string[] {
+	return sessionName && args[0] !== "--session" ? ["--session", sessionName, ...args] : args;
+}
+
+function sessionAwareStaleRefNextActions(sessionName: string | undefined): AgentBrowserNextAction[] {
+	return (buildAgentBrowserNextActions({ failureCategory: "stale-ref", resultCategory: "failure" }) ?? []).map((action) => {
+		const actionArgs = action.params?.args;
+		return {
+			...action,
+			params: action.params && actionArgs ? { ...action.params, args: sessionPrefixArgs(sessionName, actionArgs) } : action.params,
+		};
+	});
+}
+
 function buildPinnedBatchPlan(options: {
 	command?: string;
 	commandTokens: string[];
@@ -1371,14 +2567,16 @@ async function runSessionCommandData(options: {
 	cwd: string;
 	sessionName?: string;
 	signal?: AbortSignal;
+	stdin?: string;
 }): Promise<unknown | undefined> {
-	const { args, cwd, sessionName, signal } = options;
+	const { args, cwd, sessionName, signal, stdin } = options;
 	if (!sessionName) return undefined;
 
 	const processResult = await runAgentBrowserProcess({
 		args: ["--json", "--session", sessionName, ...args],
 		cwd,
 		signal,
+		stdin,
 	});
 	try {
 		if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0) {
@@ -1424,6 +2622,401 @@ function mergeNavigationSummaryIntoData(data: unknown, navigationSummary: Naviga
 	return { navigationSummary, result: data };
 }
 
+function getSnapshotRefRecord(data: unknown): Record<string, unknown> | undefined {
+	return isRecord(data) && isRecord(data.refs) ? data.refs : undefined;
+}
+
+const OVERLAY_CLOSE_NAME_PATTERN = /(?:\b(?:close|dismiss|no thanks|not now|maybe later|hide|skip|continue without|x)\b|^\s*×\s*$)/i;
+const OVERLAY_CONTEXT_NAME_PATTERN = /\b(?:banner|modal|dialog|popup|pop-up|overlay|donat(?:e|ion)|subscribe|sign in|login|cookie|privacy|consent)\b/i;
+const OVERLAY_CONTEXT_ROLES = new Set(["alertdialog", "dialog"]);
+const OVERLAY_ACTION_ROLES = new Set(["button", "link", "menuitem"]);
+const OVERLAY_BLOCKER_CANDIDATE_LIMIT = 3;
+
+function getOverlayBlockerCandidates(snapshotData: unknown): OverlayBlockerCandidate[] {
+	const refs = getSnapshotRefRecord(snapshotData);
+	if (!refs) return [];
+	const hasOverlayContext = Object.values(refs).some((entry) => {
+		if (!isRecord(entry)) return false;
+		const role = typeof entry.role === "string" ? entry.role : "";
+		const name = typeof entry.name === "string" ? entry.name : "";
+		return OVERLAY_CONTEXT_ROLES.has(role.toLowerCase()) || OVERLAY_CONTEXT_NAME_PATTERN.test(name);
+	});
+	if (!hasOverlayContext) return [];
+	const candidates: OverlayBlockerCandidate[] = [];
+	for (const [ref, entry] of Object.entries(refs)) {
+		if (!/^e\d+$/.test(ref) || !isRecord(entry)) continue;
+		const role = typeof entry.role === "string" ? entry.role : undefined;
+		const name = typeof entry.name === "string" ? entry.name : undefined;
+		if (!role || !OVERLAY_ACTION_ROLES.has(role.toLowerCase()) || !name || !OVERLAY_CLOSE_NAME_PATTERN.test(name)) continue;
+		candidates.push({
+			args: ["click", `@${ref}`],
+			name,
+			reason: `Visible ${role} ${JSON.stringify(name)} appears in a snapshot that also contains overlay/banner/dialog context.`,
+			ref: `@${ref}`,
+			role,
+		});
+		if (candidates.length >= OVERLAY_BLOCKER_CANDIDATE_LIMIT) break;
+	}
+	return candidates;
+}
+
+function formatOverlayBlockerText(diagnostic: OverlayBlockerDiagnostic): string {
+	return [
+		"Possible overlay blockers:",
+		...diagnostic.candidates.map((candidate) => `- ${candidate.ref}${candidate.role ? ` ${candidate.role}` : ""}${candidate.name ? ` ${JSON.stringify(candidate.name)}` : ""}: ${candidate.reason}`),
+	].join("\n");
+}
+
+function buildOverlayBlockerNextActions(options: { diagnostic: OverlayBlockerDiagnostic; sessionName?: string }): AgentBrowserNextAction[] {
+	return [
+		{
+			id: "inspect-overlay-state",
+			params: { args: sessionPrefixArgs(options.sessionName, ["snapshot", "-i"]) },
+			reason: "Refresh interactive refs and inspect whether an overlay, banner, modal, or dialog is blocking the intended click.",
+			safety: "Read-only inspection; use current refs from this snapshot before interacting.",
+			tool: "agent_browser" as const,
+		},
+		...options.diagnostic.candidates.map((candidate, index) => ({
+			id: `try-overlay-blocker-candidate-${index + 1}`,
+			params: { args: sessionPrefixArgs(options.sessionName, candidate.args) },
+			reason: candidate.reason,
+			safety: "Only click this if the candidate is clearly a close/dismiss control for an overlay that blocks the intended workflow.",
+			tool: "agent_browser" as const,
+		})),
+	];
+}
+
+function buildVisibleTextProbeScript(selector: string): string {
+	return `(() => {\n  const selector = ${JSON.stringify(selector)};\n  const isVisible = (element) => {\n    const style = window.getComputedStyle(element);\n    if (!style || style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse' || Number(style.opacity) === 0) return false;\n    return Array.from(element.getClientRects()).some((rect) => rect.width > 0 && rect.height > 0);\n  };\n  let matches = [];\n  try {\n    matches = Array.from(document.querySelectorAll(selector));\n  } catch (error) {\n    return JSON.stringify({ selector, error: error instanceof Error ? error.message : String(error) });\n  }\n  const visible = matches.filter(isVisible);\n  const trim = (value) => typeof value === 'string' ? value.trim().replace(/\\s+/g, ' ').slice(0, 200) : undefined;\n  return JSON.stringify({\n    selector,\n    matchCount: matches.length,\n    visibleCount: visible.length,\n    firstMatchVisible: matches[0] ? isVisible(matches[0]) : undefined,\n    firstTextPreview: trim(matches[0]?.textContent),\n    firstVisibleTextPreview: trim(visible[0]?.textContent),\n  });\n})()`;
+}
+
+function parseSelectorTextVisibilityProbe(data: unknown, selector: string): Omit<SelectorTextVisibilityDiagnostic, "summary"> | undefined {
+	const result = extractStringResultField(data, "result");
+	if (!result) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(result);
+	} catch {
+		return undefined;
+	}
+	if (!isRecord(parsed) || typeof parsed.error === "string") return undefined;
+	const matchCount = typeof parsed.matchCount === "number" ? parsed.matchCount : undefined;
+	const visibleCount = typeof parsed.visibleCount === "number" ? parsed.visibleCount : undefined;
+	if (matchCount === undefined || visibleCount === undefined) return undefined;
+	return {
+		firstMatchVisible: typeof parsed.firstMatchVisible === "boolean" ? parsed.firstMatchVisible : undefined,
+		firstVisibleTextPreview: typeof parsed.firstVisibleTextPreview === "string" && parsed.firstVisibleTextPreview.length > 0 ? redactSensitiveText(parsed.firstVisibleTextPreview) : undefined,
+		matchCount,
+		selector,
+		visibleCount,
+	};
+}
+
+function selectorMayExposeSensitiveLiteral(selector: string): boolean {
+	return redactSensitiveText(selector) !== selector || /\[[^\]]*[~|^$*]?=\s*(?:"[^"]*"|'[^']*'|[^\]\s]+)\s*(?:[is]\s*)?\]/.test(selector);
+}
+
+async function collectSelectorTextVisibilityDiagnosticForSelector(options: {
+	cwd: string;
+	selector: string | undefined;
+	sessionName?: string;
+	signal?: AbortSignal;
+}): Promise<SelectorTextVisibilityDiagnostic | undefined> {
+	const { selector } = options;
+	if (!selector || /^@e\d+$/.test(selector) || selectorMayExposeSensitiveLiteral(selector)) return undefined;
+	const probe = await runSessionCommandData({
+		args: ["eval", "--stdin"],
+		cwd: options.cwd,
+		sessionName: options.sessionName,
+		signal: options.signal,
+		stdin: buildVisibleTextProbeScript(selector),
+	});
+	const parsed = parseSelectorTextVisibilityProbe(probe, selector);
+	if (!parsed || parsed.matchCount <= 1 && parsed.firstMatchVisible !== false) return undefined;
+	if (parsed.visibleCount === 0) return undefined;
+	const visibleMatchNoun = `visible match${parsed.visibleCount === 1 ? "" : "es"}`;
+	const visibleMatchVerb = parsed.visibleCount === 1 ? "exists" : "exist";
+	const summary = parsed.firstMatchVisible === false
+		? `Selector ${JSON.stringify(selector)} matched ${parsed.matchCount} elements; the first match is hidden while ${parsed.visibleCount} ${visibleMatchNoun} ${visibleMatchVerb}.`
+		: `Selector ${JSON.stringify(selector)} matched ${parsed.matchCount} elements; get text reads the first upstream match, which may not be the intended visible tab/panel.`;
+	return { ...parsed, summary };
+}
+
+function getBatchGetTextSelectors(data: unknown): string[] {
+	if (!Array.isArray(data)) return [];
+	return data.flatMap((item) => {
+		if (!isRecord(item) || item.success === false) return [];
+		const [command, subcommand, selector] = extractBatchResultCommand(item);
+		return command === "get" && subcommand === "text" && selector ? [selector] : [];
+	});
+}
+
+async function collectSelectorTextVisibilityDiagnostics(options: {
+	commandInfo: CommandInfo;
+	commandTokens: string[];
+	cwd: string;
+	data: unknown;
+	sessionName?: string;
+	signal?: AbortSignal;
+}): Promise<SelectorTextVisibilityDiagnostic[]> {
+	const selectors = options.commandInfo.command === "get" && options.commandInfo.subcommand === "text"
+		? [options.commandTokens[2]]
+		: options.commandInfo.command === "batch"
+			? getBatchGetTextSelectors(options.data)
+			: [];
+	const diagnostics: SelectorTextVisibilityDiagnostic[] = [];
+	for (const selector of selectors) {
+		const diagnostic = await collectSelectorTextVisibilityDiagnosticForSelector({
+			cwd: options.cwd,
+			selector,
+			sessionName: options.sessionName,
+			signal: options.signal,
+		});
+		if (diagnostic) diagnostics.push(diagnostic);
+	}
+	return diagnostics.sort((left, right) => Number(right.firstMatchVisible === false) - Number(left.firstMatchVisible === false));
+}
+
+function formatSelectorTextVisibilityText(diagnostics: SelectorTextVisibilityDiagnostic[]): string | undefined {
+	if (diagnostics.length === 0) return undefined;
+	return diagnostics.flatMap((diagnostic) => {
+		const lines = [`Selector text visibility warning: ${diagnostic.summary}`];
+		if (diagnostic.firstVisibleTextPreview) lines.push(`First visible text preview: ${JSON.stringify(diagnostic.firstVisibleTextPreview)}`);
+		return lines;
+	}).join("\n");
+}
+
+function looksLikeFunctionEvalStdin(stdin: string | undefined): boolean {
+	const trimmed = stdin?.trim();
+	if (!trimmed) return false;
+	return /^(?:async\s+)?function\b/.test(trimmed) || /^(?:async\s*)?\([^)]*\)\s*=>/.test(trimmed) || /^(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(trimmed);
+}
+
+function isEmptyRecord(value: unknown): boolean {
+	return isRecord(value) && Object.keys(value).length === 0;
+}
+
+function getEvalStdinHint(options: { command?: string; data: unknown; stdin?: string }): EvalStdinHint | undefined {
+	if (options.command !== "eval" || !looksLikeFunctionEvalStdin(options.stdin) || !isRecord(options.data)) return undefined;
+	const result = options.data.result;
+	if (!isEmptyRecord(result)) return undefined;
+	return {
+		reason: "eval --stdin received a function-shaped snippet and the upstream JSON result was an empty object, which often means the function itself was returned or serialized instead of invoked.",
+		suggestion: "Pass a plain expression such as `({ title: document.title })`, or invoke the function explicitly, for example `(() => ({ title: document.title }))()`.",
+	};
+}
+
+function formatEvalStdinHintText(hint: EvalStdinHint | undefined): string | undefined {
+	return hint ? `Eval stdin hint: ${hint.reason} ${hint.suggestion}` : undefined;
+}
+
+function getArtifactCleanupGuidance(options: { command?: string; manifest?: SessionArtifactManifest; succeeded: boolean }): ArtifactCleanupGuidance | undefined {
+	if (!options.succeeded || options.command !== "close" || !options.manifest || options.manifest.entries.length === 0) return undefined;
+	const explicitArtifactPaths = options.manifest.entries
+		.filter((entry) => entry.storageScope === "explicit-path")
+		.map((entry) => entry.path)
+		.filter((path, index, paths) => paths.indexOf(path) === index)
+		.slice(0, 10);
+	return {
+		explicitArtifactPaths,
+		note: "Closing the browser session does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; clean those paths with host file tools when no longer needed.",
+		owner: "host-file-tools",
+		summary: formatSessionArtifactRetentionSummary(options.manifest),
+	};
+}
+
+function formatArtifactCleanupGuidanceText(guidance: ArtifactCleanupGuidance | undefined): string | undefined {
+	if (!guidance) return undefined;
+	const lines = [
+		"Artifact lifecycle:",
+		`- ${guidance.summary}`,
+		`- ${guidance.note}`,
+	];
+	if (guidance.explicitArtifactPaths.length > 0) {
+		lines.push(`- Explicit artifact paths to review: ${guidance.explicitArtifactPaths.join(", ")}`);
+	}
+	return lines.join("\n");
+}
+
+function buildSelectorTextVisibilityNextActions(options: { diagnostics: SelectorTextVisibilityDiagnostic[]; sessionName?: string }): AgentBrowserNextAction[] {
+	return options.diagnostics.map((diagnostic, index) => ({
+		id: index === 0 ? "inspect-visible-text-candidates" : `inspect-visible-text-candidates-${index + 1}`,
+		params: {
+			args: sessionPrefixArgs(options.sessionName, ["eval", "--stdin"]),
+			stdin: buildVisibleTextProbeScript(diagnostic.selector),
+		},
+		reason: "Inspect selector match count and visible text before trusting get text on tabbed or hidden DOM content.",
+		safety: "Read-only DOM inspection; use a more specific visible selector or current @ref before acting on hidden-tab text.",
+		tool: "agent_browser" as const,
+	}));
+}
+
+function getTimeoutProgressSteps(compiledJob: CompiledAgentBrowserJob | undefined, command: string | undefined, stdin: string | undefined): Array<{ args: string[]; index: number }> {
+	if (compiledJob) return compiledJob.steps.map((step, index) => ({ args: step.args, index: index + 1 }));
+	if (command !== "batch" || !stdin) return [];
+	try {
+		const parsed = JSON.parse(stdin) as unknown;
+		if (!Array.isArray(parsed)) return [];
+		return parsed.flatMap((step, index) => Array.isArray(step) && step.every((token) => typeof token === "string") ? [{ args: step as string[], index: index + 1 }] : []);
+	} catch {
+		return [];
+	}
+}
+
+function getLastPositionalToken(args: string[], startIndex = 1): string | undefined {
+	for (let index = args.length - 1; index >= startIndex; index -= 1) {
+		const token = args[index];
+		if (token && !token.startsWith("-")) return token;
+	}
+	return undefined;
+}
+
+function getTimeoutStepArtifactPath(args: string[]): string | undefined {
+	const [command] = args;
+	if (command === "screenshot") {
+		const index = getScreenshotPathTokenIndex(args);
+		return index === undefined ? undefined : args[index];
+	}
+	if (command === "pdf") return getLastPositionalToken(args);
+	if (command === "download") return getLastPositionalToken(args, 2);
+	if (command === "wait") {
+		const inlineDownload = args.find((token) => token.startsWith("--download="));
+		if (inlineDownload) return inlineDownload.slice("--download=".length) || undefined;
+		const downloadIndex = args.indexOf("--download");
+		const downloadPath = downloadIndex >= 0 ? args[downloadIndex + 1] : undefined;
+		if (downloadPath && !downloadPath.startsWith("-")) return downloadPath;
+	}
+	return undefined;
+}
+
+async function collectTimeoutArtifactEvidence(cwd: string, steps: Array<{ args: string[]; index: number }>): Promise<TimeoutArtifactEvidence[]> {
+	const evidence: TimeoutArtifactEvidence[] = [];
+	for (const step of steps) {
+		const path = getTimeoutStepArtifactPath(step.args);
+		if (!path) continue;
+		const absolutePath = isAbsolute(path) ? path : resolve(cwd, path);
+		try {
+			const stats = await stat(absolutePath);
+			evidence.push({ absolutePath, exists: true, path, sizeBytes: stats.size, stepIndex: step.index });
+		} catch {
+			evidence.push({ absolutePath, exists: false, path, stepIndex: step.index });
+		}
+	}
+	return evidence;
+}
+
+function getPlannedCurrentPageUrl(steps: Array<{ args: string[]; index: number }>): string | undefined {
+	for (let index = steps.length - 1; index >= 0; index -= 1) {
+		const args = steps[index]?.args ?? [];
+		if (args[0] === "open" || args[0] === "navigate" || args[0] === "pushstate") {
+			return getLastPositionalToken(args);
+		}
+	}
+	return undefined;
+}
+
+async function collectTimeoutPartialProgress(options: {
+	command?: string;
+	compiledJob?: CompiledAgentBrowserJob;
+	cwd: string;
+	sessionName?: string;
+	stdin?: string;
+}): Promise<TimeoutPartialProgress | undefined> {
+	const steps = getTimeoutProgressSteps(options.compiledJob, options.command, options.stdin);
+	const artifacts = await collectTimeoutArtifactEvidence(options.cwd, steps);
+	const [urlData, titleData] = await Promise.all([
+		runSessionCommandData({ args: ["get", "url"], cwd: options.cwd, sessionName: options.sessionName }),
+		runSessionCommandData({ args: ["get", "title"], cwd: options.cwd, sessionName: options.sessionName }),
+	]);
+	const recoveredUrl = extractStringResultField(urlData, "result") ?? extractStringResultField(urlData, "url");
+	const title = extractStringResultField(titleData, "result") ?? extractStringResultField(titleData, "title");
+	const plannedUrl = recoveredUrl ? undefined : getPlannedCurrentPageUrl(steps);
+	const url = recoveredUrl ?? plannedUrl;
+	if (steps.length === 0 && artifacts.length === 0 && !url && !title) return undefined;
+	const foundArtifacts = artifacts.filter((artifact) => artifact.exists).length;
+	const pageStateSummary = recoveredUrl || title ? " and current page state" : plannedUrl ? " and planned page URL" : "";
+	return {
+		artifacts,
+		currentPage: url || title ? { title, url } : undefined,
+		steps: steps.length > 0 ? steps : undefined,
+		summary: `Timed out before upstream returned final results; recovered ${foundArtifacts}/${artifacts.length} declared artifact path${artifacts.length === 1 ? "" : "s"}${pageStateSummary}.`,
+	};
+}
+
+function redactSensitivePathSegmentsForDiagnostic(path: string): string {
+	return path.split(/([/\\]+)/).map((segment) => {
+		if (segment === "/" || segment === "\\" || /^[/\\]+$/.test(segment)) return segment;
+		return redactSensitiveText(segment) !== segment || /(?:secret|token|password|passwd|credential|auth|api[-_]?key|bearer)/i.test(segment) ? "[REDACTED]" : segment;
+	}).join("");
+}
+
+function sanitizeCurrentPageUrlForTimeoutDiagnostic(url: string): string {
+	try {
+		const parsedUrl = new URL(url);
+		parsedUrl.pathname = parsedUrl.pathname.split("/").map((segment) => redactSensitivePathSegmentsForDiagnostic(segment)).join("/");
+		for (const [key, value] of parsedUrl.searchParams.entries()) {
+			if (redactSensitiveText(key) !== key || redactSensitiveText(value) !== value || /(?:secret|token|password|passwd|credential|auth|api[-_]?key|bearer)/i.test(`${key} ${value}`)) {
+				parsedUrl.searchParams.set(key, "[REDACTED]");
+			}
+		}
+		if (parsedUrl.hash) {
+			parsedUrl.hash = redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(parsedUrl.hash));
+		}
+		return redactSensitiveText(parsedUrl.toString());
+	} catch {
+		return redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(url));
+	}
+}
+
+function formatTimeoutPartialProgressText(progress: TimeoutPartialProgress): string {
+	const lines = [`Timeout partial progress: ${progress.summary}`];
+	const currentPageTitle = progress.currentPage?.title ? redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(progress.currentPage.title)) : undefined;
+	const currentPageUrl = progress.currentPage?.url ? sanitizeCurrentPageUrlForTimeoutDiagnostic(progress.currentPage.url) : undefined;
+	if (currentPageTitle || currentPageUrl) {
+		lines.push(`Current page: ${[currentPageTitle, currentPageUrl].filter(Boolean).join(" — ")}`);
+	}
+	if (progress.steps && progress.steps.length > 0) {
+		const shownSteps = progress.steps.slice(0, 6);
+		lines.push("Planned steps:");
+		for (const step of shownSteps) {
+			const command = redactSensitivePathSegmentsForDiagnostic(redactInvocationArgs(step.args).join(" "));
+			lines.push(`- Step ${step.index}: ${command}`);
+		}
+		if (progress.steps.length > shownSteps.length) {
+			lines.push(`- ... ${progress.steps.length - shownSteps.length} more step${progress.steps.length - shownSteps.length === 1 ? "" : "s"} omitted`);
+		}
+	}
+	for (const artifact of progress.artifacts) {
+		const path = redactSensitivePathSegmentsForDiagnostic(artifact.path);
+		lines.push(`Artifact from step ${artifact.stepIndex}: ${path} (${artifact.exists ? `exists${typeof artifact.sizeBytes === "number" ? `, ${artifact.sizeBytes} bytes` : ""}` : "missing"})`);
+	}
+	return lines.join("\n");
+}
+
+async function collectOverlayBlockerDiagnostic(options: {
+	command?: string;
+	cwd: string;
+	data: unknown;
+	navigationSummary?: NavigationSummary;
+	priorTarget?: SessionTabTarget;
+	sessionName?: string;
+	signal?: AbortSignal;
+}): Promise<OverlayBlockerDiagnostic | undefined> {
+	if (options.command !== "click" || !isRecord(options.data) || typeof options.data.clicked !== "string") return undefined;
+	const priorUrl = normalizeComparableUrl(options.priorTarget?.url);
+	const currentUrl = normalizeComparableUrl(options.navigationSummary?.url);
+	if (!priorUrl || !currentUrl || priorUrl !== currentUrl) return undefined;
+	const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal });
+	const candidates = getOverlayBlockerCandidates(snapshotData);
+	const snapshot = extractRefSnapshotFromData(snapshotData);
+	if (candidates.length === 0 || !snapshot) return undefined;
+	return {
+		candidates,
+		snapshot,
+		summary: `Click completed but the page stayed on ${currentUrl}; a fresh snapshot contains likely overlay close/dismiss controls.`,
+	};
+}
+
 async function collectOpenResultTabCorrection(options: {
 	cwd: string;
 	sessionName?: string;
@@ -1489,6 +3082,68 @@ function buildSessionDetailFields(sessionName: string | undefined, usedImplicitS
 	return sessionName ? { sessionName, usedImplicitSession } : {};
 }
 
+function buildManagedSessionOutcome(options: {
+	activeAfter: boolean;
+	activeBefore: boolean;
+	attemptedSessionName?: string;
+	command?: string;
+	currentSessionName: string;
+	previousSessionName: string;
+	replacedSessionName?: string;
+	sessionMode: "auto" | "fresh";
+	succeeded: boolean;
+}): ManagedSessionOutcome | undefined {
+	const { activeAfter, activeBefore, attemptedSessionName, command, currentSessionName, previousSessionName, replacedSessionName, sessionMode, succeeded } = options;
+	if (!attemptedSessionName) return undefined;
+	let status: ManagedSessionOutcome["status"];
+	let summary: string;
+	if (command === "close") {
+		status = succeeded ? "closed" : activeBefore ? "preserved" : "abandoned";
+		summary = succeeded
+			? `Managed session ${attemptedSessionName} was closed.`
+			: activeBefore
+				? `Managed session close failed; previous managed session ${previousSessionName} remains current.`
+				: `Managed session close failed; no managed session is active.`;
+	} else if (succeeded) {
+		if (replacedSessionName) {
+			status = "replaced";
+			summary = `Managed session ${replacedSessionName} was replaced by ${currentSessionName}.`;
+		} else if (!activeBefore && activeAfter) {
+			status = "created";
+			summary = `Managed session ${currentSessionName} is now current.`;
+		} else {
+			status = "unchanged";
+			summary = `Managed session ${currentSessionName} remains current.`;
+		}
+	} else if (activeBefore) {
+		status = "preserved";
+		summary = sessionMode === "fresh" && attemptedSessionName !== previousSessionName
+			? `Fresh managed session ${attemptedSessionName} failed before becoming current; previous managed session ${previousSessionName} was preserved.`
+			: `Managed session call failed; previous managed session ${previousSessionName} was preserved.`;
+	} else {
+		status = "abandoned";
+		summary = sessionMode === "fresh"
+			? `Fresh managed session ${attemptedSessionName} failed before becoming current; no previous managed session was active, so no managed session is current.`
+			: `Managed session call failed before any managed session became current.`;
+	}
+	return {
+		activeAfter,
+		activeBefore,
+		attemptedSessionName,
+		currentSessionName,
+		previousSessionName,
+		replacedSessionName,
+		sessionMode,
+		status,
+		succeeded,
+		summary,
+	};
+}
+
+function formatManagedSessionOutcomeText(outcome: ManagedSessionOutcome | undefined): string | undefined {
+	return outcome && !outcome.succeeded && outcome.sessionMode === "fresh" ? `Managed session outcome: ${outcome.summary}` : undefined;
+}
+
 function getPersistentSessionArtifactStore(ctx: {
 	sessionManager: {
 		getSessionDir?: () => string;
@@ -1640,6 +3295,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 	let managedSessionCwd = process.cwd();
 	let freshSessionOrdinal = 0;
 	let sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
+	let sessionRefSnapshots = new Map<string, OrderedSessionRefSnapshot>();
 	let sessionTabTargetUpdateOrder = 0;
 	let traceOwners = new Map<string, TraceOwner>();
 	let artifactManifest: SessionArtifactManifest | undefined;
@@ -1653,7 +3309,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		managedSessionCwd = ctx.cwd;
 		freshSessionOrdinal = restoredState.freshSessionOrdinal;
 		sessionTabTargets = restoreSessionTabTargetsFromBranch(ctx.sessionManager.getBranch());
-		sessionTabTargetUpdateOrder = getLatestSessionTabTargetOrder(sessionTabTargets);
+		sessionRefSnapshots = restoreSessionRefSnapshotsFromBranch(ctx.sessionManager.getBranch());
+		sessionTabTargetUpdateOrder = Math.max(getLatestSessionTabTargetOrder(sessionTabTargets), getLatestSessionTabTargetOrder(sessionRefSnapshots));
 		artifactManifest = restoreArtifactManifestFromBranch(ctx.sessionManager.getBranch());
 	});
 
@@ -1670,6 +3327,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		}
 		managedSessionActive = false;
 		sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
+		sessionRefSnapshots = new Map<string, OrderedSessionRefSnapshot>();
 		sessionTabTargetUpdateOrder = 0;
 		traceOwners = new Map<string, TraceOwner>();
 		artifactManifest = undefined;
@@ -1723,17 +3381,77 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			return component;
 		},
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const redactedArgs = redactInvocationArgs(params.args);
-			const validationError = validateToolArgs(params.args) ?? getBatchAnnotateValidationError(params.args, params.stdin);
+			const semanticActionResult = params.semanticAction === undefined ? {} : compileAgentBrowserSemanticAction(params.semanticAction);
+			const jobResult = params.job === undefined ? {} : compileAgentBrowserJob(params.job);
+			const qaResult = params.qa === undefined ? {} : compileAgentBrowserQaPreset(params.qa);
+			const sourceLookupResult = params.sourceLookup === undefined ? {} : compileAgentBrowserSourceLookup(params.sourceLookup);
+			const networkSourceLookupResult = params.networkSourceLookup === undefined ? {} : compileAgentBrowserNetworkSourceLookup(params.networkSourceLookup);
+			const hasExplicitArgs = Array.isArray(params.args);
+			const explicitInputModes = [hasExplicitArgs, Boolean(semanticActionResult.compiled), Boolean(jobResult.compiled), Boolean(qaResult.compiled), Boolean(sourceLookupResult.compiled), Boolean(networkSourceLookupResult.compiled)].filter(Boolean).length;
+			const semanticActionError = semanticActionResult.error;
+			const jobError = jobResult.error;
+			const qaError = qaResult.error;
+			const sourceLookupError = sourceLookupResult.error;
+			const networkSourceLookupError = networkSourceLookupResult.error;
+			const inputModeError = explicitInputModes !== 1
+				? "Provide exactly one of args, semanticAction, job, qa, sourceLookup, or networkSourceLookup."
+				: undefined;
+			const compiledSemanticAction = semanticActionResult.compiled;
+			const compiledQaPreset = qaResult.compiled;
+			const compiledSourceLookup = sourceLookupResult.compiled;
+			const compiledNetworkSourceLookup = networkSourceLookupResult.compiled;
+			const compiledJob = jobResult.compiled ?? compiledQaPreset;
+			const compiledGeneratedBatch = compiledNetworkSourceLookup ?? compiledSourceLookup ?? compiledJob;
+			const toolArgs = compiledSemanticAction?.args ?? compiledGeneratedBatch?.args ?? params.args ?? [];
+			const toolStdin = compiledGeneratedBatch?.stdin ?? params.stdin;
+			const redactedArgs = redactInvocationArgs(toolArgs);
+			const generatedStdinError = compiledGeneratedBatch && params.stdin !== undefined ? "Do not provide stdin with job, qa, sourceLookup, or networkSourceLookup; those modes generate their own batch stdin." : undefined;
+			const validationError = semanticActionError ?? jobError ?? qaError ?? sourceLookupError ?? networkSourceLookupError ?? inputModeError ?? generatedStdinError ?? validateToolArgs(toolArgs) ?? getBatchAnnotateValidationError(toolArgs, toolStdin);
+			const redactedCompiledSemanticAction = compiledSemanticAction
+				? { ...compiledSemanticAction, args: redactInvocationArgs(compiledSemanticAction.args) }
+				: undefined;
+			const redactedCompiledJobSteps = compiledJob?.steps.map((step) => ({ ...step, args: redactInvocationArgs(step.args) }));
+			const redactedCompiledJob = compiledJob && redactedCompiledJobSteps
+				? { ...compiledJob, stdin: JSON.stringify(redactedCompiledJobSteps.map((step) => step.args)), steps: redactedCompiledJobSteps }
+				: undefined;
+			const redactedCompiledQaPreset = compiledQaPreset && redactedCompiledJob
+				? { ...redactedCompiledJob, checks: compiledQaPreset.checks }
+				: undefined;
+			const redactedCompiledSourceLookupSteps = compiledSourceLookup?.steps.map((step) => ({ ...step, args: redactInvocationArgs(step.args) }));
+			const redactedCompiledSourceLookup = compiledSourceLookup && redactedCompiledSourceLookupSteps
+				? { ...compiledSourceLookup, stdin: JSON.stringify(redactedCompiledSourceLookupSteps.map((step) => step.args)), steps: redactedCompiledSourceLookupSteps }
+				: undefined;
+			const redactedCompiledNetworkSourceLookupSteps = compiledNetworkSourceLookup?.steps.map((step) => ({ ...step, args: redactNetworkSourceLookupArgs(step.args) }));
+			const redactedCompiledNetworkSourceLookup = compiledNetworkSourceLookup && redactedCompiledNetworkSourceLookupSteps
+				? {
+					...compiledNetworkSourceLookup,
+					query: {
+						...compiledNetworkSourceLookup.query,
+						filter: redactNetworkSourceLookupUrl(compiledNetworkSourceLookup.query.filter),
+						url: redactNetworkSourceLookupUrl(compiledNetworkSourceLookup.query.url),
+					},
+					stdin: JSON.stringify(redactedCompiledNetworkSourceLookupSteps.map((step) => step.args)),
+					steps: redactedCompiledNetworkSourceLookupSteps,
+				}
+				: undefined;
 			if (validationError) {
 				return {
 					content: [{ type: "text", text: validationError }],
-					details: { args: redactedArgs, validationError },
+					details: {
+						args: redactedArgs,
+						compiledJob: redactedCompiledJob,
+						compiledQaPreset: redactedCompiledQaPreset,
+						compiledSourceLookup: redactedCompiledSourceLookup,
+						compiledNetworkSourceLookup: redactedCompiledNetworkSourceLookup,
+						compiledSemanticAction: redactedCompiledSemanticAction,
+						...buildAgentBrowserResultCategoryDetails({ args: redactedArgs, errorText: validationError, succeeded: false, validationError }),
+						validationError,
+					},
 					isError: true,
 				};
 			}
-			const preparedArgs = await prepareAgentBrowserArgs(params.args, params.stdin, ctx.cwd);
-			const userRequestedJson = params.args.includes("--json");
+			const preparedArgs = await prepareAgentBrowserArgs(toolArgs, toolStdin, ctx.cwd);
+			const userRequestedJson = toolArgs.includes("--json");
 
 			const tabTargetUpdateOrder = ++sessionTabTargetUpdateOrder;
 			const runTool = async (): Promise<AgentBrowserToolResult> => {
@@ -1757,10 +3475,15 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						content: [{ type: "text", text: executionPlan.validationError }],
 						details: {
 							args: redactedArgs,
+							compiledJob: redactedCompiledJob,
+							compiledQaPreset: redactedCompiledQaPreset,
+							compiledSourceLookup: redactedCompiledSourceLookup,
+							compiledNetworkSourceLookup: redactedCompiledNetworkSourceLookup,
 							invalidValueFlag: executionPlan.invalidValueFlag,
 							sessionMode,
 							sessionRecoveryHint: redactedRecoveryHint,
 							startupScopedFlags: executionPlan.startupScopedFlags,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedArgs, command: executionPlan.commandInfo.command, errorText: executionPlan.validationError, succeeded: false, validationError: executionPlan.validationError }),
 							validationError: executionPlan.validationError,
 						},
 						isError: true,
@@ -1771,7 +3494,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				const exactSensitiveValues = getExactSensitiveStdinValues({
 					command: executionPlan.commandInfo.command,
 					commandTokens,
-					stdin: params.stdin,
+					stdin: toolStdin,
 				});
 				const traceOwnerGuardMessage = getTraceOwnerGuardMessage({
 					command: executionPlan.commandInfo.command,
@@ -1788,6 +3511,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							compatibilityWorkaround,
 							effectiveArgs: redactedEffectiveArgs,
 							sessionMode,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: traceOwnerGuardMessage, succeeded: false, validationError: traceOwnerGuardMessage }),
 							validationError: traceOwnerGuardMessage,
 							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 						},
@@ -1797,7 +3521,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				const stdinValidationError = validateStdinCommandContract({
 					command: executionPlan.commandInfo.command,
 					commandTokens,
-					stdin: params.stdin,
+					stdin: toolStdin,
 				});
 				if (stdinValidationError) {
 					return {
@@ -1808,13 +3532,14 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							compatibilityWorkaround,
 							effectiveArgs: redactedEffectiveArgs,
 							sessionMode,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: stdinValidationError, succeeded: false, validationError: stdinValidationError }),
 							validationError: stdinValidationError,
 							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 						},
 						isError: true,
 					};
 				}
-				const waitIpcTimeoutError = validateWaitIpcTimeoutContract(commandTokens, params.stdin);
+				const waitIpcTimeoutError = validateWaitIpcTimeoutContract(commandTokens, toolStdin);
 				if (waitIpcTimeoutError) {
 					return {
 						content: [{ type: "text", text: waitIpcTimeoutError }],
@@ -1824,6 +3549,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							compatibilityWorkaround,
 							effectiveArgs: redactedEffectiveArgs,
 							sessionMode,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: waitIpcTimeoutError, succeeded: false, timedOut: true, validationError: waitIpcTimeoutError }),
 							validationError: waitIpcTimeoutError,
 							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 						},
@@ -1833,18 +3559,43 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 
 				const priorSessionTabTargetState = executionPlan.sessionName ? sessionTabTargets.get(executionPlan.sessionName) : undefined;
 				const priorSessionTabTarget = priorSessionTabTargetState?.target;
+				const priorRefSnapshotState = executionPlan.sessionName ? sessionRefSnapshots.get(executionPlan.sessionName) : undefined;
+				const staleRefPreflight = buildStaleRefPreflight({
+					commandTokens,
+					currentTarget: priorSessionTabTarget,
+					refSnapshot: priorRefSnapshotState,
+					stdin: toolStdin,
+				});
+				if (staleRefPreflight) {
+					return {
+						content: [{ type: "text", text: staleRefPreflight.message }],
+						details: {
+							args: redactedArgs,
+							command: executionPlan.commandInfo.command,
+							compatibilityWorkaround,
+							effectiveArgs: redactedEffectiveArgs,
+							nextActions: sessionAwareStaleRefNextActions(executionPlan.sessionName),
+							refIds: staleRefPreflight.refIds,
+							refSnapshot: staleRefPreflight.snapshot,
+							sessionMode,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: staleRefPreflight.message, failureCategory: "stale-ref", succeeded: false }),
+							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+						},
+						isError: true,
+					};
+				}
 				let pinnedBatchUnwrapMode: PinnedBatchUnwrapMode | undefined;
 				let includePinnedNavigationSummary = false;
 				let sessionTabCorrection: OpenResultTabCorrection | undefined;
 				let processArgs = executionPlan.effectiveArgs;
-				let processStdin = preparedArgs.stdin ?? params.stdin;
+				let processStdin = preparedArgs.stdin ?? toolStdin;
 				if (
 					priorSessionTabTarget &&
 					shouldPinSessionTabForCommand({
 						command: executionPlan.commandInfo.command,
 						commandTokens,
 						sessionName: executionPlan.sessionName,
-						stdin: params.stdin,
+						stdin: toolStdin,
 					})
 				) {
 					const plannedSessionTabSelection = await collectSessionTabSelection({
@@ -1854,7 +3605,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						target: priorSessionTabTarget,
 					});
 					if (plannedSessionTabSelection && executionPlan.sessionName) {
-						if (executionPlan.commandInfo.command === "eval" && params.stdin !== undefined) {
+						if (executionPlan.commandInfo.command === "eval" && toolStdin !== undefined) {
 							const appliedSessionTabSelection = await applyOpenResultTabCorrection({
 								correction: plannedSessionTabSelection,
 								cwd: ctx.cwd,
@@ -1872,6 +3623,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 										effectiveArgs: redactedEffectiveArgs,
 										sessionMode,
 										sessionTabCorrection: plannedSessionTabSelection,
+										...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: error, failureCategory: "tab-drift", succeeded: false, tabDrift: true, validationError: error }),
+										nextActions: buildAgentBrowserNextActions({ failureCategory: "tab-drift", resultCategory: "failure" }),
 										validationError: error,
 										...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 									},
@@ -1884,7 +3637,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 								command: executionPlan.commandInfo.command,
 								commandTokens,
 								selectedTab: plannedSessionTabSelection.selectedTab,
-								stdin: params.stdin,
+								stdin: toolStdin,
 							});
 							if (pinnedBatchPlan && "error" in pinnedBatchPlan) {
 								return {
@@ -1896,6 +3649,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 										effectiveArgs: redactedEffectiveArgs,
 										sessionMode,
 										sessionTabCorrection: plannedSessionTabSelection,
+										...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: pinnedBatchPlan.error, failureCategory: "tab-drift", succeeded: false, tabDrift: true, validationError: pinnedBatchPlan.error }),
+										nextActions: buildAgentBrowserNextActions({ failureCategory: "tab-drift", resultCategory: "failure" }),
 										validationError: pinnedBatchPlan.error,
 										...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 									},
@@ -1935,14 +3690,27 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 
 				if (processResult.spawnError?.message.includes("ENOENT")) {
 					const errorText = buildMissingBinaryMessage();
+					const managedSessionOutcome = buildManagedSessionOutcome({
+						activeAfter: managedSessionActive,
+						activeBefore: managedSessionActive,
+						attemptedSessionName: executionPlan.managedSessionName,
+						command: executionPlan.commandInfo.command,
+						currentSessionName: managedSessionName,
+						previousSessionName: managedSessionName,
+						sessionMode,
+						succeeded: false,
+					});
+					const managedSessionOutcomeText = formatManagedSessionOutcomeText(managedSessionOutcome);
 					return {
-						content: [{ type: "text", text: errorText }],
+						content: [{ type: "text", text: managedSessionOutcomeText ? `${errorText}\n\n${managedSessionOutcomeText}` : errorText }],
 						details: {
 							args: redactedArgs,
 							compatibilityWorkaround,
 							effectiveArgs: redactedProcessArgs,
+							managedSessionOutcome,
 							sessionMode,
 							sessionTabCorrection,
+							...buildAgentBrowserResultCategoryDetails({ args: redactedProcessArgs, command: executionPlan.commandInfo.command, errorText, failureCategory: "missing-binary", spawnError: processResult.spawnError.message, succeeded: false }),
 							spawnError: processResult.spawnError.message,
 						},
 						isError: true,
@@ -1997,7 +3765,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					const plainTextInspection = executionPlan.plainTextInspection && processSucceeded;
 					const parseSucceeded = plainTextInspection || parseError === undefined;
 					const envelopeSuccess = plainTextInspection ? true : presentationEnvelope?.success !== false;
-					const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
+					let succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
 					const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
 					updateTraceOwnerState({
 						command: executionPlan.commandInfo.command,
@@ -2020,12 +3788,13 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							data: mergeNavigationSummaryIntoData(presentationEnvelope.data, navigationSummary),
 						};
 					}
+					let overlayBlockerDiagnostic: OverlayBlockerDiagnostic | undefined;
 
 					let openResultTabCorrection: OpenResultTabCorrection | undefined;
 					if (
 						succeeded &&
 						executionPlan.sessionName &&
-						hasLaunchScopedTabCorrectionFlag(params.args) &&
+						hasLaunchScopedTabCorrectionFlag(toolArgs) &&
 						(executionPlan.commandInfo.command === "goto" ||
 							executionPlan.commandInfo.command === "navigate" ||
 							executionPlan.commandInfo.command === "open")
@@ -2123,33 +3892,91 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							}
 						}
 					}
+					let selectorTextVisibilityDiagnostics: SelectorTextVisibilityDiagnostic[] = [];
+					const timeoutPartialProgress = processResult.timedOut ? await collectTimeoutPartialProgress({
+						command: executionPlan.commandInfo.command,
+						compiledJob,
+						cwd: ctx.cwd,
+						sessionName: executionPlan.sessionName,
+						stdin: toolStdin,
+					}) : undefined;
+					if (succeeded && !sessionTabCorrection && !aboutBlankSessionMismatch) {
+						overlayBlockerDiagnostic = await collectOverlayBlockerDiagnostic({
+							command: executionPlan.commandInfo.command,
+							cwd: ctx.cwd,
+							data: presentationEnvelope?.data,
+							navigationSummary,
+							priorTarget: priorSessionTabTarget,
+							sessionName: executionPlan.sessionName,
+							signal,
+						});
+					}
+					if (succeeded) {
+						selectorTextVisibilityDiagnostics = await collectSelectorTextVisibilityDiagnostics({
+							commandInfo: executionPlan.commandInfo,
+							commandTokens,
+							cwd: ctx.cwd,
+							data: presentationEnvelope?.data,
+							sessionName: executionPlan.sessionName,
+							signal,
+						});
+					}
+					let currentRefSnapshot: SessionRefSnapshot | undefined;
 					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);
+								sessionRefSnapshots.delete(executionPlan.sessionName);
 							} else if (currentSessionTabTarget) {
 								sessionTabTargets.set(executionPlan.sessionName, { order: tabTargetUpdateOrder, target: currentSessionTabTarget });
 							}
 						}
+						const refSnapshot = succeeded
+			? executionPlan.commandInfo.command === "snapshot"
+				? extractRefSnapshotFromData(presentationEnvelope?.data)
+				: executionPlan.commandInfo.command === "batch"
+					? extractRefSnapshotFromBatchResults(presentationEnvelope?.data)
+					: overlayBlockerDiagnostic?.snapshot
+			: undefined;
+						if (refSnapshot && shouldApplySessionTabTargetUpdate({ current: sessionRefSnapshots.get(executionPlan.sessionName), updateOrder: tabTargetUpdateOrder })) {
+							currentRefSnapshot = { ...refSnapshot, target: refSnapshot.target ?? currentSessionTabTarget };
+							sessionRefSnapshots.set(executionPlan.sessionName, { ...currentRefSnapshot, order: tabTargetUpdateOrder });
+						} else {
+							currentRefSnapshot = sessionRefSnapshots.get(executionPlan.sessionName);
+						}
 					}
 
+					const priorManagedSessionActive = managedSessionActive;
 					const priorManagedSessionCwd = managedSessionCwd;
+					const priorManagedSessionName = managedSessionName;
 					const managedSessionState = resolveManagedSessionState({
 						command: executionPlan.commandInfo.command,
 						managedSessionName: executionPlan.managedSessionName,
-						priorActive: managedSessionActive,
-						priorSessionName: managedSessionName,
+						priorActive: priorManagedSessionActive,
+						priorSessionName: priorManagedSessionName,
 						succeeded,
 					});
 					const replacedManagedSessionName = managedSessionState.replacedSessionName;
 					managedSessionActive = managedSessionState.active;
 					managedSessionName = managedSessionState.sessionName;
+					let managedSessionOutcome = buildManagedSessionOutcome({
+						activeAfter: managedSessionActive,
+						activeBefore: priorManagedSessionActive,
+						attemptedSessionName: executionPlan.managedSessionName,
+						command: executionPlan.commandInfo.command,
+						currentSessionName: managedSessionName,
+						previousSessionName: priorManagedSessionName,
+						replacedSessionName: replacedManagedSessionName,
+						sessionMode,
+						succeeded,
+					});
 					if (executionPlan.managedSessionName && succeeded) {
 						managedSessionCwd = ctx.cwd;
 					}
 					if (replacedManagedSessionName) {
 						sessionTabTargets.delete(replacedManagedSessionName);
+						sessionRefSnapshots.delete(replacedManagedSessionName);
 						await closeManagedSession({
 							cwd: priorManagedSessionCwd,
 							sessionName: replacedManagedSessionName,
@@ -2165,7 +3992,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						exitCode: processResult.exitCode,
 						parseError,
 						plainTextInspection,
-						staleRefArgs: getStaleRefArgs(commandTokens, params.stdin),
+						staleRefArgs: getStaleRefArgs(commandTokens, toolStdin),
 						spawnError: processResult.spawnError,
 						stderr: processResult.stderr,
 						timedOut: processResult.timedOut,
@@ -2189,6 +4016,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							summary: `${redactedArgs.join(" ")} completed`,
 						  }
 						: await buildToolPresentation({
+								args: redactedProcessArgs,
 								artifactManifest,
 								artifactRequest: screenshotArtifactRequest,
 								batchArtifactRequests: batchScreenshotArtifactRequests,
@@ -2220,6 +4048,45 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 					if (presentation.artifactManifest) {
 						artifactManifest = presentation.artifactManifest;
 					}
+					const qaPreset = compiledQaPreset ? analyzeQaPresetResults(presentationEnvelope?.data) : undefined;
+					const sourceLookup = compiledSourceLookup ? await analyzeSourceLookupResults(presentationEnvelope?.data, compiledSourceLookup, ctx.cwd) : undefined;
+					const networkSourceLookup = compiledNetworkSourceLookup ? redactNetworkSourceLookupAnalysis(await analyzeNetworkSourceLookupResults(presentationEnvelope?.data, compiledNetworkSourceLookup, ctx.cwd)) : undefined;
+					if (networkSourceLookup && presentation.content[0]?.type === "text") {
+						presentation.content[0] = { ...presentation.content[0], text: `${networkSourceLookup.summary}\n\n${presentation.content[0].text}` };
+					} else if (networkSourceLookup) {
+						presentation.content.unshift({ type: "text", text: networkSourceLookup.summary });
+					}
+					if (sourceLookup && presentation.content[0]?.type === "text") {
+						presentation.content[0] = { ...presentation.content[0], text: `${sourceLookup.summary}\n\n${presentation.content[0].text}` };
+					} else if (sourceLookup) {
+						presentation.content.unshift({ type: "text", text: sourceLookup.summary });
+					}
+					if (qaPreset && (!qaPreset.passed || qaPreset.warnings.length > 0)) {
+						if (!qaPreset.passed) {
+							succeeded = false;
+							presentation.failureCategory = "qa-failure";
+						}
+						presentation.summary = qaPreset.summary;
+						if (presentation.content[0]?.type === "text") {
+							presentation.content[0] = { ...presentation.content[0], text: `${qaPreset.summary}\n\n${presentation.content[0].text}` };
+						} else {
+							presentation.content.unshift({ type: "text", text: qaPreset.summary });
+						}
+					}
+					if (managedSessionOutcome && managedSessionOutcome.succeeded !== succeeded) {
+						managedSessionOutcome = { ...managedSessionOutcome, succeeded };
+					}
+					const evalStdinHint = getEvalStdinHint({
+						command: executionPlan.commandInfo.command,
+						data: presentationEnvelope?.data,
+						stdin: toolStdin,
+					});
+					const resultArtifactManifest = presentation.artifactManifest ?? artifactManifest;
+					const artifactCleanup = getArtifactCleanupGuidance({
+						command: executionPlan.commandInfo.command,
+						manifest: resultArtifactManifest,
+						succeeded,
+					});
 					const warningText = aboutBlankSessionMismatch ? buildAboutBlankWarning(aboutBlankSessionMismatch) : undefined;
 					const contentWithSessionWarnings = userRequestedJson && !plainTextInspection
 						? buildJsonVisibleContent({
@@ -2248,20 +4115,69 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							? { ...item, text: exactRedactedText }
 							: { ...item, text: redactSensitiveText(exactRedactedText) };
 					});
+					const categoryDetails = buildAgentBrowserResultCategoryDetails({
+						artifacts: presentation.artifacts,
+						args: redactedProcessArgs,
+						command: executionPlan.commandInfo.command,
+						confirmationRequired: presentation.summary.startsWith("Confirmation required"),
+						errorText: errorText ?? presentation.summary,
+						failureCategory: presentation.failureCategory ?? presentation.batchFailure?.failedStep.failureCategory,
+						inspection: plainTextInspection,
+						parseError,
+						savedFile: presentation.savedFile,
+						spawnError: processResult.spawnError?.message,
+						succeeded,
+						tabDrift: !succeeded && (aboutBlankSessionMismatch !== undefined || sessionTabCorrection !== undefined),
+						timedOut: processResult.timedOut,
+						validationError: undefined,
+					});
+					let nextActions = presentation.nextActions ? [...presentation.nextActions] : undefined;
+					if (categoryDetails.failureCategory === "stale-ref") {
+						nextActions = sessionAwareStaleRefNextActions(executionPlan.sessionName);
+					}
+					if (categoryDetails.failureCategory === "selector-not-found" && redactedCompiledSemanticAction) {
+						const candidateActions = buildSemanticActionCandidateActions(redactedCompiledSemanticAction);
+						if (candidateActions.length > 0) {
+							(nextActions ??= []).push(...candidateActions);
+						}
+					}
+					if (overlayBlockerDiagnostic) {
+						(nextActions ??= []).push(...buildOverlayBlockerNextActions({ diagnostic: overlayBlockerDiagnostic, sessionName: executionPlan.sessionName }));
+					}
+					if (selectorTextVisibilityDiagnostics.length > 0) {
+						(nextActions ??= []).push(...buildSelectorTextVisibilityNextActions({ diagnostics: selectorTextVisibilityDiagnostics, sessionName: executionPlan.sessionName }));
+					}
+					if (categoryDetails.failureCategory === "stale-ref" && redactedCompiledSemanticAction) {
+						(nextActions ??= []).push({
+							id: "retry-semantic-action-after-stale-ref",
+							params: { args: redactedCompiledSemanticAction.args },
+							reason: "Retry the same semantic target via its compiled find command after the upstream stale-ref failure proves the prior action did not execute.",
+							safety: "Use only for the same intended target; direct stale @refs still require a fresh snapshot or stable locator before retrying.",
+							tool: "agent_browser" as const,
+						});
+					}
 					const details = {
 						args: redactedArgs,
-						artifactManifest: presentation.artifactManifest,
-						artifactRetentionSummary: presentation.artifactRetentionSummary,
+						compiledJob: redactedCompiledJob,
+						compiledQaPreset: redactedCompiledQaPreset,
+						compiledSourceLookup: redactedCompiledSourceLookup,
+						compiledNetworkSourceLookup: redactedCompiledNetworkSourceLookup,
+						artifactManifest: resultArtifactManifest,
+						artifactRetentionSummary: presentation.artifactRetentionSummary ?? (resultArtifactManifest ? formatSessionArtifactRetentionSummary(resultArtifactManifest) : undefined),
+						artifactCleanup,
+						artifactVerification: presentation.artifactVerification,
 						artifacts: presentation.artifacts,
 						batchFailure: presentation.batchFailure,
 						batchSteps: presentation.batchSteps,
 						command: executionPlan.commandInfo.command,
+						compiledSemanticAction: redactedCompiledSemanticAction,
 						compatibilityWorkaround,
 						subcommand: executionPlan.commandInfo.subcommand,
 						data: presentation.data,
 						error: plainTextInspection ? undefined : presentationEnvelope?.error,
 						inspection: plainTextInspection || undefined,
 						navigationSummary,
+						...categoryDetails,
 						aboutBlankSessionMismatch,
 						openResultTabCorrection,
 						effectiveArgs: redactedProcessArgs,
@@ -2269,14 +4185,26 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						fullOutputPath: parseFailureOutput.fullOutputPath ?? presentation.fullOutputPath,
 						fullOutputPaths: presentation.fullOutputPaths,
 						fullOutputUnavailable: parseFailureOutput.fullOutputUnavailable,
+						managedSessionOutcome,
 						imagePath: presentation.imagePath,
 						imagePaths: presentation.imagePaths,
+						nextActions,
+						pageChangeSummary: presentation.pageChangeSummary,
+						overlayBlockers: overlayBlockerDiagnostic,
+						qaPreset,
+						selectorTextVisibility: selectorTextVisibilityDiagnostics[0],
+						selectorTextVisibilityAll: selectorTextVisibilityDiagnostics.length > 1 ? selectorTextVisibilityDiagnostics : undefined,
+						evalStdinHint,
+						timeoutPartialProgress,
 						parseError: plainTextInspection ? undefined : parseError,
 						savedFile: presentation.savedFile,
 						savedFilePath: presentation.savedFilePath,
+						sourceLookup,
+						networkSourceLookup,
 						sessionMode,
 						sessionTabCorrection,
 						sessionTabTarget: currentSessionTabTarget,
+						refSnapshot: currentRefSnapshot,
 						...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 						sessionRecoveryHint: redactedRecoveryHint,
 						startupScopedFlags: executionPlan.startupScopedFlags,
@@ -2287,11 +4215,28 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						timeoutMs: processResult.timeoutMs,
 					};
 
-					return {
-						content: redactedContent,
+					const semanticActionCandidateText = nextActions ? formatSemanticActionCandidateText(nextActions) : undefined;
+					const overlayBlockerText = overlayBlockerDiagnostic ? formatOverlayBlockerText(overlayBlockerDiagnostic) : undefined;
+					const selectorTextVisibilityText = formatSelectorTextVisibilityText(selectorTextVisibilityDiagnostics);
+					const evalStdinHintText = formatEvalStdinHintText(evalStdinHint);
+					const artifactCleanupText = formatArtifactCleanupGuidanceText(artifactCleanup);
+					const timeoutPartialProgressText = timeoutPartialProgress ? formatTimeoutPartialProgressText(timeoutPartialProgress) : undefined;
+					const managedSessionOutcomeText = formatManagedSessionOutcomeText(managedSessionOutcome);
+					const rawAppendedDiagnosticText = [semanticActionCandidateText, overlayBlockerText, selectorTextVisibilityText, evalStdinHintText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
+					const appendedDiagnosticText = redactSensitiveText(redactExactSensitiveText(rawAppendedDiagnosticText, exactSensitiveValues));
+					const shouldAppendDiagnosticText = appendedDiagnosticText.length > 0 && (!userRequestedJson || plainTextInspection);
+					const content = shouldAppendDiagnosticText && redactedContent[0]?.type === "text"
+						? [
+							{ ...redactedContent[0], text: `${redactedContent[0].text}\n\n${appendedDiagnosticText}` },
+							...redactedContent.slice(1),
+						]
+						: redactedContent;
+					const result = {
+						content,
 						details: redactToolDetails(details, exactSensitiveValues),
 						isError: !succeeded,
 					};
+					return compiledNetworkSourceLookup ? redactNetworkSourceLookupSurface(result) as typeof result : result;
 				} finally {
 					if (processResult.stdoutSpillPath) {
 						await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
@@ -2299,7 +4244,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				}
 			};
 
-			return extractExplicitSessionName(params.args)
+			return extractExplicitSessionName(toolArgs)
 				? runTool()
 				: managedSessionExecutionQueue.run(runTool);
 		},