pi-agent-browser-native 0.2.33 → 0.2.35

package/extensions/agent-browser/lib/orchestration/browser-run/diagnostics.ts

@@ -1,12 +1,14 @@
-import { constants as fsConstants } from "node:fs";
-import { access, stat } from "node:fs/promises";
-import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
 
+import { isCloseCommand, isOpenNavigationCommand } from "../../command-taxonomy.js";
 import type { ElectronLaunchRecord } from "../../electron/launch.js";
+import { executableExistsOnPath } from "../../executable-path.js";
 import type { AgentBrowserSourceLookupAnalysis, CompiledAgentBrowserJob, CompiledAgentBrowserSemanticAction } from "../../input-modes.js";
+import { isHttpOrHttpsUrl } from "../../input-modes/job.js";
 import type { AgentBrowserNextAction } from "../../results.js";
 import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
-import { withOptionalSessionArgs } from "../../results/next-actions.js";
+import { buildNextToolAction, withOptionalSessionArgs } from "../../results/next-actions.js";
 import { buildVisibleRefFallbackDiagnosticFromSnapshot, getVisibleRefFallbackTarget, type VisibleRefFallbackDiagnostic } from "../../results/selector-recovery.js";
 import { extractRefSnapshotFromData, normalizeComparableUrl, type SessionTabTarget } from "../../session-page-state.js";
 import { redactInvocationArgs, redactSensitiveText, type CommandInfo } from "../../runtime.js";
@@ -19,16 +21,19 @@ import {
 	getGuardedRefUsage,
 	runSessionCommandData,
 } from "./session-state.js";
+import { parseValidBatchStepEntries } from "../batch-stdin.js";
 import { getScreenshotPathTokenIndex } from "./prepare.js";
 import type {
 	ArtifactCleanupGuidance,
 	ComboboxFocusDiagnostic,
 	ElectronBroadGetTextScopeDiagnostic,
 	ElectronHandoffSummary,
+	ElectronManagedSessionTarget,
 	FillVerificationDiagnostic,
 	NavigationSummary,
 	OverlayBlockerCandidate,
 	OverlayBlockerDiagnostic,
+	QaAttachedPreconditionFailure,
 	QaAttachedTarget,
 	RecordingDependencyWarning,
 	ScrollNoopDiagnostic,
@@ -236,23 +241,6 @@ function getRecordStartLikeCommand(command: string | undefined, commandTokens: s
 	return undefined;
 }
 
-async function executableExistsOnPath(command: string): Promise<boolean> {
-	const pathValue = process.env.PATH ?? "";
-	const extensions = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean) : [""];
-	for (const directory of pathValue.split(delimiter).filter(Boolean)) {
-		for (const extension of extensions) {
-			try {
-				const candidate = join(directory, `${command}${extension}`);
-				await access(candidate, fsConstants.X_OK);
-				if ((await stat(candidate)).isFile()) return true;
-			} catch {
-				// Try the next candidate.
-			}
-		}
-	}
-	return false;
-}
-
 export async function collectRecordingDependencyWarning(options: { command: string | undefined; commandTokens: string[]; succeeded: boolean }): Promise<RecordingDependencyWarning | undefined> {
 	if (!options.succeeded) return undefined;
 	const recordCommand = getRecordStartLikeCommand(options.command, options.commandTokens);
@@ -464,7 +452,7 @@ export function formatEvalStdinHintText(hint: ReturnType<typeof getEvalStdinHint
 }
 
 export async function getArtifactCleanupGuidance(options: { command?: string; cwd: string; manifest?: SessionArtifactManifest; succeeded: boolean }): Promise<ArtifactCleanupGuidance | undefined> {
-	if (!options.succeeded || options.command !== "close" || !options.manifest || options.manifest.entries.length === 0) return undefined;
+	if (!options.succeeded || !isCloseCommand(options.command) || !options.manifest || options.manifest.entries.length === 0) return undefined;
 	const explicitEntries = options.manifest.entries.filter((entry) => entry.storageScope === "explicit-path");
 	const explicitArtifactPaths: string[] = [];
 	const seenPaths = new Set<string>();
@@ -491,7 +479,19 @@ async function collectManagedSessionCommandData(options: { args: string[]; cwd:
 	try { return { data: await runSessionCommandData(options) }; } catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
 }
 
-async function collectElectronManagedSessionTarget(options: { cwd: string; sessionName?: string; signal?: AbortSignal; timeoutMs?: number }): Promise<QaAttachedTarget | undefined> {
+async function collectElectronManagedSessionUrl(options: { cwd: string; sessionName: string; signal?: AbortSignal; timeoutMs?: number }): Promise<{ error?: string; url?: string }> {
+	const urlResult = await collectManagedSessionCommandData({
+		args: ["get", "url"],
+		cwd: options.cwd,
+		sessionName: options.sessionName,
+		signal: options.signal,
+		timeoutMs: options.timeoutMs,
+	});
+	const url = boundElectronProbeString(extractStringResultField(urlResult.data, "result") ?? extractStringResultField(urlResult.data, "url"), 300);
+	return urlResult.error ? { error: urlResult.error } : { url };
+}
+
+export async function collectElectronManagedSessionTarget(options: { cwd: string; sessionName?: string; signal?: AbortSignal; timeoutMs?: number }): Promise<ElectronManagedSessionTarget | undefined> {
 	if (!options.sessionName) return undefined;
 	const [titleResult, urlResult] = await Promise.all([
 		collectManagedSessionCommandData({ args: ["get", "title"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs }),
@@ -514,6 +514,58 @@ export function formatQaAttachedTargetText(target: QaAttachedTarget | undefined)
 	return ["QA attached target:", target.sessionName, target.title, target.url].filter((part): part is string => typeof part === "string" && part.length > 0).join(" — ");
 }
 
+export function buildQaAttachedRecoveryNextActions(sessionName: string | undefined): AgentBrowserNextAction[] {
+	const sessionArgs = (args: string[]) => withOptionalSessionArgs(sessionName, args);
+	return [
+		buildNextToolAction({
+			args: sessionArgs(["tab", "list"]),
+			id: "list-tabs-before-qa-attached",
+			reason: "Inspect the connected session tabs before retrying qa.attached.",
+			safety: "Read-only tab listing for the attached session.",
+		}),
+		buildNextToolAction({
+			args: sessionArgs(["snapshot", "-i"]),
+			id: "snapshot-before-qa-attached",
+			reason: "Capture interactive refs on the active http(s) page before retrying qa.attached.",
+			safety: "Read-only snapshot; confirms a renderable page is selected.",
+		}),
+	];
+}
+
+export async function validateQaAttachedPrecondition(options: {
+	cwd: string;
+	sessionName?: string;
+	signal?: AbortSignal;
+}): Promise<QaAttachedPreconditionFailure | undefined> {
+	if (!options.sessionName) {
+		return {
+			error: "qa.attached requires an active attached session with a resolvable session name.",
+			nextActions: buildQaAttachedRecoveryNextActions(options.sessionName),
+		};
+	}
+	const urlProbe = await collectElectronManagedSessionUrl({ cwd: options.cwd, sessionName: options.sessionName, signal: options.signal });
+	if (urlProbe.error) {
+		return {
+			error: `qa.attached could not read the attached session URL: ${urlProbe.error}. Run tab list or snapshot -i before retrying qa.attached.`,
+			nextActions: buildQaAttachedRecoveryNextActions(options.sessionName),
+		};
+	}
+	const url = urlProbe.url?.trim();
+	if (!url) {
+		return {
+			error: "qa.attached requires an attached session with a readable http(s) page URL. Run tab list, select a stable tab, then snapshot -i before retrying.",
+			nextActions: buildQaAttachedRecoveryNextActions(options.sessionName),
+		};
+	}
+	if (!isHttpOrHttpsUrl(url)) {
+		return {
+			error: `qa.attached requires an http(s) page URL; the current attached URL is "${url}". Use tab list and snapshot -i to recover a web surface before retrying.`,
+			nextActions: buildQaAttachedRecoveryNextActions(options.sessionName),
+		};
+	}
+	return undefined;
+}
+
 function getTopLevelFillInvocation(commandTokens: string[]): { expected: string; selector: string } | undefined {
 	if (commandTokens[0] !== "fill" || commandTokens.length < 3) return undefined;
 	const selector = commandTokens[1];
@@ -581,11 +633,7 @@ export async function collectElectronHandoff(options: { cwd: string; handoff: "c
 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 []; }
+	return parseValidBatchStepEntries(stdin).map(({ index, step }) => ({ args: step, index: index + 1 }));
 }
 
 function getLastPositionalToken(args: string[], startIndex = 1): string | undefined {
@@ -643,7 +691,7 @@ async function collectTimeoutArtifactEvidence(cwd: string, steps: Array<{ args:
 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);
+		if (isOpenNavigationCommand(args[0]) || args[0] === "pushstate") return getLastPositionalToken(args);
 	}
 	return undefined;
 }

package/extensions/agent-browser/lib/orchestration/browser-run/final-result.ts

@@ -43,6 +43,7 @@ import {
 } from "../../session-page-state.js";
 import { extractExplicitSessionName, redactInvocationArgs, redactSensitiveText, redactSensitiveValue, type OpenResultTabCorrection } from "../../runtime.js";
 import { isRecord } from "../../parsing.js";
+import { buildClickDispatchNextActions, formatClickDispatchDiagnosticText } from "./click-dispatch.js";
 import {
 	buildComboboxFocusNextActions,
 	buildElectronBroadGetTextScopeNextActions,
@@ -212,7 +213,7 @@ export function buildElectronHostFailureResult(options: {
 	return { content: [{ type: "text", text: redactSensitiveText(text) }], details: redactToolDetails(details, []), isError: true };
 }
 
-function formatElectronTargetLines(targets: ElectronCdpTarget[], limit = 8): string[] {
+export function formatElectronTargetLines(targets: ElectronCdpTarget[], limit = 8): string[] {
 	const shownTargets = targets.slice(0, limit);
 	const lines = shownTargets.map((target) => {
 		const label = [target.type, target.title].filter(Boolean).join(" ") || target.id || "target";
@@ -319,6 +320,7 @@ function buildResultNextActions(options: FinalResultInput): AgentBrowserNextActi
 	if (options.selectorTextVisibilityDiagnostics.length > 0) nextActionCollector.append(buildSelectorTextVisibilityNextActions({ diagnostics: options.selectorTextVisibilityDiagnostics, sessionName: options.executionPlan.sessionName }));
 	if (options.electronBroadGetTextScopeDiagnostics.length > 0) nextActionCollector.append(buildElectronBroadGetTextScopeNextActions({ diagnostics: options.electronBroadGetTextScopeDiagnostics, sessionName: options.executionPlan.sessionName }));
 	if (options.sourceLookup?.electronContext) nextActionCollector.appendUnique(buildSourceLookupElectronNextActions(options.sourceLookup));
+	if (options.clickDispatchDiagnostic) nextActionCollector.append(buildClickDispatchNextActions({ commandTokens: options.commandTokens, sessionName: options.executionPlan.sessionName }));
 	if (options.scrollNoopDiagnostic) nextActionCollector.append(buildScrollNoopNextActions(options.executionPlan.sessionName));
 	if (options.comboboxFocusDiagnostic) nextActionCollector.append(buildComboboxFocusNextActions(options.executionPlan.sessionName));
 	if (options.categoryDetails.failureCategory === "stale-ref" && options.redactedCompiledSemanticAction && isCompiledSemanticActionFindCommand(options.compiledSemanticAction)) nextActionCollector.append([{ id: "retry-semantic-action-after-stale-ref", params: { args: options.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 }]);
@@ -369,6 +371,7 @@ function buildAgentBrowserResultDetails(options: FinalResultInput, nextActions:
 		imagePaths: options.presentation.imagePaths,
 		nextActions,
 		pageChangeSummary,
+		clickDispatch: options.clickDispatchDiagnostic,
 		overlayBlockers: options.overlayBlockerDiagnostic,
 		fillVerification: options.fillVerificationDiagnostic,
 		visibleRefFallback: publicVisibleRefFallbackDiagnostic,
@@ -411,6 +414,7 @@ export function buildFinalAgentBrowserToolResult(options: FinalResultInput): Age
 	const visibleRefFallbackText = formatVisibleRefFallbackText(options.visibleRefFallbackDiagnostic);
 	const richInputRecoveryText = formatRichInputRecoveryText(options.richInputRecoveryDiagnostic);
 	const semanticActionCandidateText = nextActions ? formatSemanticActionCandidateText(nextActions) : undefined;
+	const clickDispatchText = options.clickDispatchDiagnostic ? formatClickDispatchDiagnosticText(options.clickDispatchDiagnostic) : undefined;
 	const overlayBlockerText = options.overlayBlockerDiagnostic ? formatOverlayBlockerText(options.overlayBlockerDiagnostic) : undefined;
 	const fillVerificationText = formatFillVerificationText(options.fillVerificationDiagnostic);
 	const electronRefFreshnessText = formatElectronRefFreshnessText(options.electronRefFreshnessDiagnostic);
@@ -423,7 +427,7 @@ export function buildFinalAgentBrowserToolResult(options: FinalResultInput): Age
 	const artifactCleanupText = formatArtifactCleanupGuidanceText(options.artifactCleanup);
 	const timeoutPartialProgressText = options.timeoutPartialProgress ? formatTimeoutPartialProgressText(options.timeoutPartialProgress) : undefined;
 	const managedSessionOutcomeText = formatManagedSessionOutcomeText(options.managedSessionOutcome);
-	const rawAppendedDiagnosticText = [visibleRefFallbackText, richInputRecoveryText, semanticActionCandidateText, overlayBlockerText, fillVerificationText, electronRefFreshnessText, selectorTextVisibilityText, electronBroadGetTextScopeText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
+	const rawAppendedDiagnosticText = [visibleRefFallbackText, richInputRecoveryText, semanticActionCandidateText, clickDispatchText, overlayBlockerText, fillVerificationText, electronRefFreshnessText, selectorTextVisibilityText, electronBroadGetTextScopeText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
 	const appendedDiagnosticText = redactSensitiveText(redactExactSensitiveText(rawAppendedDiagnosticText, options.exactSensitiveValues));
 	const shouldAppendDiagnosticText = appendedDiagnosticText.length > 0 && (!options.userRequestedJson || options.plainTextInspection);
 	let content = shouldAppendDiagnosticText && options.redactedContent[0]?.type === "text" ? [{ ...options.redactedContent[0], text: `${options.redactedContent[0].text}\n\n${appendedDiagnosticText}` }, ...options.redactedContent.slice(1)] : options.redactedContent;

package/extensions/agent-browser/lib/orchestration/browser-run/index.ts

@@ -1,11 +1,13 @@
 import { runAgentBrowserProcess } from "../../process.js";
+import { cleanupClickDispatchProbe } from "./click-dispatch.js";
 import { applyBrowserRunStatePatch } from "./session-state.js";
 import { buildMissingBinaryFailureResult } from "./final-result.js";
 import { prepareBrowserRun } from "./prepare.js";
 import { processBrowserOutput } from "./process-output.js";
 import type { AgentBrowserToolResult, BrowserRunOptions } from "./types.js";
 
-export type { BrowserRunOptions, BrowserRunState } from "./types.js";
+export { closeManagedSession } from "./session-state.js";
+export type { AgentBrowserToolResult, BrowserRunOptions, BrowserRunState, TraceOwner } from "./types.js";
 
 export async function runAgentBrowserTool(options: BrowserRunOptions): Promise<AgentBrowserToolResult> {
 	const preparedResult = await prepareBrowserRun(options);
@@ -15,32 +17,36 @@ export async function runAgentBrowserTool(options: BrowserRunOptions): Promise<A
 	}
 
 	const { prepared } = preparedResult;
-	const processResult = await runAgentBrowserProcess({
-		args: prepared.processArgs,
-		cwd: options.cwd,
-		env: prepared.executionPlan.managedSessionName ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs } : undefined,
-		signal: options.signal,
-		stdin: prepared.processStdin,
-	});
+	try {
+		const processResult = await runAgentBrowserProcess({
+			args: prepared.processArgs,
+			cwd: options.cwd,
+			env: prepared.executionPlan.managedSessionName ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs } : undefined,
+			signal: options.signal,
+			stdin: prepared.processStdin,
+		});
 
-	const missingBinaryResult = await buildMissingBinaryFailureResult({
-		compatibilityWorkaround: prepared.compatibilityWorkaround,
-		electronLaunch: prepared.electronLaunch,
-		executionPlan: prepared.executionPlan,
-		implicitSessionCloseTimeoutMs: options.implicitSessionCloseTimeoutMs,
-		managedSessionActive: options.state.managedSessionActive,
-		managedSessionName: options.state.managedSessionName,
-		processResult,
-		redactedArgs: prepared.redactedArgs,
-		redactedProcessArgs: prepared.redactedProcessArgs,
-		sessionMode: prepared.sessionMode,
-		sessionTabCorrection: prepared.sessionTabCorrection,
-	});
-	if (missingBinaryResult) {
-		return missingBinaryResult;
-	}
+		const missingBinaryResult = await buildMissingBinaryFailureResult({
+			compatibilityWorkaround: prepared.compatibilityWorkaround,
+			electronLaunch: prepared.electronLaunch,
+			executionPlan: prepared.executionPlan,
+			implicitSessionCloseTimeoutMs: options.implicitSessionCloseTimeoutMs,
+			managedSessionActive: options.state.managedSessionActive,
+			managedSessionName: options.state.managedSessionName,
+			processResult,
+			redactedArgs: prepared.redactedArgs,
+			redactedProcessArgs: prepared.redactedProcessArgs,
+			sessionMode: prepared.sessionMode,
+			sessionTabCorrection: prepared.sessionTabCorrection,
+		});
+		if (missingBinaryResult) {
+			return missingBinaryResult;
+		}
 
-	const output = await processBrowserOutput({ ...options, prepared, processResult });
-	applyBrowserRunStatePatch(options.state, output.statePatch);
-	return output.result;
+		const output = await processBrowserOutput({ ...options, prepared, processResult });
+		applyBrowserRunStatePatch(options.state, output.statePatch);
+		return output.result;
+	} finally {
+		await cleanupClickDispatchProbe({ cwd: options.cwd, probe: prepared.clickDispatchProbe, sessionName: prepared.executionPlan.sessionName });
+	}
 }

package/extensions/agent-browser/lib/orchestration/browser-run/prepare.ts

@@ -26,8 +26,11 @@ import {
 	runSessionCommandData,
 	shouldPinSessionTabForCommand,
 } from "./session-state.js";
+import { parseBatchStdinJsonArray, parseValidBatchStepEntries } from "../batch-stdin.js";
 import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
-import { collectScrollPositionSnapshot } from "./diagnostics.js";
+import { prepareClickDispatchProbe } from "./click-dispatch.js";
+import { collectScrollPositionSnapshot, validateQaAttachedPrecondition } from "./diagnostics.js";
+import { findRequestedArtifactCloseViolation, findStopBoundaryViolation } from "./prompt-guards.js";
 import type {
 	BrowserRunInputFields,
 	BrowserRunOptions,
@@ -141,19 +144,14 @@ async function prepareBatchScreenshotPaths(args: string[], stdin: string | undef
 	if (commandTokens[0] !== "batch" || stdin === undefined) {
 		return undefined;
 	}
-	let steps: unknown;
-	try {
-		steps = JSON.parse(stdin);
-	} catch {
-		return undefined;
-	}
-	if (!Array.isArray(steps)) {
+	const parsed = parseBatchStdinJsonArray(stdin);
+	if (parsed.error || parsed.steps === undefined) {
 		return undefined;
 	}
 
 	let changed = false;
 	const batchScreenshotPathRequests: Array<ScreenshotPathRequest | undefined> = [];
-	const preparedSteps = await Promise.all(steps.map(async (step, index) => {
+	const preparedSteps = await Promise.all(parsed.steps.map(async (step, index) => {
 		if (!Array.isArray(step) || !step.every((item) => typeof item === "string") || step[0] !== "screenshot") {
 			return step;
 		}
@@ -282,20 +280,7 @@ export function validateWaitIpcTimeoutContract(commandTokens: string[], stdin: s
 	if (commandTokens[0] !== "batch" || stdin === undefined) {
 		return undefined;
 	}
-	let steps: unknown;
-	try {
-		steps = JSON.parse(stdin);
-	} catch {
-		return undefined;
-	}
-	if (!Array.isArray(steps)) {
-		return undefined;
-	}
-	for (let index = 0; index < steps.length; index += 1) {
-		const step = steps[index];
-		if (!Array.isArray(step) || !step.every((item) => typeof item === "string")) {
-			continue;
-		}
+	for (const { index, step } of parseValidBatchStepEntries(stdin)) {
 		const waitTimeout = findWaitTimeoutMs(step);
 		if (waitTimeout && waitTimeout.timeoutMs > SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS) {
 			return buildIpcUnsafeWaitError(waitTimeout.source, waitTimeout.timeoutMs, index);
@@ -528,6 +513,43 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 	const resolvedSemanticActionRefSnapshot: SessionRefSnapshot | undefined = semanticActionVisibleRefResolution?.snapshot
 		? { ...semanticActionVisibleRefResolution.snapshot, target: semanticActionVisibleRefResolution.snapshot.target ?? priorSessionTabTarget }
 		: undefined;
+	const promptRefSnapshot = resolvedSemanticActionRefSnapshot ?? priorRefSnapshotState;
+	const stopBoundaryViolation = findStopBoundaryViolation({ commandTokens, promptPolicy: options.promptPolicy, refSnapshot: promptRefSnapshot, stdin: runtimeToolStdin });
+	if (stopBoundaryViolation) {
+		return { kind: "early-result", statePatch, result: {
+			content: [{ type: "text", text: stopBoundaryViolation.message }],
+			details: {
+				args: redactedArgs,
+				command: executionPlan.commandInfo.command,
+				compatibilityWorkaround,
+				effectiveArgs: redactedEffectiveArgs,
+				promptGuard: stopBoundaryViolation,
+				sessionMode,
+				...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: stopBoundaryViolation.message, failureCategory: "policy-blocked", succeeded: false, validationError: stopBoundaryViolation.message }),
+				validationError: stopBoundaryViolation.message,
+				...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+			},
+			isError: true,
+		} };
+	}
+	const requestedArtifactCloseViolation = await findRequestedArtifactCloseViolation({ artifactManifest: state.artifactManifest, command: executionPlan.commandInfo.command, cwd, promptPolicy: options.promptPolicy });
+	if (requestedArtifactCloseViolation) {
+		return { kind: "early-result", statePatch, result: {
+			content: [{ type: "text", text: requestedArtifactCloseViolation.message }],
+			details: {
+				args: redactedArgs,
+				command: executionPlan.commandInfo.command,
+				compatibilityWorkaround,
+				effectiveArgs: redactedEffectiveArgs,
+				promptGuard: requestedArtifactCloseViolation,
+				sessionMode,
+				...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: requestedArtifactCloseViolation.message, failureCategory: "policy-blocked", succeeded: false, validationError: requestedArtifactCloseViolation.message }),
+				validationError: requestedArtifactCloseViolation.message,
+				...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+			},
+			isError: true,
+		} };
+	}
 	const staleRefPreflight = buildStaleRefPreflight({
 		commandTokens,
 		currentTarget: priorSessionTabTarget,
@@ -555,6 +577,31 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 		} };
 	}
 
+	if (compiledQaPreset?.checks.attached) {
+		const qaAttachedPrecondition = await validateQaAttachedPrecondition({
+			cwd,
+			sessionName: executionPlan.sessionName,
+			signal,
+		});
+		if (qaAttachedPrecondition) {
+			return { kind: "early-result", statePatch, result: {
+				content: [{ type: "text", text: qaAttachedPrecondition.error }],
+				details: {
+					args: redactedArgs,
+					compiledQaPreset: redactedCompiledQaPreset,
+					compatibilityWorkaround,
+					effectiveArgs: redactedEffectiveArgs,
+					nextActions: qaAttachedPrecondition.nextActions,
+					sessionMode,
+					...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: qaAttachedPrecondition.error, succeeded: false, validationError: qaAttachedPrecondition.error }),
+					validationError: qaAttachedPrecondition.error,
+					...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+				},
+				isError: true,
+			} };
+		}
+	}
+
 	let pinnedBatchUnwrapMode: PreparedBrowserRun["pinnedBatchUnwrapMode"];
 	let includePinnedNavigationSummary = false;
 	let sessionTabCorrection: PreparedBrowserRun["sessionTabCorrection"];
@@ -651,6 +698,9 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 			}
 		}
 	}
+	const clickDispatchProbe = pinnedBatchUnwrapMode === undefined && compiledElectron === undefined
+		? await prepareClickDispatchProbe({ commandTokens, cwd, sessionName: executionPlan.sessionName, signal })
+		: undefined;
 	const redactedProcessArgs = redactInvocationArgs(processArgs);
 	const shouldProbeScrollNoop = executionPlan.commandInfo.command === "scroll" && executionPlan.startupScopedFlags.length === 0;
 	const scrollPositionBefore = shouldProbeScrollNoop
@@ -677,6 +727,7 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 		compiledSemanticAction,
 		compiledSourceLookup,
 		compatibilityWorkaround,
+		clickDispatchProbe,
 		electronLaunch,
 		exactSensitiveValues,
 		executionPlan,