pi-agent-browser-native 0.6.10 → 0.6.12

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

@@ -14,13 +14,14 @@ export const QUICK_START_GUIDELINES = [
     "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. 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. Current upstream records the active page unless a URL is supplied. To support older natives, the wrapper conservatively blocks prior @e… refs after every dispatched start attempt and URL-bearing restart, even on failure; this does not prove the page changed. Take a fresh snapshot before continuing. A restart with only --fps keeps the page and refs; --fps <n> selects 1–60 fps (default 30). 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.",
+    "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 and all-read batches skip browser helpers and managed replacement, including timeout recovery; omit the URL for verified 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 finalizes the target. Recording receipts separate captured-frame rate/wall duration from nominal FPS and held/encoded frames; unknown native metrics stay unknown, and sparse or final-only frames cannot prove smoothness. A stop timeout gets one bounded session-info receipt query; follow its exact status/stop actions. Distinct outputPath exports retain failed attempts too. Current upstream records the active page unless a URL is supplied. To support older natives, the wrapper conservatively blocks prior @e… refs after every dispatched start attempt and URL-bearing restart, even on failure; this does not prove the page changed. Take a fresh snapshot before continuing. A restart with only --fps keeps the page and refs; --fps <n> selects 1–60 fps (default 30). 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.",
+    "Use session info for one read-only preflight distinguishing daemon PID/activity from native browser liveness, Chrome PID, exact profile, tabs and native ownership; Pi cleanup ownership is separate and absent fields stay unknown. For policy-required URL reads, use the exact confirm/deny actions and session they return. Only native explicit-read provenance plus capabilities.readRequiresConfirmation enables browserless confirmation; legacy/DOM confirmations retain normal page checks.",
     "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.",
 ];
 export const WEB_SEARCH_PROMPT_GUIDELINE = "Prefer agent_browser_web_search for current or external web facts and URL discovery over public search-engine forms that can hit anti-bot/CAPTCHA-gated pages. For research before implementation, pass searchType: deep-lite unless webSearch.defaultSearchType already does; omit it for everyday lookups so config/auto wins. Provider rank is not proof of authority: when correctness or version matters, prefer the vendor or project's primary current docs, inspect page-date and version clues, and constrain one follow-up after discovering the official domain (Exa includeDomains; Brave site: in query). Do not count URL aliases as independent sources. Use agent_browser after you have a target URL that needs interaction, screenshots, or DOM inspection.";
 export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
-    "Use top-level script only for one-shot loops, conditional page branches, or multi-page aggregation that would otherwise require several calls: await browser({ args, stdin?, timeoutMs? }), branch on its ok field, and emit one bounded JSON value. Script gets an isolated non-profile browser session that is always closed, cannot use caller session/namespace/lifecycle/attachment controls, inherited agent-browser launch/proxy settings, or host APIs, and is not a reusable named recipe. One top-level approval can authorize up to 25 inner calls, so inspect the full source before approval. Use args/job/qa for ordinary linear flows.",
+    "Use top-level script only for one-shot loops, conditional page branches, or multi-page aggregation that would otherwise require several calls: await browser({ args, stdin?, timeoutMs? }), branch on its ok field, and emit one bounded JSON value. Script gets an isolated non-profile browser session that is always closed, cannot use caller session/namespace/lifecycle/attachment controls, inherited agent-browser launch/proxy settings, user/project config or explicit --config, or host APIs, and is not a reusable named recipe. One top-level approval can authorize up to 25 inner calls, so inspect the full source before approval. Use args/job/qa for ordinary linear flows.",
     "Standard workflow: open the page, snapshot -i, interact using current @refs from that snapshot, and re-snapshot after navigation, scrolling, rerendering, or other major DOM changes because refs are page-scoped; the wrapper fails mutation-prone stale/recycled refs before upstream can silently target a different current-page element. On dense pages, use wrapper-side snapshot -i --search <text> or snapshot -i --filter role=<role> to render matching refs while preserving the full ref map in details.refSnapshot, add snapshot --viewport when scroll position or above/below-fold context matters, and add snapshot --diff when a quick before/after ref-map delta would prevent reading a full spill file.",
     "For ordinary forms from one snapshot, batch multiple fill @refs before the submit/click step to avoid serial tool calls; if a fill may autosubmit, navigate, or rerender later fields, split the flow and refresh refs first.",
     "Do not use browser automation to drive public search-engine forms such as Google for discovery; headless jobs that type a query and press Enter can be redirected to anti-bot or CAPTCHA pages. Prefer agent_browser_web_search for live discovery, then agent_browser on a target URL. Do not attempt CAPTCHA bypass.",
@@ -29,7 +30,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "For desktop or host-controlled rich inputs, if semanticAction fill misses, refresh refs and prefer a current editable @ref from details.richInputRecovery or the latest snapshot; focus or click that ref, then use keyboard type for framework-controlled editors that require real key events. keyboard inserttext is paste-like and can change a DOM value without updating application state, so use it only when later application-state evidence proves the edit was accepted. Do not auto-submit with Enter or a submit button unless the user flow explicitly calls for it.",
     "Do not assume Playwright selector dialects such as text=Close or button:has-text('Close') are supported wrapper syntax unless current upstream agent-browser behavior has been verified.",
     "For authenticated or user-specific content explicitly requested by the user, such as feeds, inboxes, account pages, or private dashboards, use a real profile only when the user/config asks for it or profiles have been inspected; do not assume --profile Default exists on every machine. Do not use a real profile for public pages just because they are dashboards. Treat visible page content from real profiles as model-visible transcript data. On macOS, copied Chrome profiles may omit encrypted cookies, so profile selection alone is not proof of authentication; verify the target page and use a user-approved headed login once when needed. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser. If profile/user-data-dir resolution fails, stop retrying opens, run profiles and/or doctor through agent_browser, then report what the user needs to configure.",
-    "Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.",
+    "Use bare calls for a configured native shared session; the wrapper honors its session/namespace across Pi agents without owning quit cleanup or idle policy. Otherwise use the implicit session for routine work. Coordinate shared tabs and do not close another agent's browser.",
     `When using launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}), put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.`,
     "Caller-owned explicit sessions are serialized per effective canonical namespace/session inside this extension while live URL checks, semantic-action snapshots, and the requested command run. For raw batches whose later content step depends on navigation, use exact batch --bail or split the calls; unsafe continue-after-navigation-failure shapes are rejected before the batch runs.",
     "After a successful `connect`, `--cdp`, or enabled `--auto-connect` call, verify with get url and keep using the resulting session without repeating the attach flag. The wrapper remembers that attachment across active-branch reload/resume and live-checks the URL before later page reads/interactions because an attached browser can drift externally; caller config, file access, launch arguments, and environment pass through unchanged. A successful close clears the marker. When several named sessions share one Chrome, pass --pin-tab once (AGENT_BROWSER_PIN_TAB) so a closed bound tab fails as tab_gone instead of acting on a neighbor; recover with tab new or tab list. --no-pin-tab turns the sticky pin off. tab list includes each tab's CDP targetId, accepted as a tab ref.",
@@ -69,7 +70,7 @@ 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 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.",
+    "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 may start a daemon without fulfilling that reopen; explicit URL reads leave the managed browser and pending reopen untouched. 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.",
@@ -79,7 +80,7 @@ export const WRAPPER_TAB_RECOVERY_BEHAVIOR = [
 export const RUNTIME_PROMPT_GUIDELINES = [
     "Use agent_browser with one input mode: script, args, semanticAction, job, qa, sourceLookup/networkSourceLookup, or electron. stdin: batch/eval/auth/wrapper batch only; electron rejects it; never pass --json.",
     "For agent_browser, use open → snapshot -i → @refs; re-snapshot after changes. In authenticated unattended/auto-approved employee flows, ordinary requested non-destructive submissions may proceed. Honor explicit stops; require explicit authorization for purchases, production-control, destructive/irreversible, or account/security/privacy changes.",
-    "Use agent_browser sessionMode=fresh for launch flags. Use requested/configured profiles only; run profiles/doctor on failure. --allowed-domains cannot restore; macOS profile copies may omit encrypted cookies. Verify auth; use a user-approved headed login if needed. Profile content is model-visible.",
+    "agent_browser honors native shared-session defaults on bare calls; do not relaunch/close a shared browser. Without a selected native session, use sessionMode=fresh for launch flags. Use requested/configured profiles only; verify auth. Profile content is model-visible; script is always disposable.",
     "agent_browser: exact user paths; verify artifactVerification/artifacts before success claims. Save promptGuard-required files before close; ffmpeg before recording; close keeps files; waited:timeout proves nothing.",
     "When agent_browser details.nextActions exists, use them. Check Omitted high-value controls in dense snapshots. Dashboards: verify scroll via screenshot/snapshot.",
     "agent_browser: read <url> for docs/text or active DOM; get title/url; get text/html/value/count <selector>; get attr <selector> <name>. Batch 3+ getters; heed visibility warnings.",
@@ -87,15 +88,15 @@ export const RUNTIME_PROMPT_GUIDELINES = [
 export function buildBrowserExecutablePathGuideline(executablePath) {
     if (!executablePath)
         return undefined;
-    return `agent_browser config sets browser.executablePath to ${JSON.stringify(executablePath)}; for fresh browser launches that should use that Chromium-compatible executable, add --executable-path ${JSON.stringify(executablePath)} with sessionMode:fresh. The upstream profiles command still lists Chrome profiles only; for non-Chrome Chromium login state, ask the user for an explicit profile/user-data directory path or inspect local setup with profiles/doctor before recommending a profile value.`;
+    return `agent_browser config sets browser.executablePath to ${JSON.stringify(executablePath)}; reuse a configured native shared session with bare calls; otherwise for fresh browser launches that should use that Chromium-compatible executable, add --executable-path ${JSON.stringify(executablePath)} with sessionMode:fresh. The upstream profiles command still lists Chrome profiles only; for non-Chrome Chromium login state, ask the user for an explicit profile/user-data directory path or inspect local setup with profiles/doctor before recommending a profile value.`;
 }
 export function buildBrowserDefaultProfileGuideline(profile) {
     if (!profile || profile.policy === "explicit-only")
         return undefined;
     if (profile.policy === "always") {
-        return `agent_browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)} with policy always; use --profile ${JSON.stringify(profile.name)} with sessionMode:fresh when a fresh browser launch should use the configured profile, and treat profile content as model-visible user data.`;
+        return `agent_browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)} with policy always; reuse a configured native shared session with bare calls, otherwise use --profile ${JSON.stringify(profile.name)} with sessionMode:fresh when a fresh browser launch should use the configured profile, and treat profile content as model-visible user data.`;
     }
-    return `agent_browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)}; for signed-in/account-specific browser tasks, start with --profile ${JSON.stringify(profile.name)} plus sessionMode:fresh unless the user asks for a different profile.`;
+    return `agent_browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)}; for signed-in/account-specific browser tasks, reuse a configured native shared session with bare calls, otherwise start with --profile ${JSON.stringify(profile.name)} plus sessionMode:fresh unless the user asks for a different profile.`;
 }
 export function buildToolPromptGuidelines(options) {
     const browserDefaultProfileGuideline = buildBrowserDefaultProfileGuideline(options.browserDefaultProfile);

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

@@ -1,14 +1,32 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { rm } from "node:fs/promises";
+import { writeSecureTempFile } from "./temp.js";
 const isolatedAgentBrowserEnvironment = new AsyncLocalStorage();
+const agentBrowserProcessEnvironment = new AsyncLocalStorage();
 const PROXY_ENV_NAMES = new Set(["ALL_PROXY", "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY"]);
 export function getAgentBrowserProcessEnvironment(baseEnv = process.env) {
-    if (isolatedAgentBrowserEnvironment.getStore() !== true)
-        return baseEnv;
-    return Object.fromEntries(Object.entries(baseEnv).filter(([name]) => {
-        const normalizedName = name.toUpperCase();
-        return !normalizedName.startsWith("AGENT_BROWSER_") && !PROXY_ENV_NAMES.has(normalizedName);
-    }));
+    const isolatedConfig = isolatedAgentBrowserEnvironment.getStore();
+    if (isolatedConfig === undefined)
+        return { ...baseEnv, ...agentBrowserProcessEnvironment.getStore() };
+    return {
+        ...Object.fromEntries(Object.entries(baseEnv).filter(([name]) => {
+            const normalizedName = name.toUpperCase();
+            return !normalizedName.startsWith("AGENT_BROWSER_") && !PROXY_ENV_NAMES.has(normalizedName);
+        })),
+        AGENT_BROWSER_CONFIG: isolatedConfig,
+    };
 }
-export function withIsolatedAgentBrowserEnvironment(run) {
-    return isolatedAgentBrowserEnvironment.run(true, run);
+export function withAgentBrowserProcessEnvironment(env, run) {
+    return agentBrowserProcessEnvironment.run({ ...agentBrowserProcessEnvironment.getStore(), ...env }, run);
+}
+export async function withIsolatedAgentBrowserEnvironment(run) {
+    if (isolatedAgentBrowserEnvironment.getStore() !== undefined)
+        return await run();
+    const path = await writeSecureTempFile({ content: "{}", prefix: "script-config", suffix: ".json" });
+    try {
+        return await isolatedAgentBrowserEnvironment.run(path, run);
+    }
+    finally {
+        await rm(path, { force: true });
+    }
 }

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

@@ -286,10 +286,12 @@ export function buildAgentBrowserProcessEnv(baseEnv = processEnv, overrides = un
     clampUpstreamDefaultTimeout(childEnv);
     return childEnv;
 }
-function getManagedPreSpawnPolicyError(options, currentPageUrl, pageUrlUnknown = false) {
+function getManagedPreSpawnPolicyError(options, currentPageUrl, pageUrlUnknown = false, browserIndependentReadConfirmation = false) {
     if (!validateManagedSessionRestoreContextForSpawn(options)) {
         return "Managed session restore policy, storage, or checkout identity changed after planning; refusing to start agent-browser.";
     }
+    if (browserIndependentReadConfirmation)
+        return undefined;
     return getPageTargetValidationError({
         args: options.args,
         currentPageUrl,
@@ -316,7 +318,7 @@ export async function runAgentBrowserProcess(options) {
         restoreState: managedSessionRestoreState,
         stdin,
     };
-    const planningPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown);
+    const planningPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown, options.browserIndependentReadConfirmation);
     if (planningPolicyError) {
         return {
             aborted: false,
@@ -331,7 +333,7 @@ export async function runAgentBrowserProcess(options) {
     const managedSessionRestoreEnv = getManagedSessionRestoreEnv(managedSessionRestoreOptions);
     const ownedManagedSessionCompatibilityEnv = getOwnedManagedSessionCompatibilityEnv(managedSessionRestoreOptions);
     const processOverrides = {
-        [AGENT_BROWSER_IDLE_TIMEOUT_ENV]: String(getImplicitSessionIdleTimeoutMs()),
+        ...(ownedManagedSession ? { [AGENT_BROWSER_IDLE_TIMEOUT_ENV]: String(getImplicitSessionIdleTimeoutMs()) } : {}),
         ...managedSessionRestoreEnv,
         ...env,
         ...getManagedSessionRestoreProtectedEnv(managedSessionRestoreOptions, managedSessionRestoreEnv),
@@ -340,7 +342,8 @@ export async function runAgentBrowserProcess(options) {
     };
     const explicitSocketDir = processOverrides[AGENT_BROWSER_SOCKET_DIR_ENV];
     let effectiveEnv = explicitSocketDir === undefined ? { ...processOverrides, [AGENT_BROWSER_SOCKET_DIR_ENV]: undefined } : processOverrides;
-    const requestedSocketDir = explicitSocketDir ?? parentEnv[PI_AGENT_BROWSER_SOCKET_DIR_ENV] ?? getAgentBrowserSocketDir();
+    const requestedSocketDir = explicitSocketDir ?? parentEnv[PI_AGENT_BROWSER_SOCKET_DIR_ENV]
+        ?? (!ownedManagedSession ? parentEnv[AGENT_BROWSER_SOCKET_DIR_ENV] : undefined) ?? getAgentBrowserSocketDir();
     if (requestedSocketDir !== undefined) {
         const socketDirError = requestedSocketDir.length > 0
             ? await getAgentBrowserSocketDirValidationError(requestedSocketDir)
@@ -463,7 +466,7 @@ export async function runAgentBrowserProcess(options) {
             });
         };
         const childEnv = buildAgentBrowserProcessEnv(parentEnv, effectiveEnv);
-        const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown);
+        const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown, options.browserIndependentReadConfirmation);
         if (spawnPolicyError) {
             resolve({ aborted: false, agentBrowserStarted: false, exitCode: 1, spawnError: new Error(spawnPolicyError), stderr: "", stdout: "", timedOut: false });
             return;

package/dist/extensions/agent-browser/lib/read-confirmation.js

@@ -0,0 +1,59 @@
+import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
+import { extractExplicitSessionName, getAgentBrowserSessionIdentityKey, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences } from "./argv-grammar.js";
+import { getExplicitReadUrl } from "./command-policy.js";
+import { isCloseCommand } from "./command-taxonomy.js";
+import { isRecord } from "./parsing.js";
+export function parseReadConfirmation(value) {
+    if (!isRecord(value) || value.source !== "native-explicit-url-read" || (value.state !== "pending" && value.state !== "cleared"))
+        return undefined;
+    if (typeof value.id !== "string" || !value.id || typeof value.sessionName !== "string" || !value.sessionName || (value.namespace !== undefined && typeof value.namespace !== "string"))
+        return undefined;
+    return { ...(isRecord(value.capabilities) && value.capabilities.readRequiresConfirmation === true ? { capabilities: { readRequiresConfirmation: true } } : {}), id: value.id, sessionName: value.sessionName, namespace: value.namespace, source: "native-explicit-url-read", state: value.state };
+}
+export function findReadConfirmation(args, confirmations, namespace) {
+    const tokens = extractUpstreamCommandTokens(args);
+    if (tokens.length !== 2 || !["confirm", "deny"].includes(tokens[0]))
+        return undefined;
+    const sessionName = extractExplicitSessionName(args);
+    const effectiveNamespace = resolveAgentBrowserNamespace(args, namespace);
+    const matches = [...confirmations].filter(value => value.state === "pending" && value.id === tokens[1]
+        && (sessionName === undefined || getAgentBrowserSessionIdentityKey(sessionName, value.namespace) === getAgentBrowserSessionIdentityKey(value.sessionName, value.namespace))
+        && (effectiveNamespace === undefined || getAgentBrowserSessionIdentityKey(value.sessionName, effectiveNamespace) === getAgentBrowserSessionIdentityKey(value.sessionName, value.namespace)));
+    return matches.length === 1 ? matches[0] : undefined;
+}
+export function scopeReadConfirmationArgs(args, confirmation) {
+    return [
+        ...(scanUpstreamGlobalFlagOccurrences(args, "--namespace").length === 0 ? ["--namespace", confirmation.namespace ?? ""] : []),
+        ...(extractExplicitSessionName(args) === undefined ? ["--session", confirmation.sessionName] : []),
+        ...args,
+    ];
+}
+export function nextReadConfirmation(options) {
+    const { commandTokens: tokens, current } = options;
+    const settlesRead = current?.state === "pending" && tokens.length === 2 && ["confirm", "deny"].includes(tokens[0]) && tokens[1] === current.id;
+    const confirmedResult = settlesRead && tokens[0] === "confirm" && isRecord(options.data) && options.data.confirmed === true && options.data.action === "read" && isRecord(options.data.result)
+        ? options.data.result.data : options.data;
+    // Native control fields only. Never parse response content, snapshot text or nested page JSON as provenance.
+    if (isRecord(confirmedResult) && confirmedResult.confirmation_required === true && typeof confirmedResult.confirmation_id === "string" && confirmedResult.confirmation_id && !("content" in confirmedResult)) {
+        if (confirmedResult.action === "read" && (typeof getExplicitReadUrl(tokens) === "string" || settlesRead)) {
+            return { ...(isRecord(confirmedResult.capabilities) && confirmedResult.capabilities.readRequiresConfirmation === true ? { capabilities: { readRequiresConfirmation: true } } : {}), id: confirmedResult.confirmation_id, namespace: options.namespace, sessionName: options.sessionName, source: "native-explicit-url-read", state: "pending" };
+        }
+        if (current?.state === "pending")
+            return { ...current, state: "cleared" };
+    }
+    return options.succeeded && current?.state === "pending" && (settlesRead || isCloseCommand(tokens[0])) ? { ...current, state: "cleared" } : undefined;
+}
+export function buildReadConfirmationNextActions(confirmation, pendingResponse) {
+    if (confirmation.state === "cleared")
+        return [];
+    const prefix = ["--namespace", confirmation.namespace ?? "", "--session", confirmation.sessionName];
+    if (!pendingResponse)
+        return [{ id: "inspect-read-confirmation-session", tool: "agent_browser", params: { args: [...prefix, "session", "info"] }, reason: "Inspect the exact native session after the read confirmation failed; rerun the original URL read if its ID expired.", safety: "Read-only status, without browser launch or tab changes. Do not substitute a different pending confirmation ID." }];
+    return ["confirm", "deny"].map(command => ({
+        id: command === "confirm" ? "approve-confirmation" : "deny-confirmation", tool: "agent_browser", params: { args: [...prefix, command, confirmation.id] },
+        reason: `${command === "confirm" ? "Approve" : "Deny"} the native confirmation for this explicit URL read.`,
+        safety: confirmation.capabilities?.readRequiresConfirmation === true
+            ? "Review the requested read first. The native capability proves ID matching; no DOM confirmation is implied."
+            : "Native ID matching/browser independence is unproven. The exact native session is preserved, but this confirmation retains normal page checks.",
+    }));
+}

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

@@ -14,6 +14,8 @@ function getArtifactReservation(artifact) {
         cwd: artifact.cwd ?? process.cwd(),
         namespace: artifact.namespace,
         path: artifact.path,
+        ...(artifact.recording?.recordingId ? { recordingId: artifact.recording.recordingId } : {}),
+        ...(artifact.recordingStartedAtMs !== undefined ? { startedAtMs: artifact.recordingStartedAtMs } : {}),
         sessionName: artifact.session,
     };
 }
@@ -43,7 +45,7 @@ export function applyRecordingArtifactsToReservations(reservations, artifacts) {
     for (const [key, pending] of pendingBySession) {
         const existing = reservations.get(key);
         reservations.set(key, pending);
-        if (!existing || existing.absolutePath !== pending.absolutePath || existing.cwd !== pending.cwd) {
+        if (!existing || existing.absolutePath !== pending.absolutePath || existing.cwd !== pending.cwd || existing.recordingId !== pending.recordingId || existing.startedAtMs !== pending.startedAtMs) {
             transitions.push({ reservation: pending, state: "active" });
         }
     }
@@ -63,6 +65,8 @@ export function appendRecordingReservationTransition(pi, transition) {
         cwd: state === "active" ? reservation.cwd : undefined,
         namespace: reservation.namespace,
         path: state === "active" ? reservation.path : undefined,
+        recordingId: state === "active" ? reservation.recordingId : undefined,
+        startedAtMs: state === "active" ? reservation.startedAtMs : undefined,
         sessionName: reservation.sessionName,
         state,
         version: 1,
@@ -81,6 +85,10 @@ function parseReservationTransition(data) {
             state: "closed",
         };
     }
+    if (data.recordingId !== undefined && (typeof data.recordingId !== "string" || !data.recordingId))
+        return undefined;
+    if (data.startedAtMs !== undefined && (typeof data.startedAtMs !== "number" || !Number.isFinite(data.startedAtMs)))
+        return undefined;
     if (typeof data.absolutePath !== "string" || !isAbsolute(data.absolutePath)
         || typeof data.cwd !== "string" || !isAbsolute(data.cwd) || typeof data.path !== "string")
         return undefined;
@@ -90,6 +98,8 @@ function parseReservationTransition(data) {
             cwd: data.cwd,
             namespace: data.namespace,
             path: data.path,
+            ...(typeof data.recordingId === "string" ? { recordingId: data.recordingId } : {}),
+            ...(typeof data.startedAtMs === "number" ? { startedAtMs: data.startedAtMs } : {}),
             sessionName: data.sessionName,
         },
         state: "active",

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

@@ -197,6 +197,14 @@ export function buildAgentBrowserNextActions(options) {
                 break;
             case "timeout":
                 {
+                    if (options.command === "session" && options.subcommand === "info") {
+                        actions.push(buildNextToolAction({
+                            args: ["session", "info"],
+                            id: "retry-session-info",
+                            reason: "Retry the same session status check without opening a browser or inspecting its page.",
+                        }));
+                        break;
+                    }
                     const textAssertion = options.command === "wait" && options.args?.includes("--text") === true;
                     const urlAssertion = options.command === "wait" && options.args?.includes("--url") === true;
                     actions.push(buildNextToolAction({

package/dist/extensions/agent-browser/lib/results/artifact-manifest.js

@@ -4,7 +4,8 @@ export function isPendingRecordingCommand(command, subcommand, kind) {
     return command === "record" && (subcommand === "start" || subcommand === "restart") && kind === "video";
 }
 export function isPendingRecordingArtifact(artifact) {
-    return isPendingRecordingCommand(artifact.command, artifact.subcommand, artifact.kind);
+    return artifact.recordingState === "openRecording" || artifact.status === "pending"
+        || (artifact.status === undefined && isPendingRecordingCommand(artifact.command, artifact.subcommand, artifact.kind));
 }
 export const SESSION_ARTIFACT_MANIFEST_VERSION = 1;
 export const SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES";
@@ -98,10 +99,10 @@ export function retirePendingRecordingManifestEntries(manifest, sessionName, nam
             || !entry.session
             || getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) !== sessionKey
             || entry.kind !== "video"
-            || !isPendingRecordingCommand(entry.command, entry.subcommand, entry.kind))
+            || !isPendingRecordingArtifact(entry))
             return entry;
         changed = true;
-        return { ...entry, retentionState: "missing", subcommand: "close-abandoned" };
+        return { ...entry, recordingState: undefined, status: "unverified", subcommand: "close-abandoned" };
     });
     if (!changed)
         return manifest;
@@ -135,7 +136,7 @@ export function mergeSessionArtifactManifest(options) {
                 if (candidateKey !== key
                     && sameRecordingSession
                     && candidate.kind === "video"
-                    && isPendingRecordingCommand(candidate.command, candidate.subcommand, candidate.kind)) {
+                    && isPendingRecordingArtifact(candidate)) {
                     byPath.delete(candidateKey);
                 }
             }
@@ -155,7 +156,7 @@ export function mergeSessionArtifactManifest(options) {
         const leftTime = left.evictedAtMs ?? left.createdAtMs;
         const rightTime = right.evictedAtMs ?? right.createdAtMs;
         return rightTime - leftTime
-            || Number(isPendingRecordingCommand(right.command, right.subcommand, right.kind)) - Number(isPendingRecordingCommand(left.command, left.subcommand, left.kind))
+            || Number(isPendingRecordingArtifact(right)) - Number(isPendingRecordingArtifact(left))
             || left.path.localeCompare(right.path);
     })
         .slice(0, maxEntries);

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

@@ -1,14 +1,16 @@
 import { isPendingRecordingArtifact } from "./artifact-manifest.js";
 function hasUnverifiedFileArtifact(artifacts) {
-    return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && artifact.exists !== true);
+    return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && (artifact.exists !== true || ["failed", "stale", "unverified"].includes(artifact.status ?? "")));
 }
 export function classifyAgentBrowserSuccessCategory(options) {
     if (options.inspection)
         return "inspection";
+    if (hasUnverifiedFileArtifact(options.artifacts))
+        return "artifact-unverified";
     if ((options.artifacts ?? []).some(isPendingRecordingArtifact))
         return "artifact-pending";
     if ((options.artifacts ?? []).length > 0)
-        return hasUnverifiedFileArtifact(options.artifacts) ? "artifact-unverified" : "artifact-saved";
+        return "artifact-saved";
     if (options.savedFile)
         return "artifact-saved";
     return "completed";

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

@@ -5,6 +5,7 @@ import { getExplicitArtifactDestination } from "../../orchestration/browser-run/
 import { isRecord, parsePositiveInteger } from "../../parsing.js";
 import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, isPendingRecordingCommand, mergeSessionArtifactManifest, } from "../artifact-manifest.js";
 import { classifyAgentBrowserSuccessCategory } from "../categories.js";
+import { formatRecordingReceipt, getRecordingReceipt } from "../recording.js";
 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;
@@ -159,24 +160,26 @@ async function buildFileArtifactMetadata(options) {
     const absolutePath = options.artifactRequest?.absolutePath ?? resolve(options.cwd, options.path);
     const displayPath = options.artifactRequest?.path ?? options.path;
     const extension = extname(absolutePath || options.path).toLowerCase() || undefined;
-    const pendingRecording = isPendingRecordingCommand(options.commandInfo.command, options.commandInfo.subcommand, kind);
+    const pendingRecording = options.recordingPending === true || (isPendingRecordingCommand(options.commandInfo.command, options.commandInfo.subcommand, kind) && options.recordingOutcome !== false && options.recording?.success !== false);
+    const captureStartedAtMs = options.recording?.capture.startedAt ? Date.parse(options.recording.capture.startedAt) : NaN;
+    const recordingStartedAtMs = Number.isFinite(captureStartedAtMs) ? captureStartedAtMs : options.artifactMinUpdatedAtMs;
     let exists;
     let sizeBytes;
     let mediaType;
     let stale = false;
     let updatedAtMs;
-    if (!pendingRecording) {
+    if (!pendingRecording || options.commandInfo.subcommand === "stop") {
         try {
             const fileStats = await stat(absolutePath);
-            exists = true;
+            exists = fileStats.isFile();
             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);
+            stale = commandCreatesArtifact && artifactMtimeIsOutsideCommandWindow(updatedAtMs, kind === "video" ? recordingStartedAtMs : options.artifactMinUpdatedAtMs, options.artifactMaxUpdatedAtMs);
         }
-        catch {
-            exists = false;
+        catch (error) {
+            exists = ["ENOENT", "ENOTDIR"].includes(error.code ?? "") ? false : undefined;
         }
     }
     return {
@@ -190,11 +193,17 @@ async function buildFileArtifactMetadata(options) {
         mediaType,
         namespace: options.namespace,
         path: displayPath,
+        recording: options.recording,
+        recordingStartedAtMs: kind === "video" ? recordingStartedAtMs : undefined,
         recordingState: pendingRecording ? "openRecording" : undefined,
         requestedPath: options.artifactRequest?.path ?? getExplicitArtifactDestination(options.commandInfo.commandTokens ?? []),
         session: options.sessionName,
         sizeBytes,
-        status: pendingRecording ? "pending" : exists === false ? "missing" : stale ? "stale" : options.artifactRequest?.status ?? "saved",
+        status: pendingRecording ? "pending" : exists !== true ? exists === false ? "missing" : "unverified" : stale ? "stale"
+            : kind === "video" && (options.recording?.success === false || options.recording?.output.encoderSucceeded === false || (options.recordingOutcome === false && options.recording?.success !== null)) ? "failed"
+                : kind === "video" && ((options.recording?.success !== true && options.recordingOutcome !== true)
+                    || (options.recording?.file.sizeBytes != null && options.recording.file.sizeBytes !== sizeBytes)) ? "unverified"
+                    : options.artifactRequest?.status ?? "saved",
         subcommand: options.commandInfo.subcommand,
         tempPath: options.artifactRequest?.tempPath,
         updatedAtMs,
@@ -204,6 +213,10 @@ async function buildFileArtifactMetadata(options) {
 async function buildPreviousRestartRecordingArtifact(options) {
     if (options.commandInfo.command !== "record" || options.commandInfo.subcommand !== "restart")
         return undefined;
+    if (isRecord(options.data) && "previousRecording" in options.data) {
+        const recording = getRecordingReceipt(options.data.previousRecording);
+        return recording ? buildFileArtifactMetadata({ ...options, commandInfo: { command: "record", subcommand: "restart-previous" }, path: recording.path, recording }) : undefined;
+    }
     const sessionKey = options.sessionName ? getAgentBrowserSessionIdentityKey(options.sessionName, options.namespace) : undefined;
     const previousRecording = options.artifactManifest?.entries.find((entry) => (entry.command === "record" &&
         (entry.subcommand === "start" || entry.subcommand === "restart") &&
@@ -233,18 +246,21 @@ async function buildPreviousRestartRecordingArtifact(options) {
             exists: true,
             mediaType: fileStats.isFile() ? await getFileImageMimeType(absolutePath) : undefined,
             sizeBytes: fileStats.size,
-            status: stale ? "stale" : "saved",
+            status: stale ? "stale" : "unverified",
             updatedAtMs: fileStats.mtimeMs,
         };
     }
-    catch {
-        return { ...base, exists: false, status: "missing" };
+    catch (error) {
+        const missing = ["ENOENT", "ENOTDIR"].includes(error.code ?? "");
+        return { ...base, exists: missing ? false : undefined, status: missing ? "missing" : "unverified" };
     }
 }
 export async function extractFileArtifacts(options) {
     const candidates = extractPathStrings(options.data);
-    const currentArtifacts = (await Promise.all(candidates.map((path) => buildFileArtifactMetadata({ ...options, path })))).filter((artifact) => artifact !== undefined);
-    const previousRestartRecordingArtifact = await buildPreviousRestartRecordingArtifact({ artifactManifest: options.artifactManifest, artifactMaxUpdatedAtMs: options.artifactMaxUpdatedAtMs, artifactMinUpdatedAtMs: options.artifactMinUpdatedAtMs, commandInfo: options.commandInfo, cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName });
+    const recording = options.commandInfo.command === "record" ? getRecordingReceipt(options.data, options.commandInfo.subcommand === "stop" ? options.recordingOutcome : undefined) : undefined;
+    const recordingPending = options.recordingPending ?? (recording?.success === null && isRecord(options.data) && isRecord(options.data.capture) && recording.capture.endedAt === null);
+    const currentArtifacts = (await Promise.all(candidates.map((path) => buildFileArtifactMetadata({ ...options, path, recording, recordingPending })))).filter((artifact) => artifact !== undefined);
+    const previousRestartRecordingArtifact = await buildPreviousRestartRecordingArtifact(options);
     return previousRestartRecordingArtifact ? [previousRestartRecordingArtifact, ...currentArtifacts] : currentArtifacts;
 }
 export function buildManifestEntriesForFileArtifacts(artifacts, nowMs = Date.now()) {
@@ -259,6 +275,10 @@ export function buildManifestEntriesForFileArtifacts(artifacts, nowMs = Date.now
         mediaType: artifact.mediaType,
         namespace: artifact.namespace,
         path: artifact.path,
+        recording: artifact.recording,
+        recordingStartedAtMs: artifact.recordingStartedAtMs,
+        recordingState: artifact.recordingState,
+        status: artifact.status,
         requestedPath: artifact.requestedPath,
         retentionState: artifact.exists === false || artifact.status === "stale" ? "missing" : "live",
         session: artifact.session,
@@ -268,10 +288,7 @@ export function buildManifestEntriesForFileArtifacts(artifacts, nowMs = Date.now
     }));
 }
 export function isManifestFileArtifact(artifact) {
-    if (artifact.status === "stale") {
-        return artifact.kind === "video" && artifact.command === "record" && artifact.subcommand === "restart-previous";
-    }
-    return artifact.kind === "video" && artifact.command === "record" ? true : !isPendingRecordingArtifact(artifact);
+    return artifact.kind === "video" && artifact.command === "record" ? true : artifact.status !== "stale" && !isPendingRecordingArtifact(artifact);
 }
 function getArtifactVerificationEntry(artifact) {
     if (isPendingRecordingArtifact(artifact)) {
@@ -279,7 +296,9 @@ function getArtifactVerificationEntry(artifact) {
             absolutePath: artifact.absolutePath,
             exists: artifact.exists,
             kind: artifact.kind,
-            limitation: "Recording output is pending until record stop completes.",
+            limitation: "Recording output is pending until native finalization succeeds and the file is verified.",
+            recording: artifact.recording,
+            recordingStartedAtMs: artifact.recordingStartedAtMs,
             mediaType: artifact.mediaType,
             path: artifact.path,
             recordingState: artifact.recordingState ?? "openRecording",
@@ -292,7 +311,7 @@ function getArtifactVerificationEntry(artifact) {
             willExistOnStop: artifact.willExistOnStop ?? true,
         };
     }
-    const state = artifact.status === "stale"
+    const state = ["failed", "stale", "unverified"].includes(artifact.status ?? "")
         ? "unverified"
         : artifact.exists === true
             ? "verified"
@@ -303,13 +322,17 @@ function getArtifactVerificationEntry(artifact) {
         absolutePath: artifact.absolutePath,
         exists: artifact.exists,
         kind: artifact.kind,
-        limitation: artifact.status === "stale"
-            ? "The reported path's modification time fell outside this command's bounded artifact window. Treat the artifact as stale until regenerated."
-            : state === "missing"
-                ? "The wrapper did not find the reported artifact at absolutePath. Treat the path as unverified until recovered or regenerated."
-                : state === "unverified"
-                    ? "The wrapper could not prove local filesystem existence for this artifact."
-                    : undefined,
+        recording: artifact.recording,
+        recordingStartedAtMs: artifact.recordingStartedAtMs,
+        limitation: artifact.status === "failed" || artifact.status === "unverified"
+            ? "File presence does not prove successful native recording finalization or encoding. Inspect the receipt and original failure."
+            : artifact.status === "stale"
+                ? "The reported path's modification time fell outside this command's bounded artifact window. Treat the artifact as stale until regenerated."
+                : state === "missing"
+                    ? "The wrapper did not find the reported artifact at absolutePath. Treat the path as unverified until recovered or regenerated."
+                    : state === "unverified"
+                        ? "The wrapper could not prove local filesystem existence for this artifact."
+                        : undefined,
         mediaType: artifact.mediaType,
         path: artifact.path,
         requestedPath: artifact.requestedPath,
@@ -415,6 +438,10 @@ function formatArtifactLabel(artifact) {
         case "trace":
             return "Saved trace";
         case "video":
+            if (artifact.status === "failed")
+                return artifact.subcommand === "restart-previous" ? "Previous recording failed" : "Recording failed";
+            if (artifact.status === "unverified")
+                return artifact.subcommand === "restart-previous" ? "Previous recording unverified" : "Recording unverified";
             if (artifact.command === "record" && artifact.subcommand === "restart-previous") {
                 if (artifact.status === "stale")
                     return "Previous recording stale";
@@ -423,7 +450,9 @@ function formatArtifactLabel(artifact) {
                 return "Previous recording saved";
             }
             if (!isPendingRecordingArtifact(artifact))
-                return "Saved recording";
+                return artifact.status === "saved" ? "Saved recording" : "Recording reported; file not verified";
+            if (artifact.subcommand === "stop")
+                return "Recording finalization pending";
             return artifact.subcommand === "restart" ? "Recording restarted; output will be written on stop" : "Recording started; output will be written on stop";
     }
 }
@@ -440,7 +469,7 @@ export function formatArtifactSummary(artifacts) {
     if (restartArtifact && previousRecordingArtifacts.length > 0) {
         return [...previousRecordingArtifacts, restartArtifact].map((artifact) => `${formatArtifactLabel(artifact)}: ${artifact.path}`).join("\n");
     }
-    return `Saved ${artifacts.length} artifacts: ${artifacts.map((artifact) => `${artifact.kind} ${artifact.path}`).join(", ")}`;
+    return `${artifacts.every((artifact) => artifact.status === "saved") ? "Saved" : "Reported"} ${artifacts.length} artifacts: ${artifacts.map((artifact) => `${artifact.kind} ${artifact.path}`).join(", ")}`;
 }
 export function formatArtifactMetadataLines(artifacts) {
     return artifacts.map((artifact, index) => {
@@ -450,12 +479,13 @@ export function formatArtifactMetadataLines(artifacts) {
                 `Artifact type: ${artifact.kind}`,
                 artifact.requestedPath ? `Requested path: ${artifact.requestedPath}` : undefined,
                 `Absolute path: ${artifact.absolutePath}`,
-                "Exists: pending until record stop",
+                `Exists: ${artifact.exists ?? "pending until record stop"}`,
                 `Status: ${artifact.status ?? "pending"}`,
                 `Recording state: ${artifact.recordingState ?? "openRecording"}`,
                 `Will exist on stop: ${artifact.willExistOnStop !== false}`,
                 artifact.session ? `Session: ${artifact.session}` : undefined,
                 artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
+                artifact.recording ? formatRecordingReceipt(artifact.recording) : undefined,
                 `Machine data: details.artifacts[${index}]`,
             ].filter((item) => item !== undefined).join("\n");
         }
@@ -464,7 +494,7 @@ export function formatArtifactMetadataLines(artifacts) {
             `Artifact type: ${artifact.kind}`,
             artifact.requestedPath ? `Requested path: ${artifact.requestedPath}` : undefined,
             `Absolute path: ${artifact.absolutePath}`,
-            `Exists: ${artifact.exists === true}`,
+            `Exists: ${artifact.exists ?? "unknown"}`,
             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,
@@ -473,6 +503,7 @@ export function formatArtifactMetadataLines(artifacts) {
             artifact.mediaType ? `Media type: ${artifact.mediaType}` : undefined,
             artifact.session ? `Session: ${artifact.session}` : undefined,
             artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
+            artifact.recording ? formatRecordingReceipt(artifact.recording) : undefined,
             `Machine data: details.artifacts[${index}]`,
         ].filter((item) => item !== undefined).join("\n");
     });