pi-agent-browser-native 0.2.34 → 0.2.36

package/extensions/agent-browser/lib/input-modes/params.ts

@@ -45,7 +45,7 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 			role: Type.Optional(Type.String({ description: "Role locator value for locator=role. May be used instead of value; when both are set they must match." })),
 			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 command." })),
-		}),
+		}, { additionalProperties: false }),
 	),
 	qa: Type.Optional(
 		Type.Union([
@@ -79,7 +79,7 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 			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 })),
-		}, { description: "EXPERIMENTAL: local UI-to-source candidates only (confidence/evidence, not guaranteed mappings). Compiles to batch; mutually exclusive with other input modes." }),
+		}, { additionalProperties: false, description: "EXPERIMENTAL: local UI-to-source candidates only (confidence/evidence, not guaranteed mappings). Compiles to batch; mutually exclusive with other input modes." }),
 	),
 	networkSourceLookup: Type.Optional(
 		Type.Object({
@@ -88,7 +88,7 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 			session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the generated batch." })),
 			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 })),
-		}, { description: "EXPERIMENTAL: failed-request-to-source candidates only (initiator metadata and bounded workspace URL literals; not definitive blame). Compiles to batch; mutually exclusive with other input modes." }),
+		}, { additionalProperties: false, description: "EXPERIMENTAL: failed-request-to-source candidates only (initiator metadata and bounded workspace URL literals; not definitive blame). Compiles to batch; mutually exclusive with other input modes." }),
 	),
 	electron: Type.Optional(
 		Type.Union([
@@ -172,10 +172,10 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 					values: Type.Optional(Type.Array(Type.String({ description: "Option value for select steps." }), { description: "One or more option values for select steps.", minItems: 1 })),
 					path: Type.Optional(Type.String({ description: "Artifact/download path for waitForDownload or screenshot steps." })),
 					milliseconds: Type.Optional(Type.Number({ description: "Milliseconds for wait steps." })),
-				}),
+				}, { additionalProperties: false }),
 				{ minItems: 1 },
 			),
-		}),
+		}, { additionalProperties: false }),
 	),
 	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. Do not use with electron mode." })),
 	sessionMode: Type.Optional(
@@ -185,4 +185,4 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 			default: DEFAULT_SESSION_MODE,
 		}),
 	),
-});
+}, { additionalProperties: false });

package/extensions/agent-browser/lib/orchestration/batch-stdin.ts

@@ -0,0 +1,65 @@
+export type BatchCommandStep = [string, ...string[]];
+
+function validateUserBatchStep(step: unknown, index: number): { error: string; ok: false } | { ok: true; step: BatchCommandStep } {
+	if (!Array.isArray(step)) {
+		return {
+			error: `agent_browser batch stdin step ${index} must be a non-empty array of string command tokens.`,
+			ok: false,
+		};
+	}
+	if (step.length === 0) {
+		return {
+			error: `agent_browser batch stdin step ${index} must not be empty.`,
+			ok: false,
+		};
+	}
+	const invalidTokenIndex = step.findIndex((token) => typeof token !== "string");
+	if (invalidTokenIndex !== -1) {
+		return {
+			error: `agent_browser batch stdin step ${index} token ${invalidTokenIndex} must be a string.`,
+			ok: false,
+		};
+	}
+	return { ok: true, step: step as BatchCommandStep };
+}
+
+export function parseBatchStdinJsonArray(stdin: string | undefined): { error?: string; steps?: unknown[] } {
+	if (stdin === undefined) {
+		return { steps: [] };
+	}
+	try {
+		const parsed = JSON.parse(stdin) as unknown;
+		if (!Array.isArray(parsed)) {
+			return { error: "agent_browser batch stdin must be a JSON array of command steps." };
+		}
+		return { steps: parsed };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { error: `agent_browser batch stdin could not be parsed as JSON: ${message}` };
+	}
+}
+
+export function parseUserBatchStdin(stdin: string | undefined): { error?: string; steps?: BatchCommandStep[] } {
+	const parsed = parseBatchStdinJsonArray(stdin);
+	if (parsed.error || parsed.steps === undefined) {
+		return parsed.error ? { error: parsed.error } : { steps: [] };
+	}
+	const steps: BatchCommandStep[] = [];
+	for (const [index, rawStep] of parsed.steps.entries()) {
+		const validated = validateUserBatchStep(rawStep, index);
+		if (!validated.ok) {
+			return { error: validated.error };
+		}
+		steps.push(validated.step);
+	}
+	return { steps };
+}
+
+export function parseValidBatchStepEntries(stdin: string | undefined): Array<{ index: number; step: BatchCommandStep }> {
+	const parsed = parseBatchStdinJsonArray(stdin);
+	if (parsed.error || parsed.steps === undefined) return [];
+	return parsed.steps.flatMap((step, index) => {
+		const validated = validateUserBatchStep(step, index);
+		return validated.ok ? [{ index, step: validated.step }] : [];
+	});
+}

package/extensions/agent-browser/lib/orchestration/browser-run/browser-action-model.ts

@@ -0,0 +1,154 @@
+/**
+ * Purpose: Normalize planned browser argv into a small action model for prompt-derived guards.
+ * Responsibilities: Map command tokens and batch stdin steps to click-like and keyboard-submit actions with target labels.
+ * Scope: Best-effort finalizing-action detection only; does not model eval, generic fill/type, or non-Enter keyboard flows.
+ */
+
+import type { SessionRefSnapshot } from "../../session-page-state.js";
+import { parseValidBatchStepEntries } from "../batch-stdin.js";
+
+const FINAL_ACTION_PATTERN = /\b(?:finish|place\s+(?:the\s+)?order|submit\s+(?:the\s+)?order|complete\s+(?:the\s+)?order|confirm\s+(?:the\s+)?order|purchase|buy\s+now|pay\s+now|finali[sz]e|submit\s+payment|checkout\s+complete)\b/i;
+
+const CLICK_LIKE_COMMANDS = new Set(["click", "dblclick", "tap"]);
+const FIND_CLICK_ACTIONS = new Set(["click", "dblclick", "tap"]);
+const KEYBOARD_SUBMIT_KEYS = new Set(["enter", "return"]);
+
+export type BrowserFinalizingActionKind = "click-like" | "keyboard-submit";
+
+export interface BrowserFinalizingAction {
+	command: string[];
+	kind: BrowserFinalizingActionKind;
+	stepIndex?: number;
+	targetLabel?: string;
+}
+
+export const STOP_BOUNDARY_GUARD_SCOPE = {
+	covered: [
+		"standalone click, dblclick, and tap",
+		"find … click|dblclick|tap",
+		"batch steps with the click-like shapes above",
+		"press <key> and key <key> when key is Enter or Return",
+	],
+	excluded: [
+		"eval --stdin and other scripted activation",
+		"fill, type, select, drag, and upload without an explicit click-like command",
+		"keyboard type/inserttext and keyboard shortcuts other than Enter/Return",
+		"semanticAction and job/qa compiled plans unless their batch stdin contains a covered step",
+	],
+} as const;
+
+function normalizeTargetText(value: string): string {
+	return value
+		.replace(/[_-]+/g, " ")
+		.replace(/[\[\]{}()#.'\"=:/]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export function matchesFinalActionLabel(value: string | undefined): boolean {
+	return value !== undefined && FINAL_ACTION_PATTERN.test(normalizeTargetText(value));
+}
+
+function parseRefId(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim();
+	const candidate = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed.startsWith("ref=") ? trimmed.slice(4) : trimmed;
+	return /^e\d+$/.test(candidate) ? candidate : undefined;
+}
+
+function getRefTargetLabel(refSnapshot: SessionRefSnapshot | undefined, refId: string | undefined): string | undefined {
+	if (!refId) return undefined;
+	const ref = refSnapshot?.refs?.[refId];
+	return ref ? [ref.role, ref.name].filter(Boolean).join(" ") : undefined;
+}
+
+function getFlagValue(tokens: string[], flag: string): string | undefined {
+	for (const [index, token] of tokens.entries()) {
+		if (token === flag) return tokens[index + 1];
+		if (token.startsWith(`${flag}=`)) return token.slice(flag.length + 1);
+	}
+	return undefined;
+}
+
+function getClickLikeTargetLabel(command: string[], refSnapshot: SessionRefSnapshot | undefined): string | undefined {
+	const target = command[1];
+	return getRefTargetLabel(refSnapshot, parseRefId(target)) ?? target;
+}
+
+function getFindClickTargetLabel(command: string[]): string | undefined {
+	if (command[0] !== "find") return undefined;
+	const actionIndex = command.findIndex((token, index) => index >= 3 && FIND_CLICK_ACTIONS.has(token));
+	if (actionIndex === -1) return undefined;
+	return getFlagValue(command, "--name") ?? command[2];
+}
+
+function getKeyboardSubmitKey(command: string[]): string | undefined {
+	const commandName = command[0];
+	if (commandName === "press" || commandName === "key") return command[1];
+	return undefined;
+}
+
+function collectActionsFromCommand(command: string[], refSnapshot: SessionRefSnapshot | undefined, stepIndex?: number): BrowserFinalizingAction[] {
+	const actions: BrowserFinalizingAction[] = [];
+	if (CLICK_LIKE_COMMANDS.has(command[0] ?? "")) {
+		actions.push({
+			command,
+			kind: "click-like",
+			stepIndex,
+			targetLabel: getClickLikeTargetLabel(command, refSnapshot),
+		});
+		return actions;
+	}
+	if (command[0] === "find") {
+		const actionIndex = command.findIndex((token, index) => index >= 3 && FIND_CLICK_ACTIONS.has(token));
+		if (actionIndex !== -1) {
+			actions.push({
+				command,
+				kind: "click-like",
+				stepIndex,
+				targetLabel: getFindClickTargetLabel(command),
+			});
+		}
+		return actions;
+	}
+	const submitKey = getKeyboardSubmitKey(command)?.trim().toLowerCase();
+	if (submitKey && KEYBOARD_SUBMIT_KEYS.has(submitKey)) {
+		actions.push({
+			command,
+			kind: "keyboard-submit",
+			stepIndex,
+			targetLabel: submitKey,
+		});
+	}
+	return actions;
+}
+
+export function collectBrowserFinalizingActions(options: {
+	commandTokens: string[];
+	refSnapshot?: SessionRefSnapshot;
+	stdin?: string;
+}): BrowserFinalizingAction[] {
+	const actions = collectActionsFromCommand(options.commandTokens, options.refSnapshot);
+	if (options.commandTokens[0] !== "batch") return actions;
+	for (const { index, step } of parseValidBatchStepEntries(options.stdin)) {
+		actions.push(...collectActionsFromCommand(step, options.refSnapshot, index));
+	}
+	return actions;
+}
+
+export function shouldBlockFinalizingAction(action: BrowserFinalizingAction): boolean {
+	if (action.kind === "keyboard-submit") return true;
+	return matchesFinalActionLabel(action.targetLabel);
+}
+
+export function findBlockedFinalizingAction(options: {
+	commandTokens: string[];
+	refSnapshot?: SessionRefSnapshot;
+	stdin?: string;
+}): BrowserFinalizingAction | undefined {
+	for (const action of collectBrowserFinalizingActions(options)) {
+		if (!shouldBlockFinalizingAction(action)) continue;
+		return action;
+	}
+	return undefined;
+}

package/extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts

@@ -0,0 +1,149 @@
+import { isRecord } from "../../parsing.js";
+import { redactSensitiveText } from "../../runtime.js";
+import { withOptionalSessionArgs, type AgentBrowserNextAction } from "../../results/next-actions.js";
+import { runSessionCommandData } from "./session-state.js";
+import type { ClickDispatchDiagnostic, ClickDispatchProbe, ClickDispatchProbeTarget } from "./types.js";
+
+const CLICK_DISPATCH_MARKER_PREFIX = "__piAgentBrowserClickDispatchProbe_";
+const CLICK_DISPATCH_CLEANUP_TIMEOUT_MS = 2_000;
+
+function parseClickRefId(selector: string): string | undefined {
+	const trimmed = selector.trim();
+	const candidate = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed.startsWith("ref=") ? trimmed.slice(4) : trimmed;
+	return /^e\d+$/.test(candidate) ? candidate : undefined;
+}
+
+function getClickDispatchSelectorTarget(commandTokens: string[]): ClickDispatchProbeTarget | undefined {
+	if (commandTokens[0] !== "click" || commandTokens.includes("--new-tab")) return undefined;
+	const selector = commandTokens[1];
+	if (!selector || selector.startsWith("-")) return undefined;
+	if (parseClickRefId(selector)) return undefined;
+	if (selector.startsWith("xpath=")) return { kind: "xpath", selector: selector.slice("xpath=".length) };
+	return { kind: "selector", selector };
+}
+
+function getEvalResultRecord(data: unknown): Record<string, unknown> | undefined {
+	return isRecord(data) && isRecord(data.result) ? data.result : undefined;
+}
+
+function buildClickDispatchProbeInstallScript(probe: ClickDispatchProbe): string {
+	const target = probe.target;
+	const resolveTarget = target.kind === "selector"
+		? `(() => { try { return document.querySelector(${JSON.stringify(target.selector)}); } catch { return null; } })()`
+		: `(() => { try { return document.evaluate(${JSON.stringify(target.selector)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue; } catch { return null; } })()`;
+	return `(() => {
+const marker = ${JSON.stringify(probe.marker)};
+const element = ${resolveTarget};
+if (!element) return { status: "target-not-found", marker };
+const state = { events: [], target: { tagName: element.tagName.toLowerCase() } };
+const eventTypes = ["pointerdown", "mousedown", "pointerup", "mouseup", "click"];
+const listeners = eventTypes.map((type) => {
+  const listener = (event) => {
+    const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+    const eventTarget = event.target;
+    const targetMatched = path.includes(element) || eventTarget === element || (eventTarget instanceof Node && element.contains(eventTarget));
+    state.events.push({ type: event.type, isTrusted: event.isTrusted === true, targetMatched });
+  };
+  document.addEventListener(type, listener, true);
+  return [type, listener];
+});
+state.cleanup = () => listeners.forEach(([type, listener]) => document.removeEventListener(type, listener, true));
+window[marker] = state;
+return { status: "installed", marker, target: state.target };
+})()`;
+}
+
+function buildClickDispatchProbeCheckScript(probe: ClickDispatchProbe): string {
+	return `(() => {
+const marker = ${JSON.stringify(probe.marker)};
+const state = window[marker];
+const finish = (payload) => {
+  if (state && typeof state.cleanup === "function") state.cleanup();
+  try { delete window[marker]; } catch {}
+  return payload;
+};
+if (!state || !Array.isArray(state.events)) return finish({ status: "probe-missing", nativeEventCount: 0 });
+const nativeEventCount = state.events.filter((event) => event && event.isTrusted === true && event.targetMatched === true).length;
+if (nativeEventCount > 0) return finish({ status: "native-event-observed", nativeEventCount, target: state.target });
+return finish({ status: "no-native-event-observed", nativeEventCount, target: state.target });
+})()`;
+}
+
+function buildClickDispatchProbeCleanupScript(probe: ClickDispatchProbe): string {
+	return `(() => {
+const marker = ${JSON.stringify(probe.marker)};
+const state = window[marker];
+if (state && typeof state.cleanup === "function") state.cleanup();
+try { delete window[marker]; } catch {}
+return { status: "cleaned-up" };
+})()`;
+}
+
+function redactClickDispatchTarget(target: ClickDispatchProbeTarget): ClickDispatchProbeTarget {
+	return target.kind === "selector" || target.kind === "xpath"
+		? { ...target, selector: redactSensitiveText(target.selector) }
+		: target;
+}
+
+export function formatClickDispatchDiagnosticText(diagnostic: ClickDispatchDiagnostic): string {
+	return `Click dispatch diagnostic: ${diagnostic.summary}`;
+}
+
+export function buildClickDispatchNextActions(options: { commandTokens: string[]; sessionName?: string }): AgentBrowserNextAction[] {
+	const retryArgs = options.commandTokens[0] === "click" ? options.commandTokens : ["click", ...options.commandTokens];
+	return [
+		{
+			id: "inspect-click-dispatch-miss",
+			params: { args: withOptionalSessionArgs(options.sessionName, ["snapshot", "-i"]) },
+			reason: "Refresh interactive refs and verify the intended click target before retrying upstream click.",
+			safety: "Read-only snapshot; the wrapper does not replay clicks in-page when upstream reports success without DOM events.",
+			tool: "agent_browser",
+		},
+		{
+			id: "retry-click-after-dispatch-miss",
+			params: { args: withOptionalSessionArgs(options.sessionName, retryArgs) },
+			reason: "Retry the same upstream click after confirming the target is visible; do not assume the prior success mutated the page.",
+			safety: "Only retry when the target is still intended; use page-change evidence or a fresh snapshot before continuing the workflow.",
+			tool: "agent_browser",
+		},
+	];
+}
+
+export async function prepareClickDispatchProbe(options: { commandTokens: string[]; cwd: string; sessionName?: string; signal?: AbortSignal }): Promise<ClickDispatchProbe | undefined> {
+	if (!options.sessionName || options.commandTokens[0] !== "click" || options.commandTokens.includes("--new-tab")) return undefined;
+	const target = getClickDispatchSelectorTarget(options.commandTokens);
+	if (!target) return undefined;
+	const probe: ClickDispatchProbe = { marker: `${CLICK_DISPATCH_MARKER_PREFIX}${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`, target };
+	const installData = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, stdin: buildClickDispatchProbeInstallScript(probe) });
+	const installResult = getEvalResultRecord(installData);
+	return installResult?.status === "installed" ? probe : undefined;
+}
+
+export async function collectClickDispatchDiagnostic(options: { cwd: string; probe?: ClickDispatchProbe; sessionName?: string; signal?: AbortSignal }): Promise<ClickDispatchDiagnostic | undefined> {
+	if (!options.probe || !options.sessionName) return undefined;
+	const data = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, stdin: buildClickDispatchProbeCheckScript(options.probe) });
+	const result = getEvalResultRecord(data);
+	if (!result) return undefined;
+	const status = typeof result.status === "string" ? result.status : undefined;
+	if (status !== "no-native-event-observed") return undefined;
+	const nativeEventCount = typeof result.nativeEventCount === "number" ? result.nativeEventCount : 0;
+	const summary = "Upstream click reported success but no trusted DOM event reached the selected element. Gather evidence with snapshot or page-change checks, then retry upstream click or report the workflow issue; the wrapper does not replay clicks in-page.";
+	return {
+		nativeEventCount,
+		reason: "native-click-produced-no-target-dom-event",
+		status,
+		summary,
+		target: redactClickDispatchTarget(options.probe.target),
+	};
+}
+
+export async function cleanupClickDispatchProbe(options: { cwd: string; probe?: ClickDispatchProbe; sessionName?: string }): Promise<void> {
+	if (!options.probe || !options.sessionName) return;
+	await runSessionCommandData({
+		args: ["eval", "--stdin"],
+		cwd: options.cwd,
+		sessionName: options.sessionName,
+		stdin: buildClickDispatchProbeCleanupScript(options.probe),
+		timeoutMs: CLICK_DISPATCH_CLEANUP_TIMEOUT_MS,
+	}).catch(() => undefined);
+}

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

@@ -1,8 +1,9 @@
-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";
@@ -20,12 +21,14 @@ 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,
@@ -238,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);
@@ -314,8 +300,21 @@ export async function collectOverlayBlockerDiagnostic(options: { command?: strin
 	return { candidates, snapshot, summary: `Click completed but the page stayed on ${currentUrl}; a fresh snapshot contains likely overlay close/dismiss controls.` };
 }
 
+const SELECTOR_TEXT_VISIBILITY_CANDIDATE_LIMIT = 8;
+
 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({ selector, matchCount: matches.length, visibleCount: visible.length, firstMatchVisible: matches[0] ? isVisible(matches[0]) : undefined, firstTextPreview: trim(matches[0]?.textContent), firstVisibleTextPreview: trim(visible[0]?.textContent) });\n})()`;
+	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  const describeCandidate = (element) => {\n    const index = matches.indexOf(element);\n    const role = element.getAttribute('role');\n    const candidate = { index, tagName: element.tagName.toLowerCase(), textPreview: trim(element.textContent) };\n    if (role) candidate.role = role;\n    return candidate;\n  };\n  const visibleCandidates = visible.slice(0, ${SELECTOR_TEXT_VISIBILITY_CANDIDATE_LIMIT}).map(describeCandidate);\n  return JSON.stringify({ selector, matchCount: matches.length, visibleCount: visible.length, firstMatchVisible: matches[0] ? isVisible(matches[0]) : undefined, firstTextPreview: trim(matches[0]?.textContent), firstVisibleTextPreview: trim(visible[0]?.textContent), visibleCandidates });\n})()`;
+}
+
+function parseSelectorTextVisibilityCandidates(value: unknown): SelectorTextVisibilityDiagnostic["visibleCandidates"] {
+	if (!Array.isArray(value)) return undefined;
+	const candidates = value.flatMap((entry): NonNullable<SelectorTextVisibilityDiagnostic["visibleCandidates"]> => {
+		if (!isRecord(entry) || typeof entry.index !== "number" || typeof entry.tagName !== "string") return [];
+		const role = typeof entry.role === "string" && entry.role.length > 0 ? entry.role : undefined;
+		const textPreview = typeof entry.textPreview === "string" && entry.textPreview.length > 0 ? redactSensitiveText(entry.textPreview) : undefined;
+		return [{ index: entry.index, tagName: entry.tagName, ...(role ? { role } : {}), ...(textPreview ? { textPreview } : {}) }];
+	});
+	return candidates.length > 0 ? candidates : undefined;
 }
 
 function parseSelectorTextVisibilityProbe(data: unknown, selector: string): Omit<SelectorTextVisibilityDiagnostic, "summary"> | undefined {
@@ -327,7 +326,14 @@ function parseSelectorTextVisibilityProbe(data: unknown, selector: string): Omit
 	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 };
+	return {
+		firstMatchVisible: typeof parsed.firstMatchVisible === "boolean" ? parsed.firstMatchVisible : undefined,
+		firstVisibleTextPreview: typeof parsed.firstVisibleTextPreview === "string" && parsed.firstVisibleTextPreview.length > 0 ? redactSensitiveText(parsed.firstVisibleTextPreview) : undefined,
+		matchCount,
+		selector,
+		visibleCandidates: parseSelectorTextVisibilityCandidates(parsed.visibleCandidates),
+		visibleCount,
+	};
 }
 
 function selectorMayExposeSensitiveLiteral(selector: string): boolean {
@@ -380,6 +386,14 @@ export function formatSelectorTextVisibilityText(diagnostics: SelectorTextVisibi
 		const actionId = index === 0 ? "inspect-visible-text-candidates" : `inspect-visible-text-candidates-${index + 1}`;
 		const lines = [`Selector text visibility warning: ${diagnostic.summary}`];
 		if (diagnostic.firstVisibleTextPreview) lines.push(`First visible text preview: ${JSON.stringify(diagnostic.firstVisibleTextPreview)}`);
+		if (diagnostic.visibleCandidates && diagnostic.visibleCandidates.length > 0) {
+			lines.push(`Visible candidates (${diagnostic.visibleCandidates.length} shown, querySelectorAll index):`);
+			for (const candidate of diagnostic.visibleCandidates) {
+				const rolePart = candidate.role ? ` role=${candidate.role}` : "";
+				const previewPart = candidate.textPreview ? `: ${JSON.stringify(candidate.textPreview)}` : "";
+				lines.push(`- [${candidate.index}] ${candidate.tagName}${rolePart}${previewPart}`);
+			}
+		}
 		lines.push(`Next action: use details.nextActions ${actionId} before trusting this selector text.`);
 		return lines;
 	}).join("\n");
@@ -465,8 +479,24 @@ export function formatEvalStdinHintText(hint: ReturnType<typeof getEvalStdinHint
 	return hint ? `Eval stdin hint: ${hint.reason} ${hint.suggestion}` : undefined;
 }
 
+export function getEvalResultWarning(options: { command?: string; data: unknown; navigationSummary?: { url?: string }; pageUrl?: string; stdin?: string }) {
+	if (options.command !== "eval" || !options.stdin?.trim() || !isRecord(options.data) || options.data.result !== null) return undefined;
+	const pageUrl = options.pageUrl?.trim() ?? options.navigationSummary?.url?.trim() ?? extractNavigationSummaryFromData(options.data)?.url;
+	if (!pageUrl || !/^file:/i.test(pageUrl)) return undefined;
+	const trimmed = options.stdin.trim();
+	if (/^(?:null|undefined)$/i.test(trimmed)) return undefined;
+	return {
+		reason: "eval --stdin returned null on a file:// page; upstream may not expose full DOM semantics for local fixtures.",
+		suggestion: "Treat this as inconclusive verification. Use snapshot -i, get text on current @refs, screenshot evidence, or a reachable http(s) fixture before concluding DOM state.",
+	};
+}
+
+export function formatEvalResultWarningText(warning: ReturnType<typeof getEvalResultWarning>): string | undefined {
+	return warning ? `Eval result warning: ${warning.reason} ${warning.suggestion}` : undefined;
+}
+
 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>();
@@ -505,7 +535,7 @@ async function collectElectronManagedSessionUrl(options: { cwd: string; sessionN
 	return urlResult.error ? { error: urlResult.error } : { url };
 }
 
-async function collectElectronManagedSessionTarget(options: { cwd: string; sessionName?: string; signal?: AbortSignal; timeoutMs?: number }): Promise<QaAttachedTarget | undefined> {
+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 }),
@@ -647,11 +677,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 {
@@ -709,7 +735,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;
 }