pi-agent-browser-native 0.6.6 → 0.6.8

package/dist/extensions/agent-browser/lib/playbook.js

@@ -13,7 +13,7 @@ export const QUICK_START_GUIDELINES = [
     "Common first calls (first-call recipe): { args: [\"open\", \"<url>\"] } → { args: [\"snapshot\", \"-i\"] } → { args: [\"click\", \"@eN\"] } or { args: [\"fill\", \"@eN\", \"<text>\"] } using @refs and visible labels from that snapshot, then { args: [\"snapshot\", \"-i\"] } after navigation or DOM changes. On https://example.com/ the main link label is Learn more (use exact snapshot text, not guessed link copy).",
     "Locator-first clicks/fills and native select changes without hand-building argv: { semanticAction: { action: \"click\", locator: \"text\", value: \"Close\" } }, { semanticAction: { action: \"fill\", locator: \"label\", value: \"Email\", text: \"user@example.com\" } }, direct current targets such as { semanticAction: { action: \"fill\", selector: \"@e1\", text: \"prompt\" } }, or { semanticAction: { action: \"select\", selector: \"#flavor\", value: \"chocolate\" } }; add semanticAction.session when targeting a named upstream browser session; details.compiledSemanticAction shows the semantic target, while details.effectiveArgs may show a resolved current @ref for active-session role/name click/check/fill actions to avoid hidden duplicate matches; semanticAction does not expose uncheck while upstream find ... uncheck is not runtime-supported, so use raw uncheck with a stable selector or current ref; selector-not-found failures may append bounded click try-*-candidate next actions or, for fill misses with current editable refs, details.richInputRecovery with focus/click actions that do not copy fill text; stale-ref failures can return retry-semantic-action-after-stale-ref for compiled find actions when retry safety is provable.",
     `Common advanced calls: { args: ["batch", "--bail"], stdin: "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }, { job: { steps: [{ action: "open", url: "https://example.com" }, { action: "assertText", text: "Example Domain" }, { action: "screenshot", path: ".dogfood/example.png" }] } }, { qa: { url: "https://example.com", expectedText: "Example Domain", screenshotPath: ".dogfood/qa-example.png" } } (example.com smoke only; elsewhere match exact visible text from snapshot -i), { electron: { action: "list", query: "code" } }, { electron: { action: "launch", appName: "Visual Studio Code", handoff: "snapshot" } }, { electron: { action: "probe" } }, { qa: { attached: true, expectedText: "Explorer" } }, { args: ["eval", "--stdin"], stdin: "document.title", outputPath: "logs/page-title.json" }, { args: ["auth", "save", "name", "--password-stdin"], stdin: "<password from user-approved secret source>" }, { args: ["--profile", "Default", "open", "https://example.com/account"], sessionMode: "fresh" }, and { args: ["open", "--enable", "react-devtools", "https://example.com"], sessionMode: "fresh" }. For app pages with a native dropdown, job steps can include { action: "select", selector: "#flavor", value: "chocolate" } before the dependent assertion; for locator-friendly pages, job click/fill steps can use semantic locator fields such as { action: "fill", locator: "role", role: "searchbox", name: "Search", text: "agent browser" }; for human-paced input, job type steps can use { action: "type", selector: "#prompt", text: "hello", delayMs: 20, press: "Enter" }; delayed typing is capped at 200 characters per step, and generated per-character rows are compacted in visible batch prose while full rows remain in details.batchSteps.`,
-    "Constrained job navigation is explicit only: click (and select/submit flows that may navigate) does not prove the next page loaded; add an assertUrl that does not already match the starting page and/or assertText for new page state after navigation-prone steps before screenshot or later interactions. Keep jobs short around navigation, click, and rerender boundaries on dynamic React/product apps; avoid a whole checkout in one job. If a long job times out and details.timeoutPartialProgress shows a mutating incomplete step, inspect current page state and continue with a shorter job or single action instead of blindly retrying the mutating step. Example: { job: { steps: [{ action: \"open\", url: \"https://shop.example/checkout\" }, { action: \"fill\", selector: \"#email\", text: \"user@example.com\" }, { action: \"click\", selector: \"#continue\" }, { action: \"assertUrl\", url: \"**/shipping\" }, { action: \"assertText\", text: \"Shipping address\" }, { action: \"screenshot\", path: \".dogfood/shipping.png\" }] } }. Top-level click may add pageChangeSummary hints, but job never auto-inserts post-click asserts.",
+    "Constrained job navigation is explicit only: click (and select/submit flows that may navigate) does not prove the next page loaded; add an assertUrl that does not already match the starting page and/or assertText for new page state after navigation-prone steps before screenshot or later interactions. assertText takes only text, not selector or locator fields. Clicks can stale subsequent @refs: split the job and re-snapshot before using those refs. Keep jobs short around navigation, click, and rerender boundaries on dynamic React/product apps; avoid a whole checkout in one job. If a long job times out and details.timeoutPartialProgress shows a mutating incomplete step, inspect current page state and continue with a shorter job or single action instead of blindly retrying the mutating step. Example: { job: { steps: [{ action: \"open\", url: \"https://shop.example/checkout\" }, { action: \"fill\", selector: \"#email\", text: \"user@example.com\" }, { action: \"click\", selector: \"#continue\" }, { action: \"assertUrl\", url: \"**/shipping\" }, { action: \"assertText\", text: \"Shipping address\" }, { action: \"screenshot\", path: \".dogfood/shipping.png\" }] } }. Top-level click may add pageChangeSummary hints, but job never auto-inserts post-click asserts.",
     "High-value command reference: click <selector> --new-tab opens link-like targets in a new tab; select <selector> <value...> changes native dropdown values; wrapper-handled scroll <dir> [px|percent] and scroll to end/top target document scrolling before upstream fallback, while scroll <selector> <dir> [px|percent] targets nested scrollers; download <selector> <path> saves a file triggered by a click; read [url] returns agent-readable text (explicit URLs prefer markdown without requiring a Chrome page; omit the URL for rendered active-tab DOM); get title/url need no selector; get text/html/value/count <selector> and get attr <selector> <name> read elements/page state (use body for whole-page text/html); screenshot [selector] [path] captures a page or element image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab; react tree, react inspect <fiberId>, react renders start/stop, and react suspense introspect React after --enable react-devtools; vitals [url] measures Core Web Vitals; pushstate <url> performs SPA navigation; tap <selector> and swipe <direction> [distance] support iOS/provider touch flows.",
     "For artifact-producing commands, read the visible artifact block and details.artifactVerification before using files: check requested path, absolute path, existence, size bytes, artifact kind, optional mediaType, status, optional limitation, and verified/missing/pending/unverified counts. details.artifacts contains per-file metadata; record start rows are pending/openRecording until record stop writes the target. Upstream record start uses a fresh active page for video capture, so prior in-page DOM and JavaScript state does not carry over; the wrapper blocks prior @e… refs as stale-ref even when the start fails as already-active, and record restart with a URL navigates and invalidates the same way (plain record restart keeps the page), so take a fresh snapshot before continuing. The wrapper creates parent directories for direct artifact paths and can save simple loopback HTTP(S) anchor downloads directly to the requested path before upstream download fallback. Browser close does not delete explicit saved files; if close reports details.artifactCleanup, use host file tools to remove paths listed in explicitArtifactPaths (when non-empty) after inspection. If close fails with details.promptGuard.reason=requested-artifacts-missing-before-close, save the exact required artifact path before closing. A bare inbound image/video path is not a requested output artifact and does not block close. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step; if annotation labels crowd a dense page, use a scoped or non-annotated screenshot plus snapshot refs instead.",
     "When failure output shows Next actions, prefer those exact native agent_browser follow-up payloads over guessed commands. The same actions are available in details.nextActions to callers that expose structured details; short stdin is shown inline, while long stdin stays details-only.",
@@ -46,14 +46,14 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "For Electron desktop apps, prefer top-level electron for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: \"tabs\" is the safer diagnostic starting point, use electron.probe or snapshot -i/qa.attached for current-session state, and always cleanup the returned launchId when done. electron.launch uses an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; after connect, run get url to verify the active target before page-content reads, inspect tab list, select the stable tab id such as tab t2, verify it again with get url, then run a condition wait or snapshot -i before using refs. close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; leave manually launched app shutdown, profile cleanup, and explicit artifacts to the host owner.",
     "For provider or specialized app workflows, load version-matched upstream guidance with skills get agentcore|electron|slack|dogfood|vercel-sandbox|derive-client through the native tool; add --full when you need references/templates, and use skills get --all only for broad skill audits. Use derive-client when recording HAR traffic to generate a standalone API client; prefer network har start (text bodies by default) or network har start --content all|none before multi-step capture. For accessibility audits use a11y or a11y --tags wcag2a,wcag2aa (CDP browsers only). Hosted sandbox workflows should use upstream @agent-browser/sandbox helpers outside this wrapper. Provider launches such as -p ios, --provider browserbase/kernel/browseruse/browserless/agentcore, and iOS --device are upstream-owned setup paths; use sessionMode fresh when switching providers and expect external credentials or local Appium/Xcode setup to be required.",
     "For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; dialog commands and eval snippets that look like alert/confirm/prompt/dialog triggers are shorter-bounded than normal browser calls, and timed-out dialog-like interactions may add inspect-dialog-after-timeout, dismiss-dialog-after-timeout, or recover-fresh-session-after-dialog-timeout nextActions. When --confirm-actions produces a pending confirmation, use details.nextActions or exact confirm <id> / deny <id> calls instead of inventing ids.",
-    "If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or qa.attached; for disappearance checks, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use electron.probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort: use explicit --timeout or top-level timeoutMs for legitimately slow waits, and treat a successful payload like \"waited\":\"timeout\" as elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.",
+    "If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or qa.attached; for disappearance checks, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use electron.probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort: their duration is positional (wait <ms>, not wait --time <ms>). Use explicit --timeout or top-level timeoutMs for legitimately slow waits, and treat a successful payload like \"waited\":\"timeout\" as elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.",
     "For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.",
     "For read-only browsing tasks, use read <url> for documentation or other unstructured text without requiring a Chrome page, or read with no URL for rendered active-tab DOM. Prefer the current snapshot, structured ref labels, getters, or scoped eval --stdin when you need interactive structure or targeted page state. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.",
     "For downloads, prefer download <selector> <path> when an element click should save a file; simple loopback anchor downloads are saved to the requested path when the wrapper can resolve an HTTP(S) href. Do not rely on click alone when you need the downloaded file on disk.",
-    "On dashboards with nested scroll containers, verify scroll with a screenshot or fresh snapshot -i; if the viewport did not move, details.data.scrolled may be false/noMovement true and you should prefer scrollintoview <@ref> or target the actual scrollable region with scroll <selector> <dir> [px|percent]. For native selects, use select <selector> <value...> (or semanticAction/job select) instead of clicking option refs; for custom comboboxes, a click/semanticAction may only focus the field, so re-snapshot and fall back to type, press Enter/arrow keys, or visible option refs.",
+    "On dashboards with nested scroll containers, verify scroll with a screenshot or fresh snapshot -i; if the viewport did not move, details.data.scrolled may be false/noMovement true and you should prefer scrollintoview <@ref> or target the actual scrollable region with scroll <selector> <dir> [px|percent]. For native selects, use select <selector> <value...> (or semanticAction/job select) instead of clicking option refs; for custom comboboxes, a click/semanticAction may only focus the field, so re-snapshot and use keyboard type <text> for focused input, press ArrowDown or press Enter, or visible option refs. Raw type requires both <selector> and <text>.",
     "When using eval --stdin, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.",
     "When using eval --stdin for extraction, pass the JavaScript through the native tool stdin field, not as an extra args token after --stdin, and return the value you want instead of relying on console.log as the primary result channel. Prefer plain expressions like ({ title: document.title }) or explicitly invoked functions like (() => ({ title: document.title }))(); use outputPath when the eval/get/snapshot data should be saved as a durable local file, but never reuse a screenshot, download, recording, or other browser artifact destination as outputPath. If a function-shaped snippet returns {}, details.evalStdinHint may warn that the function was serialized instead of called. Local file pages and caller-selected output paths are supported when upstream allows them. If get text on a broad CSS selector surfaces details.selectorTextVisibility or selectorTextVisibilityAll, prefer a visible @ref, a more specific selector, or the inspect-visible-text-candidates nextAction over hidden tab content.",
-    "When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone. If details.clickDispatch reports a click-dispatch miss, refresh/inspect/retry the real click first; for static local fixtures only, an explicit eval --stdin programmatic .click() can exercise app handlers, but treat it as an untrusted scripted workaround and never use it to bypass stop-before-submit/order/purchase boundaries. If a no-navigation click surfaces details.overlayBlockers, inspect the fresh snapshot evidence before using a close/dismiss candidate nextAction; ordinary page chrome without dialog/alertdialog evidence should not trigger this diagnostic.",
+    "When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone. If details.clickDispatch reports a click-dispatch miss, refresh/inspect/retry the real click first; for static local fixtures only, an explicit eval --stdin programmatic .click() can exercise app handlers, but treat it as an untrusted scripted workaround and never use it to bypass stop-before-submit/order/purchase boundaries. If an upstream click failure says the target is covered by another element at the target's click point, use the inspect-overlay-state nextAction to refresh refs and inspect the blocker before deciding whether to retry; do not blindly repeat the blocked click. If a no-navigation click surfaces details.overlayBlockers, inspect the fresh snapshot evidence before using a close/dismiss candidate nextAction; ordinary page chrome without dialog/alertdialog evidence should not trigger this diagnostic.",
     "When commands save or spill files (screenshots, downloads, PDFs, traces, recordings, HAR, large snapshot spills), use the user's exact requested paths when given and treat paths as provisional until details.artifactVerification shows every row verified: branch on missingCount, pendingCount, unverifiedCount, per-entry state, and optional limitation before downstream file use or PASS/FAIL reporting.",
     "For evidence-only screenshots, QA captures, or other audit artifacts, save to an explicit path and branch on details.artifactVerification plus details.artifacts before reporting PASS/FAIL; do not require vision review of inline image attachments unless the user asked for visual inspection.",
     "Respect explicit user stop boundaries yourself. When the surrounding authenticated employee or automation context is explicitly unattended/auto-approved, ordinary non-destructive form submissions within the requested flow may proceed without separate confirmation. Still require explicit authorization for purchases, production-control actions, destructive or irreversible actions, and account, security, or privacy changes. The wrapper does not infer broad business intent from prompt text; details.promptGuard is reserved for concrete artifact-before-close checks.",
@@ -62,10 +62,6 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 ];
 export const TOOL_PROMPT_GUIDELINES_SUFFIX = [
     "Prefer agent_browser over bash, osascript, AppleScript, or generic browser shell for sites, docs, clicks, fills, screenshots, eval, and batch.",
-    "Pass exact agent-browser CLI arguments in agent_browser args when you are not using script, semanticAction, job, or qa, excluding the binary name and --json (agent_browser injects --json automatically).",
-    "Use top-level agent_browser stdin only for eval --stdin, batch, auth save --password-stdin, or wrapper-generated job/qa batches instead of shell heredocs or password args; script puts any inner stdin on browser({ stdin }), and other command/stdin combinations are rejected before launch.",
-    `Let the agent_browser extension-managed session handle the common path unless you explicitly need a fresh launch for launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}).`,
-    "Use agent_browser sessionMode=fresh when switching from an existing implicit session to a new profile/browser executable/debug/init-script/provider launch without inventing a fixed explicit session name; later auto calls will follow that new session.",
 ];
 export const INSPECTION_TOOL_CALL_EXAMPLES = [
     '{ "args": ["--help"] }',
@@ -73,7 +69,8 @@ export const INSPECTION_TOOL_CALL_EXAMPLES = [
 ];
 export const WRAPPER_TAB_RECOVERY_BEHAVIOR = [
     "After open/goto/navigate calls with --profile, --restore, --session-name, or --state, agent_browser best-effort re-selects the tab whose URL matches the returned page when restored tabs steal focus during launch or reconnect.",
-    "After the wrapper observes tab-drift risk for a session (for example open correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab or ref snapshot is known.",
+    "After confirmed shutdown of an automatically restored managed session, the wrapper retains its complete recorded URL, including the fragment, until the first current-page operation (including get url and reload). Non-page calls such as tab list or read <url> may start a daemon without fulfilling that reopen. The wrapper uses native open once, verifies the observed tab, and discards old refs/frame scope; it does not restore unsaved forms, JavaScript memory, or history. Explicit navigation, caller-owned/attached sessions, and restore-disabled sessions are not auto-reopened.",
+    "For a still-live browser after tab drift or resume, the wrapper verifies/selects the intended tab before ref/semantic helpers and page commands; failed selection stops the call without navigating. Local commands, read <url>, URL a11y/vitals, diff url, window new, and explicit tab/navigation/connection/state recovery do not require the prior tab. Batch checks follow effective rows past non-page prefixes and stop at explicit context changes, preserving caller argv/stdin and continue-on-error behavior. Same-tab reselection is avoided because it clears refs. Use exact batch --bail for fail-fast, not --bail=<value>. Routine same-session calls skip tab-list preflights.",
     "For sessions with observed tab-drift risk, after a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes. Routine same-session commands skip this post-command tab-list probe.",
     "If a known session target unexpectedly reports about:blank, agent_browser best-effort re-selects the prior intended target when it still exists; if recovery fails, it records the observed about:blank target and reports exact recovery guidance instead of treating the prior page as active.",
     "If upstream reports tab_gone, the pinned bound tab is gone; use details.nextActions (tab list / tab new) instead of assuming another tab is yours.",

package/dist/extensions/agent-browser/lib/process.js

@@ -1,11 +1,11 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn } from "node:child_process";
-import { lstat, mkdir, readdir } from "node:fs/promises";
+import { lstat, mkdir, readdir, readlink, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
 import { env as processEnv, platform as processPlatform } from "node:process";
+import { spawn as crossSpawn } from "cross-spawn";
 import { parseArgvDescriptor } from "./argv-descriptor.js";
-import { isKnownCommandToken } from "./command-taxonomy.js";
-import { extractExplicitSessionName, getFlagName, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, resolveAgentBrowserNamespace, } from "./argv-grammar.js";
+import { extractExplicitSessionName, resolveAgentBrowserNamespace } from "./argv-grammar.js";
 import { commitManagedSessionRestoreSuppression, getManagedSessionRestoreEnv, getManagedSessionRestoreProtectedEnv, getOwnedManagedSessionCompatibilityEnv, getOwnedManagedSessionNamespaceEnv, isOwnedManagedSessionTarget, validateManagedSessionRestoreContextForSpawn, } from "./managed-session-restore.js";
 import { getPageTargetValidationError, } from "./page-target-validation.js";
 import { getImplicitSessionIdleTimeoutMs } from "./runtime.js";
@@ -26,114 +26,19 @@ export const SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS = 25_000;
 const DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS = 35_000;
 /** Grace period after `exit` before resolving when `close` is delayed by inherited stdio handles. */
 const EXIT_STDIO_GRACE_MS = 100;
-const WINDOWS_AGENT_BROWSER_MISSING_MARKER = "PI_AGENT_BROWSER_COMMAND_NOT_FOUND:agent-browser.cmd";
 const attachedBrowserSessionContext = new AsyncLocalStorage();
-const WINDOWS_COMMANDS_WITH_ADJACENT_SUBCOMMAND = new Set([
-    "auth", "clipboard", "cookies", "dashboard", "device", "dialog", "diff", "find", "get", "is", "keyboard",
-    "mouse", "network", "plugin", "profiler", "react", "record", "session", "set", "skills", "state", "storage",
-    "stream", "tab", "trace", "webmcp", "window",
-]);
 export function withAttachedBrowserSessionContext(preserve, run) {
     return attachedBrowserSessionContext.run(preserve || attachedBrowserSessionContext.getStore() === true, run);
 }
-export function getWindowsExplicitDefaultNamespaceEnv(args, parentNamespace, platform = processPlatform) {
-    return platform === "win32" && resolveAgentBrowserNamespace(args, parentNamespace) === ""
-        ? { AGENT_BROWSER_NAMESPACE: "" }
-        : {};
-}
 function appendTail(text, addition, maxChars) {
     const combined = text + addition;
     return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
 }
-function quoteWindowsPowerShellArg(value) {
-    return `'${value.replace(/'/g, "''")}'`;
-}
-/** Exported for unit tests that lock Windows launcher argv ordering. */
-export function reorderWindowsLeadingGlobalArgs(args) {
-    const leadingGlobals = [];
-    for (let index = 0; index < args.length; index += 1) {
-        const token = args[index];
-        if (isKnownCommandToken(token)) {
-            if (index === 0)
-                return args;
-            const firstPositional = args[index + 1];
-            return WINDOWS_COMMANDS_WITH_ADJACENT_SUBCOMMAND.has(token) && firstPositional && !firstPositional.startsWith("-")
-                ? [token, firstPositional, ...leadingGlobals, ...args.slice(index + 2)]
-                : [token, ...leadingGlobals, ...args.slice(index + 1)];
-        }
-        if (!token.startsWith("-"))
-            return args;
-        if (token.startsWith("--restore=")) {
-            leadingGlobals.push(token);
-            continue;
-        }
-        if (token === "--restore") {
-            const value = args[index + 1];
-            if (optionalGlobalValueFlagConsumesNext(token, value)) {
-                leadingGlobals.push(`--restore=${value}`);
-                index += 1;
-            }
-            else {
-                leadingGlobals.push(token);
-            }
-            continue;
-        }
-        if (token.includes("="))
-            return args;
-        const flag = getFlagName(token);
-        if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(flag)) {
-            leadingGlobals.push(token);
-            if (["true", "false"].includes(args[index + 1] ?? "")) {
-                leadingGlobals.push(args[index + 1]);
-                index += 1;
-            }
-            continue;
-        }
-        if (GLOBAL_VALUE_FLAGS.includes(flag)) {
-            const value = args[index + 1];
-            if (value === undefined)
-                return args;
-            // PowerShell -> .cmd drops empty argv values. Planning rejects empty
-            // caller --args; keep this defensive skip so an unexpected empty value
-            // cannot turn the next flag into its accidental value on native Windows.
-            if (value === "" && (flag === "--args" || flag === "--namespace")) {
-                index += 1;
-                continue;
-            }
-            leadingGlobals.push(token, value);
-            index += 1;
-            continue;
-        }
-        return args;
-    }
-    return args;
-}
 export function prepareAgentBrowserSpawnArgs(args, wrapperCompatibilityUserAgent, preserveAttachedBrowserSession = false) {
     if (preserveAttachedBrowserSession || !wrapperCompatibilityUserAgent)
         return args;
     return ["--args", `--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}`, ...args];
 }
-export function buildAgentBrowserSpawnCommand(args, platform = processPlatform) {
-    if (platform !== "win32") {
-        return { command: "agent-browser", args };
-    }
-    const invocationArgs = reorderWindowsLeadingGlobalArgs(args).map(quoteWindowsPowerShellArg).join(" ");
-    const commandLine = [
-        "$agentBrowser = Get-Command agent-browser.cmd -ErrorAction SilentlyContinue;",
-        `if (-not $agentBrowser) { [Console]::Error.WriteLine('${WINDOWS_AGENT_BROWSER_MISSING_MARKER}'); exit 127 };`,
-        `& $agentBrowser.Source ${invocationArgs}`.trimEnd(),
-    ].join(" ");
-    return { command: "powershell.exe", args: ["-NoLogo", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", commandLine] };
-}
-export function isWindowsAgentBrowserCommandMissing(stderr) {
-    const normalized = stderr.toLowerCase();
-    return normalized.includes(WINDOWS_AGENT_BROWSER_MISSING_MARKER.toLowerCase()) || (normalized.includes("agent-browser.cmd") && (normalized.includes("commandnotfoundexception") ||
-        normalized.includes("not recognized as the name of a cmdlet") ||
-        normalized.includes("not recognized as an internal or external command")));
-}
-export function shouldCommitManagedRestoreAfterWindowsProcess(input) {
-    return !input.spawnError && !(input.exitCode !== 0 && isWindowsAgentBrowserCommandMissing(input.stderr));
-}
 function terminateSpawnedChild(child, signal) {
     if (processPlatform === "win32" && child.pid) {
         const killer = spawn("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
@@ -252,13 +157,30 @@ export function isTrustedSocketDirAncestor(metadata, uid, platform = processPlat
         return (mode & 0o022) === 0;
     return metadata.uid === 0 && ((mode & 0o022) === 0 || (mode & 0o1000) !== 0);
 }
-async function hasTrustedSocketDirAncestry(socketDir, uid) {
+async function hasTrustedSocketDirAncestry(socketDir, uid, visited = new Set()) {
     for (let current = dirname(socketDir);;) {
+        current = current.replace(/\/+$/, "") || "/";
+        if (visited.has(current))
+            return true;
+        visited.add(current);
         const metadata = await lstat(current);
+        // The operating environment supplies /; its reported owner may be unmapped in a user namespace.
+        if (current === "/" && metadata.isDirectory() && (metadata.mode & 0o022) === 0)
+            return true;
         if (isTrustedAndroidAppDataRoot(current, metadata, uid))
             return true;
         if (!isTrustedSocketDirAncestor(metadata, uid))
             return false;
+        if (metadata.isSymbolicLink()) {
+            // Native stat rejects broken/cyclic links before walking their destination ancestry.
+            if (!isTrustedSocketDirAncestor(await stat(current), uid))
+                return false;
+            const target = await readlink(current);
+            const targetPath = isAbsolute(target) ? target : `${dirname(current)}/${target}`;
+            // Keep '..' after symlinks intact; '/.' includes the target itself in the parent walk.
+            if (!await hasTrustedSocketDirAncestry(`${targetPath}/.`, uid, visited))
+                return false;
+        }
         const parent = dirname(current);
         if (parent === current)
             return true;
@@ -364,7 +286,7 @@ export function buildAgentBrowserProcessEnv(baseEnv = processEnv, overrides = un
     clampUpstreamDefaultTimeout(childEnv);
     return childEnv;
 }
-function getManagedPreSpawnPolicyError(options, currentPageUrl, pageUrlUnknown = false, trustedFirstBatchTabSelection = false) {
+function getManagedPreSpawnPolicyError(options, currentPageUrl, pageUrlUnknown = false) {
     if (!validateManagedSessionRestoreContextForSpawn(options)) {
         return "Managed session restore policy, storage, or checkout identity changed after planning; refusing to start agent-browser.";
     }
@@ -373,11 +295,10 @@ function getManagedPreSpawnPolicyError(options, currentPageUrl, pageUrlUnknown =
         currentPageUrl,
         pageUrlUnknown,
         stdin: options.stdin,
-        trustedFirstBatchTabSelection,
     });
 }
 export async function runAgentBrowserProcess(options) {
-    const { cwd, env, managedSessionRestoreState, managedStateCurrentPageUrl, managedStatePageUrlUnknown, signal, stdin, trustedFirstBatchTabSelection } = options;
+    const { cwd, env, managedSessionRestoreState, managedStateCurrentPageUrl, managedStatePageUrlUnknown, signal, stdin } = options;
     const preserveAttachedBrowserSession = options.preserveAttachedBrowserSession === true || attachedBrowserSessionContext.getStore() === true;
     const ownedManagedSession = options.ownedManagedSession === true || isOwnedManagedSessionTarget(options.args);
     const args = options.args;
@@ -395,7 +316,7 @@ export async function runAgentBrowserProcess(options) {
         restoreState: managedSessionRestoreState,
         stdin,
     };
-    const planningPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown, trustedFirstBatchTabSelection);
+    const planningPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown);
     if (planningPolicyError) {
         return {
             aborted: false,
@@ -415,7 +336,6 @@ export async function runAgentBrowserProcess(options) {
         ...env,
         ...getManagedSessionRestoreProtectedEnv(managedSessionRestoreOptions, managedSessionRestoreEnv),
         ...getOwnedManagedSessionNamespaceEnv(managedSessionRestoreOptions),
-        ...getWindowsExplicitDefaultNamespaceEnv(args, parentEnv.AGENT_BROWSER_NAMESPACE),
         ...ownedManagedSessionCompatibilityEnv,
     };
     const explicitSocketDir = processOverrides[AGENT_BROWSER_SOCKET_DIR_ENV];
@@ -520,13 +440,8 @@ export async function runAgentBrowserProcess(options) {
                 if (stdoutSpillHandle) {
                     await stdoutSpillHandle.close().catch(() => undefined);
                 }
-                const windowsMissingBinary = processPlatform === "win32" && exitCode !== 0 && isWindowsAgentBrowserCommandMissing(stderr);
-                if (processPlatform === "win32" && !windowsMissingBinary && !spawnError)
+                if (processPlatform === "win32" && !spawnError) {
                     agentBrowserStarted = true;
-                if (windowsMissingBinary && !spawnError) {
-                    spawnError = Object.assign(new Error("spawn agent-browser ENOENT"), { code: "ENOENT" });
-                }
-                else if (processPlatform === "win32" && shouldCommitManagedRestoreAfterWindowsProcess({ exitCode, spawnError, stderr })) {
                     commitManagedSessionRestoreSuppression(managedSessionRestoreOptions);
                 }
                 if (!spawnError && stdoutSpillError) {
@@ -548,13 +463,13 @@ export async function runAgentBrowserProcess(options) {
             });
         };
         const childEnv = buildAgentBrowserProcessEnv(parentEnv, effectiveEnv);
-        const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown, trustedFirstBatchTabSelection);
+        const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown);
         if (spawnPolicyError) {
             resolve({ aborted: false, agentBrowserStarted: false, exitCode: 1, spawnError: new Error(spawnPolicyError), stderr: "", stdout: "", timedOut: false });
             return;
         }
-        const spawnCommand = buildAgentBrowserSpawnCommand(prepareAgentBrowserSpawnArgs(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession));
-        const child = spawn(spawnCommand.command, spawnCommand.args, {
+        const spawnBrowser = processPlatform === "win32" ? crossSpawn : spawn;
+        const child = spawnBrowser("agent-browser", prepareAgentBrowserSpawnArgs(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession), {
             cwd,
             env: childEnv,
             stdio: ["pipe", "pipe", "pipe"],

package/dist/extensions/agent-browser/lib/recording-reservations.js

@@ -1,3 +1,4 @@
+import { isAbsolute } from "node:path";
 import { getAgentBrowserSessionIdentityKey } from "./argv-grammar.js";
 import { isRecord } from "./parsing.js";
 import { isPendingRecordingArtifact } from "./results/artifact-manifest.js";
@@ -80,7 +81,8 @@ function parseReservationTransition(data) {
             state: "closed",
         };
     }
-    if (typeof data.absolutePath !== "string" || typeof data.cwd !== "string" || typeof data.path !== "string")
+    if (typeof data.absolutePath !== "string" || !isAbsolute(data.absolutePath)
+        || typeof data.cwd !== "string" || !isAbsolute(data.cwd) || typeof data.path !== "string")
         return undefined;
     return {
         reservation: {

package/dist/extensions/agent-browser/lib/results/action-recommendations.js

@@ -1,6 +1,6 @@
 import { isOpenNavigationCommand, isPageMutationCommand } from "../command-taxonomy.js";
 import { isPendingRecordingArtifact } from "./artifact-manifest.js";
-import { applySessionToNextActions, buildNextToolAction } from "./next-actions.js";
+import { applySessionToNextActions, buildInspectOverlayStateAction, buildNextToolAction } from "./next-actions.js";
 import { AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS, buildRecoveryNextActions, } from "./recovery-actions.js";
 function buildArtifactAction(path) {
     return {
@@ -223,7 +223,10 @@ export function buildAgentBrowserNextActions(options) {
                 }
                 break;
             case "upstream-error":
-                if (isOpenNavigationCommand(options.command)) {
+                if (options.overlayBlockedClick) {
+                    actions.push(buildInspectOverlayStateAction(options.sessionName));
+                }
+                else if (isOpenNavigationCommand(options.command)) {
                     actions.push(buildNextToolAction({
                         args: ["get", "url"],
                         id: "inspect-page-after-navigation-error",

package/dist/extensions/agent-browser/lib/results/envelope.js

@@ -17,7 +17,7 @@ async function readEnvelopeSource(options) {
         throw new Error(`agent-browser output spill file could not be read: ${message}`);
     }
 }
-function extractEnvelopeErrorText(error) {
+export function extractEnvelopeErrorText(error) {
     if (typeof error === "string") {
         return error.trim() || undefined;
     }
@@ -48,7 +48,8 @@ export async function parseAgentBrowserEnvelope(options) {
         return { parseError: error instanceof Error ? error.message : String(error) };
     }
     const trimmed = stdout.trim();
-    if (trimmed.length === 0) {
+    const plainText = typeof options !== "string" && options.plainText === true;
+    if (trimmed.length === 0 && !plainText) {
         return { parseError: "agent-browser returned no JSON output." };
     }
     try {
@@ -81,6 +82,8 @@ export async function parseAgentBrowserEnvelope(options) {
         return { envelope: parsed };
     }
     catch (error) {
+        if (plainText)
+            return { envelope: { success: true, data: trimmed } };
         const message = error instanceof Error ? error.message : String(error);
         return { parseError: `agent-browser returned invalid JSON: ${message}` };
     }
@@ -149,10 +152,12 @@ export function getAgentBrowserErrorText(options) {
     if (parseError)
         return parseError;
     if (envelope?.success === false) {
-        if ((hasStructuredBatchStepFailure(envelope.data) || detectConfirmationRequired(envelope.data)) && envelope.error === undefined) {
+        const explicitErrorText = extractEnvelopeErrorText(envelope.error);
+        if ((hasStructuredBatchStepFailure(envelope.data) || detectConfirmationRequired(envelope.data)) && explicitErrorText === undefined) {
             return undefined;
         }
-        const envelopeErrorText = extractEnvelopeErrorText(envelope.error);
+        const envelopeErrorText = explicitErrorText
+            ?? extractEnvelopeErrorText(typeof envelope.data === "string" ? envelope.data : isRecord(envelope.data) ? envelope.data.error : undefined);
         if (envelopeErrorText && isUpstreamIpcReadTimeoutMessage(envelopeErrorText)) {
             return buildUpstreamIpcReadTimeoutMessage();
         }

package/dist/extensions/agent-browser/lib/results/next-actions.js

@@ -44,6 +44,14 @@ export function buildNextToolAction(options) {
         tool: "agent_browser",
     };
 }
+export function buildInspectOverlayStateAction(sessionName) {
+    return buildNextToolAction({
+        args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]),
+        id: "inspect-overlay-state",
+        reason: "Refresh interactive refs and inspect whether an overlay, banner, modal, or dialog is blocking the intended click.",
+        safety: "Read-only inspection; do not blindly retry the blocked click, and use current refs from this snapshot before interacting.",
+    });
+}
 export function appendUniqueAgentBrowserNextActions(target, additions) {
     if (!additions || additions.length === 0)
         return target;

package/dist/extensions/agent-browser/lib/results/presentation/artifacts.js

@@ -1,22 +1,43 @@
-import { readFile, stat } from "node:fs/promises";
+import { open, readFile, stat } from "node:fs/promises";
 import { extname, resolve } from "node:path";
 import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
+import { getExplicitArtifactDestination } from "../../orchestration/browser-run/artifact-paths.js";
 import { isRecord, parsePositiveInteger } from "../../parsing.js";
+import { extractUpstreamCommandTokens } from "../../runtime.js";
 import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, isPendingRecordingCommand, mergeSessionArtifactManifest, } from "../artifact-manifest.js";
 import { classifyAgentBrowserSuccessCategory } from "../categories.js";
-const IMAGE_EXTENSION_TO_MIME_TYPE = {
-    ".gif": "image/gif",
-    ".jpeg": "image/jpeg",
-    ".jpg": "image/jpeg",
-    ".png": "image/png",
-    ".webp": "image/webp",
-};
+const PNG_HEADER = Buffer.from("89504e470d0a1a0a0000000d49484452", "hex");
 const INLINE_IMAGE_MAX_BYTES_ENV = "PI_AGENT_BROWSER_INLINE_IMAGE_MAX_BYTES";
 const DEFAULT_INLINE_IMAGE_MAX_BYTES = 5 * 1_024 * 1_024;
 const ARTIFACT_MTIME_TOLERANCE_MS = 2_000;
-function getImageMimeType(filePath) {
-    const extension = extname(filePath).toLowerCase();
-    return IMAGE_EXTENSION_TO_MIME_TYPE[extension];
+function getImageMimeType(bytes) {
+    if (bytes.length < 16)
+        return undefined;
+    if (bytes.subarray(0, 16).equals(PNG_HEADER))
+        return "image/png";
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff && bytes[3] !== 0xf7)
+        return "image/jpeg";
+    if (["GIF87a", "GIF89a"].includes(bytes.toString("utf8", 0, 6)))
+        return "image/gif";
+    if (bytes.toString("utf8", 0, 4) === "RIFF" && bytes.toString("utf8", 8, 12) === "WEBP")
+        return "image/webp";
+    return undefined;
+}
+async function getFileImageMimeType(path) {
+    try {
+        const file = await open(path, "r");
+        try {
+            const bytes = Buffer.alloc(16);
+            const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+            return getImageMimeType(bytes.subarray(0, bytesRead));
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
 }
 function getInlineImageMaxBytes(env = process.env) {
     return parsePositiveInteger(env[INLINE_IMAGE_MAX_BYTES_ENV]) ?? DEFAULT_INLINE_IMAGE_MAX_BYTES;
@@ -74,17 +95,6 @@ const PATH_FIELD_CANDIDATES = [
     "profilePath",
     "videoPath",
 ];
-const ARTIFACT_EXTENSION_TO_MEDIA_TYPE = {
-    ".cpuprofile": "application/json",
-    ".har": "application/json",
-    ".html": "text/html",
-    ".json": "application/json",
-    ".pdf": "application/pdf",
-    ".txt": "text/plain",
-    ".webm": "video/webm",
-    ".zip": "application/zip",
-    ...IMAGE_EXTENSION_TO_MIME_TYPE,
-};
 function isDownloadWaitSubcommand(subcommand) {
     return subcommand === "--download" || subcommand === "-d";
 }
@@ -153,6 +163,7 @@ async function buildFileArtifactMetadata(options) {
     const pendingRecording = isPendingRecordingCommand(options.commandInfo.command, options.commandInfo.subcommand, kind);
     let exists;
     let sizeBytes;
+    let mediaType;
     let stale = false;
     let updatedAtMs;
     if (!pendingRecording) {
@@ -161,6 +172,7 @@ async function buildFileArtifactMetadata(options) {
             exists = true;
             sizeBytes = fileStats.size;
             updatedAtMs = fileStats.mtimeMs;
+            mediaType = fileStats.isFile() ? await getFileImageMimeType(absolutePath) : undefined;
             const commandCreatesArtifact = !(options.commandInfo.command === "wait" && isDownloadWaitSubcommand(options.commandInfo.subcommand));
             stale = commandCreatesArtifact && artifactMtimeIsOutsideCommandWindow(updatedAtMs, options.artifactMinUpdatedAtMs, options.artifactMaxUpdatedAtMs);
         }
@@ -176,11 +188,11 @@ async function buildFileArtifactMetadata(options) {
         exists,
         extension,
         kind,
-        mediaType: extension ? ARTIFACT_EXTENSION_TO_MEDIA_TYPE[extension] : undefined,
+        mediaType,
         namespace: options.namespace,
         path: displayPath,
         recordingState: pendingRecording ? "openRecording" : undefined,
-        requestedPath: options.artifactRequest?.path,
+        requestedPath: options.artifactRequest?.path ?? getExplicitArtifactDestination(extractUpstreamCommandTokens(options.commandInfo.commandTokens ?? [])),
         session: options.sessionName,
         sizeBytes,
         status: pendingRecording ? "pending" : exists === false ? "missing" : stale ? "stale" : options.artifactRequest?.status ?? "saved",
@@ -212,7 +224,7 @@ async function buildPreviousRestartRecordingArtifact(options) {
             exists: true,
             extension: previousRecording.extension ?? (extname(absolutePath).toLowerCase() || undefined),
             kind: "video",
-            mediaType: previousRecording.mediaType,
+            mediaType: fileStats.isFile() ? await getFileImageMimeType(absolutePath) : undefined,
             namespace: previousRecording.namespace ?? options.namespace,
             path: previousRecording.path,
             requestedPath: previousRecording.requestedPath,
@@ -232,7 +244,6 @@ async function buildPreviousRestartRecordingArtifact(options) {
             exists: false,
             extension: previousRecording.extension ?? (extname(absolutePath).toLowerCase() || undefined),
             kind: "video",
-            mediaType: previousRecording.mediaType,
             namespace: previousRecording.namespace ?? options.namespace,
             path: previousRecording.path,
             requestedPath: previousRecording.requestedPath,
@@ -449,13 +460,12 @@ export function formatArtifactMetadataLines(artifacts) {
             return [
                 `${formatArtifactLabel(artifact)}: ${artifact.path}`,
                 `Artifact type: ${artifact.kind}`,
-                `Requested path: ${artifact.requestedPath ?? artifact.path}`,
+                artifact.requestedPath ? `Requested path: ${artifact.requestedPath}` : undefined,
                 `Absolute path: ${artifact.absolutePath}`,
                 "Exists: pending until record stop",
                 `Status: ${artifact.status ?? "pending"}`,
                 `Recording state: ${artifact.recordingState ?? "openRecording"}`,
                 `Will exist on stop: ${artifact.willExistOnStop !== false}`,
-                artifact.subcommand === "start" ? "Page state: record start uses a fresh active page for video capture; prior in-page DOM and JavaScript state does not carry over. Take a fresh snapshot before continuing." : undefined,
                 artifact.session ? `Session: ${artifact.session}` : undefined,
                 artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
                 `Machine data: details.artifacts[${index}]`,
@@ -464,14 +474,14 @@ export function formatArtifactMetadataLines(artifacts) {
         return [
             `${formatArtifactLabel(artifact)}: ${artifact.path}`,
             `Artifact type: ${artifact.kind}`,
-            `Requested path: ${artifact.requestedPath ?? artifact.path}`,
+            artifact.requestedPath ? `Requested path: ${artifact.requestedPath}` : undefined,
             `Absolute path: ${artifact.absolutePath}`,
             `Exists: ${artifact.exists === true}`,
             artifact.exists === false ? "not found on disk" : undefined,
             typeof artifact.sizeBytes === "number" ? `Size: ${formatByteCount(artifact.sizeBytes)}` : undefined,
             typeof artifact.sizeBytes === "number" ? `Size bytes: ${artifact.sizeBytes}` : undefined,
             `Status: ${artifact.status ?? (artifact.exists === false ? "missing" : "saved")}`,
-            artifact.tempPath ? `Temp path: ${artifact.tempPath}` : undefined,
+            artifact.tempPath ? `Reported path: ${artifact.tempPath}` : undefined,
             artifact.mediaType ? `Media type: ${artifact.mediaType}` : undefined,
             artifact.session ? `Session: ${artifact.session}` : undefined,
             artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
@@ -519,21 +529,10 @@ export function extractImagePath(commandInfo, cwd, data) {
     if (!isTrustedScreenshotOutput(commandInfo)) {
         return undefined;
     }
-    if (typeof data === "string") {
-        const mimeType = getImageMimeType(data);
-        return mimeType ? resolve(cwd, data) : undefined;
-    }
-    if (!isRecord(data) || typeof data.path !== "string") {
-        return undefined;
-    }
-    const mimeType = getImageMimeType(data.path);
-    return mimeType ? resolve(cwd, data.path) : undefined;
+    const path = typeof data === "string" ? data : isRecord(data) && typeof data.path === "string" ? data.path : undefined;
+    return path?.trim() && !isNonFileArtifactPathCandidate(path) ? resolve(cwd, path) : undefined;
 }
 export async function attachInlineImage(presentation, imagePath) {
-    const mimeType = getImageMimeType(imagePath);
-    if (!mimeType) {
-        return presentation;
-    }
     try {
         const fileStats = await stat(imagePath);
         const inlineImageMaxBytes = getInlineImageMaxBytes();
@@ -543,6 +542,9 @@ export async function attachInlineImage(presentation, imagePath) {
             return presentation;
         }
         const file = await readFile(imagePath);
+        const mimeType = getImageMimeType(file);
+        if (!mimeType)
+            return presentation;
         presentation.content.push({ type: "image", data: file.toString("base64"), mimeType });
         presentation.imagePath = imagePath;
         return presentation;

package/dist/extensions/agent-browser/lib/results/presentation/batch.js

@@ -13,7 +13,7 @@ import { extractAgentBrowserLifecycle, stringifyModelFacing } from "./common.js"
 import { buildArtifactVerificationSummary, classifyPresentationSuccessCategory, manifestHasNewNoticeWorthyEntries } from "./artifacts.js";
 import { formatBatchStepCommand, getPresentationImages, getPresentationPaths, getPresentationText, isStringArray } from "./content.js";
 import { buildPageChangeSummary } from "./navigation.js";
-import { appendSelectorRecoveryHint, getClipboardWritePayloadCandidates, redactClipboardPermissionErrorValue } from "./errors.js";
+import { appendSelectorRecoveryHint, getClipboardWritePayloadCandidates, isOverlayBlockedClickError, redactClipboardPermissionErrorValue } from "./errors.js";
 export function isAgentBrowserBatchResultArray(value) {
     return Array.isArray(value) && value.every(isRecord);
 }
@@ -208,6 +208,7 @@ async function buildBatchStepPresentation(options) {
             command: command?.[0],
             confirmationId: confirmationRequired?.id,
             failureCategory,
+            overlayBlockedClick: isOverlayBlockedClickError(command?.[0], errorText, command),
             resultCategory: "failure",
             sessionName,
             subcommand: command?.[1],