pi-agent-browser-native 0.6.9 → 0.6.11

package/dist/extensions/agent-browser/lib/argv-descriptor.js

@@ -48,14 +48,13 @@ export function parseWaitCommandTokens(commandTokens) {
         if (match)
             return { subcommand: match.token };
     }
-    const download = considered.find((entry) => entry.token === "--download" || entry.token === "-d");
-    if (download) {
-        const downloadPathIndex = download.index + 1;
-        const candidate = commandTokens[downloadPathIndex];
+    const downloadIndex = considered.findIndex((entry) => entry.token === "--download" || entry.token === "-d");
+    if (downloadIndex >= 0) {
+        const candidate = considered[downloadIndex + 1];
         return {
-            downloadPath: candidate && !candidate.startsWith("--") ? candidate : undefined,
-            downloadPathIndex: candidate && !candidate.startsWith("--") ? downloadPathIndex : undefined,
-            subcommand: download.token,
+            downloadPath: candidate && !candidate.token.startsWith("--") ? candidate.token : undefined,
+            downloadPathIndex: candidate && !candidate.token.startsWith("--") ? candidate.index : undefined,
+            subcommand: considered[downloadIndex].token,
         };
     }
     return { subcommand: considered[0]?.token };

package/dist/extensions/agent-browser/lib/argv-grammar.js

@@ -81,7 +81,7 @@ export const COMMAND_VALUE_FLAGS = [
 export const OPTIONAL_GLOBAL_VALUE_FLAGS = new Set(["--restore"]);
 export const VALUE_FLAGS = new Set([...GLOBAL_VALUE_FLAGS, ...COMMAND_VALUE_FLAGS]);
 export const PREVALIDATED_VALUE_FLAGS = new Set(GLOBAL_VALUE_FLAGS);
-export const GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE = new Set(["--args"]);
+export const GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE = new Set(["--args", "--session"]);
 export const GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES = new Set([
     "--allow-file-access",
     "--annotate",
@@ -175,6 +175,12 @@ export function isAgentBrowserSessionIdentityKeyInNamespace(identityKey, namespa
     const prefix = getAgentBrowserSessionIdentityKey("", namespace);
     return prefix ? identityKey.startsWith(prefix) : !identityKey.includes("\0");
 }
+export function deleteIdentityKeysInNamespace(entries, namespace) {
+    for (const key of entries.keys()) {
+        if (isAgentBrowserSessionIdentityKeyInNamespace(key, namespace))
+            entries.delete(key);
+    }
+}
 /** Mirror upstream global parsing: full argv, no `--` sentinel, and only global value payloads are skipped. */
 export function scanUpstreamGlobalFlagOccurrences(args, targetFlag) {
     const occurrences = [];

package/dist/extensions/agent-browser/lib/batch-lifecycle.js

@@ -1,12 +1,6 @@
 import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
 import { isCloseAllCommand, isCloseCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
-function getRowBrowserLaunched(row) {
-    const result = isRecord(row.result) ? row.result : isRecord(row.data) ? row.data : undefined;
-    const lifecycle = isRecord(row.lifecycle) ? row.lifecycle : isRecord(result?.lifecycle) ? result.lifecycle : undefined;
-    const effectiveLaunch = isRecord(lifecycle?.effectiveLaunch) ? lifecycle.effectiveLaunch : undefined;
-    return typeof effectiveLaunch?.browserLaunched === "boolean" ? effectiveLaunch.browserLaunched : undefined;
-}
 export function batchHasSuccessfulCloseAll(data, fallbackCommands = []) {
     if (!Array.isArray(data))
         return false;
@@ -34,7 +28,10 @@ export function getSuccessfulBatchCloseLifecycle(rows, fallbackCommands = []) {
         const rowCommand = Array.isArray(row.command) && row.command.every((token) => typeof token === "string")
             ? row.command
             : fallbackCommands[index];
-        const browserLaunched = getRowBrowserLaunched(row);
+        const result = isRecord(row.result) ? row.result : isRecord(row.data) ? row.data : undefined;
+        const lifecycle = isRecord(row.lifecycle) ? row.lifecycle : isRecord(result?.lifecycle) ? result.lifecycle : undefined;
+        const effectiveLaunch = isRecord(lifecycle?.effectiveLaunch) ? lifecycle.effectiveLaunch : undefined;
+        const browserLaunched = typeof effectiveLaunch?.browserLaunched === "boolean" ? effectiveLaunch.browserLaunched : undefined;
         if (!rowCommand) {
             if (sawClose && browserLaunched !== false) {
                 endsClosed = false;
@@ -49,7 +46,6 @@ export function getSuccessfulBatchCloseLifecycle(rows, fallbackCommands = []) {
             endsClosed = true;
             browserActiveAfterClose = false;
             recordingClosedAfterBatch = true;
-            const result = isRecord(row.result) ? row.result : isRecord(row.data) ? row.data : undefined;
             statePath = typeof result?.statePath === "string" ? result.statePath : undefined;
         }
         else if (sawClose && command === "record") {

package/dist/extensions/agent-browser/lib/command-policy.js

@@ -1,4 +1,5 @@
 import { hasOnlyBooleanFlags, hasOnlyOptionFlags, isNonFlagToken, stripSessionlessShapeGlobalFlags } from "./argv-grammar.js";
+import { getUpstreamEffectiveBatchSteps } from "./orchestration/batch-stdin.js";
 const SESSIONLESS_AUTH_SUBCOMMANDS = new Set(["save", "list", "show", "delete", "remove"]);
 const PLUGIN_SESSIONLESS_SUBCOMMANDS = new Set(["list", "show", "add", "run"]);
 const EMPTY_BOOLEAN_FLAGS = new Set();
@@ -92,6 +93,44 @@ function isSessionlessCommand(commandTokens) {
         return isSessionlessStateCommand(normalizedTokens);
     return false;
 }
-export function needsManagedSession(descriptor) {
-    return !isSessionlessCommand(descriptor.upstreamCommandTokens);
+// undefined is a valid DOM read; null is invalid native syntax, which must not trigger page helpers.
+export function getExplicitReadUrl(commandTokens) {
+    if (commandTokens[0] !== "read")
+        return undefined;
+    let url;
+    let llms = false;
+    let outline = false;
+    for (let index = 1; index < commandTokens.length; index += 1) {
+        const token = commandTokens[index];
+        if (["--filter", "--llms", "--timeout"].includes(token)) {
+            const value = commandTokens[++index];
+            if (value === undefined)
+                return null;
+            if (token === "--llms") {
+                if (!["index", "full"].includes(value))
+                    return null;
+                llms = true;
+            }
+            if (token === "--timeout" && (!/^\+?\d+$/.test(value) || BigInt(value) === 0n || BigInt(value) > 18446744073709551615n))
+                return null;
+        }
+        else if (["--raw", "--require-md", "--outline", "--json"].includes(token)) {
+            if (token === "--outline")
+                outline = true;
+        }
+        else if (token.startsWith("--") || url !== undefined)
+            return null;
+        else
+            url = token;
+    }
+    return llms && outline ? null : url;
+}
+export function isBrowserIndependentRead(commandTokens, stdin) {
+    if (commandTokens[0] !== "batch")
+        return getExplicitReadUrl(commandTokens) !== undefined;
+    const steps = getUpstreamEffectiveBatchSteps(commandTokens, stdin);
+    return steps.length > 0 && steps.every((step) => getExplicitReadUrl(step) !== undefined);
+}
+export function needsManagedSession(descriptor, stdin) {
+    return !isSessionlessCommand(descriptor.upstreamCommandTokens) && !isBrowserIndependentRead(descriptor.upstreamCommandTokens, stdin);
 }

package/dist/extensions/agent-browser/lib/command-taxonomy.js

@@ -316,13 +316,26 @@ export function isSessionTabPinningExcludedCommand(command) {
 export function isSessionTabPostCommandCorrectionExcludedCommand(command) {
     return hasCommandCapability(command, "excludedFromPostCommandCorrection");
 }
-/** Upstream 0.33.2 record start swaps to a fresh active page before its already-active check, so even a failed start can replace the page; record restart navigates the current page only when a URL operand (any fourth token, mirroring upstream's positional slot) is present. */
+export function getRecordCommandOperands(tokens) {
+    if (tokens[0] !== "record" || !["start", "restart"].includes(tokens[1] ?? ""))
+        return {};
+    const operands = [];
+    for (let index = 2; index < tokens.length && operands.length < 2; index += 1) {
+        // Native validates the range; bare/non-numeric --fps keeps its old literal meaning.
+        if (tokens[index] === "--fps" && /^\+?\d+$/.test(tokens[index + 1] ?? ""))
+            index += 1;
+        else
+            operands.push(tokens[index]);
+    }
+    return operands.length > 0 ? { path: operands[0], url: operands[1] } : { path: tokens[2], url: tokens[3] };
+}
+/** Starts conservatively invalidate refs because older supported natives replace the page, even on failure. Restarts invalidate only when they have a URL. */
 export function isRecordPageTransitionCommand(tokens) {
     if (tokens[0] !== "record")
         return false;
     if (tokens[1] === "start")
         return true;
-    return tokens[1] === "restart" && tokens.length >= 4;
+    return tokens[1] === "restart" && getRecordCommandOperands(tokens).url !== undefined;
 }
 export function isWebMcpPageMutationCommand(tokens) {
     return isWebMcpPageMutation(tokens[0], tokens[1]);

package/dist/extensions/agent-browser/lib/input-modes/params.js

@@ -138,7 +138,7 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
         outputPath: Type.Optional(Type.String({ description: "Workspace-relative or absolute result-data path; keep it distinct from screenshot, download, recording, and other browser artifact destinations.", minLength: 1 })),
         timeoutMs: Type.Optional(Type.Integer({ description: "Wrapper timeout in ms; exceed explicit waits. electron.list has no configurable timeout; other Electron actions use electron.timeoutMs.", minimum: 1 })),
         sessionMode: Type.Optional(StringEnum(["auto", "fresh"], {
-            description: "auto reuses the managed session; fresh starts one for launch-only flags, then makes it the managed session.",
+            description: "Native configured sessions win; otherwise auto reuses the managed session and fresh starts a new managed browser for launch-only flags.",
             default: DEFAULT_SESSION_MODE,
         })),
     }, {

package/dist/extensions/agent-browser/lib/input-modes/script.js

@@ -5,7 +5,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgvDescriptor } from "../argv-descriptor.js";
 import { getFlagName } from "../argv-grammar.js";
-import { needsManagedSession } from "../command-policy.js";
+import { isBrowserIndependentRead, needsManagedSession } from "../command-policy.js";
 import { isCloseCommand } from "../command-taxonomy.js";
 import { LAUNCH_SCOPED_FLAGS, MANAGED_RESTORE_INCOMPATIBLE_FLAGS } from "../launch-scoped-flags.js";
 import { isRecord } from "../parsing.js";
@@ -44,6 +44,7 @@ const SCRIPT_FORBIDDEN_FLAGS = new Set([
     ...MANAGED_RESTORE_INCOMPATIBLE_FLAGS.filter((flag) => flag !== SCRIPT_ALLOWED_LAUNCH_FLAG),
     "--namespace",
     "--session",
+    "--config",
 ]);
 export function compileAgentBrowserScript(input) {
     if (typeof input !== "string")
@@ -71,7 +72,7 @@ function getScriptCallPolicyError(args) {
         return "script browser calls cannot close, quit, or exit their isolated session.";
     if (SCRIPT_FORBIDDEN_COMMANDS.has(command))
         return `script browser calls cannot use ${command}.`;
-    if (!needsManagedSession(descriptor))
+    if (!needsManagedSession(descriptor) && !isBrowserIndependentRead(descriptor.upstreamCommandTokens))
         return `script browser calls cannot use sessionless/local command ${command}.`;
     for (const token of args) {
         const flag = getFlagName(token);

package/dist/extensions/agent-browser/lib/managed-session-restore.js

@@ -104,7 +104,7 @@ export function agentBrowserExplicitConfigIsPresent(parentEnv = getAgentBrowserP
     return hasExplicitConfigArg(args) || hasUpstreamEnvValue(parentEnv, AGENT_BROWSER_CONFIG_ENV);
 }
 /** Caller-selected upstream config disables the wrapper's automatic restore injection without blocking that config. */
-export function agentBrowserConfigBlocksManagedRestore(_cwd, parentEnv = getAgentBrowserProcessEnvironment(), args = [], platform = process.platform) {
+export function agentBrowserConfigBlocksManagedRestore(parentEnv = getAgentBrowserProcessEnvironment(), args = [], platform = process.platform) {
     return !resolveManagedSessionRestoreHome(parentEnv, platform) || agentBrowserExplicitConfigIsPresent(parentEnv, args);
 }
 function omitWrapperInjectedUserAgent(args, enabled) {
@@ -151,7 +151,7 @@ function isManagedSessionRestoreIncompatible(options, namespace = extractExplici
     const args = omitWrapperInjectedUserAgent(options.args, options.wrapperInjectedUserAgent);
     if (options.cwd && !hasManagedSessionRestoreProjectIdentity(options.cwd))
         return true;
-    if (options.cwd && agentBrowserConfigBlocksManagedRestore(options.cwd, effectiveEnv, args))
+    if (options.cwd && agentBrowserConfigBlocksManagedRestore(effectiveEnv, args))
         return true;
     return !ensureManagedSessionRestoreStorageIsSecure(effectiveEnv, process.platform, namespace);
 }
@@ -192,6 +192,12 @@ export function getOwnedManagedSessionCompatibilityEnv(options) {
     const explicitRawInterval = Object.hasOwn(callEnv, "AGENT_BROWSER_AUTOSAVE_INTERVAL_MS")
         ? callEnv.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS
         : parentEnv.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS;
+    if (ownedContext.reuseOnly) {
+        return explicitRawInterval === undefined && ownedContext.headedManagedAutosaveInterval !== undefined
+            && !agentBrowserExplicitConfigIsPresent({ ...parentEnv, ...callEnv }, options.args)
+            ? { AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: ownedContext.headedManagedAutosaveInterval }
+            : {};
+    }
     const explicitIntervalMatches = resolveExplicitAutosaveInterval(explicitRawInterval) === ownedContext.headedManagedAutosaveInterval;
     return {
         ...(ownedContext.compatibilityUserAgent ? { AGENT_BROWSER_USER_AGENT: ownedContext.compatibilityUserAgent } : {}),
@@ -209,26 +215,33 @@ export function getManagedSessionRestoreProtectedEnv(options, restoreEnv) {
 }
 export function validateManagedSessionRestoreContextForSpawn(options) {
     const { namespace, ownedContext, parentEnv } = resolveManagedSessionRestorePolicy(options);
-    if (closesBrowserSession(options.args) || ownedContext?.restoreDecision !== "enabled")
+    if (closesBrowserSession(options.args) || ownedContext?.restoreDecision !== "enabled" || (ownedContext.reuseOnly && ownedContext.restoreSuppressed))
         return true;
     const ownedCwd = ownedContext.cwd ?? options.cwd;
     if (!ownedContext.restoreKey || !ownedContext.restoreScope || createManagedSessionRestoreKey(ownedCwd, ownedContext.restoreScope) !== ownedContext.restoreKey || !hasManagedSessionRestoreProjectIdentity(ownedCwd))
         return false;
     const effectiveEnv = { ...parentEnv, ...options.env };
-    if (isDisabledEnvFlag(effectiveEnv[MANAGED_SESSION_RESTORE_ENV]))
-        return false;
-    if (MANAGED_RESTORE_INCOMPATIBLE_ENVS.some((name) => !MANAGED_SESSION_RESTORE_SPAWN_PINNED_ENVS.has(name) && hasUpstreamEnvValue(effectiveEnv, name)))
-        return false;
-    if (MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS.some((name) => isUpstreamEnvFlagEnabled(effectiveEnv[name])))
-        return false;
-    if (options.env?.[AGENT_BROWSER_RESTORE_ENV] !== undefined && options.env[AGENT_BROWSER_RESTORE_ENV] !== ownedContext.restoreKey)
-        return false;
+    if (!ownedContext.reuseOnly) {
+        if (isDisabledEnvFlag(effectiveEnv[MANAGED_SESSION_RESTORE_ENV]))
+            return false;
+        if (MANAGED_RESTORE_INCOMPATIBLE_ENVS.some((name) => !MANAGED_SESSION_RESTORE_SPAWN_PINNED_ENVS.has(name) && hasUpstreamEnvValue(effectiveEnv, name)))
+            return false;
+        if (MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS.some((name) => isUpstreamEnvFlagEnabled(effectiveEnv[name])))
+            return false;
+        if (options.env?.[AGENT_BROWSER_RESTORE_ENV] !== undefined && options.env[AGENT_BROWSER_RESTORE_ENV] !== ownedContext.restoreKey)
+            return false;
+    }
     return ensureManagedSessionRestoreStorageIsSecure({ ...effectiveEnv, ...ownedContext.protectedStorageEnv }, process.platform, namespace);
 }
 export function getManagedSessionRestoreEnv(options) {
     const { namespace, owned, ownedContext, parentEnv, restoreState, sessionName } = resolveManagedSessionRestorePolicy(options);
     if (!owned || !restoreState || closesBrowserSession(options.args))
         return {};
+    if (ownedContext?.reuseOnly) {
+        return ownedContext.restoreKey && !ownedContext.restoreSuppressed && validateManagedSessionRestoreContextForSpawn(options)
+            ? { [AGENT_BROWSER_RESTORE_ENV]: ownedContext.restoreKey }
+            : {};
+    }
     if (ownedContext?.restoreDecision) {
         if (ownedContext.restoreDecision !== "enabled" || restoreState.isDisabled(sessionName, namespace) || !sessionName || !ownedContext.restoreKey || !validateManagedSessionRestoreContextForSpawn(options))
             return {};
@@ -244,7 +257,7 @@ export function getManagedSessionRestoreEnv(options) {
 /** Commit sticky suppression only after an owned-context subprocess has actually started. */
 export function commitManagedSessionRestoreSuppression(options) {
     const { namespace, owned, ownedContext, parentEnv, restoreState, sessionName } = resolveManagedSessionRestorePolicy(options);
-    if (!owned || !restoreState || closesBrowserSession(options.args))
+    if (!owned || !restoreState || ownedContext?.reuseOnly || closesBrowserSession(options.args))
         return;
     if (ownedContext?.restoreDecision) {
         const alreadyDisabled = restoreState.isDisabled(sessionName, namespace);
@@ -272,6 +285,23 @@ export function buildOwnedManagedSessionRestoreContext(options) {
     if (!owned)
         return undefined;
     const ownedCwd = owned.cwd ?? options.cwd;
+    if (options.reuseOnly) {
+        const env = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
+        const enabled = !options.restoreState.isDisabled(owned.sessionName, owned.namespace);
+        const restoreScope = getManagedSessionRestoreScope(owned.sessionName);
+        const knownKey = options.restoreState.getDaemonRestoreKey(owned.sessionName, owned.namespace);
+        const restoreKey = knownKey === undefined && enabled && hasManagedSessionRestoreProjectIdentity(ownedCwd)
+            ? createManagedSessionRestoreKey(ownedCwd, restoreScope)
+            : knownKey;
+        return { ...owned, reuseOnly: true, restoreKey: restoreKey ?? undefined, restoreScope,
+            protectedStorageEnv: enabled ? getManagedSessionRestoreProtectedStorageEnv(true, env) : undefined,
+            restoreDecision: enabled ? "enabled" : undefined,
+            restoreSuppressed: managedSessionRestoreOptedOut(options) || agentBrowserExplicitConfigIsPresent(env, options.args)
+                || ["--restore", "--session-name"].some(flag => hasLaunchScopedFlagToken(options.args, flag))
+                || env.AGENT_BROWSER_RESTORE !== undefined || env.AGENT_BROWSER_SESSION_NAME !== undefined,
+            headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+            headedManagedAutosaveInterval: options.headedManagedAutosaveInterval };
+    }
     const policyOptions = {
         args: options.args,
         cwd: ownedCwd,

package/dist/extensions/agent-browser/lib/managed-session-snapshots.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join } from "node:path";
-import { createManagedSessionRestoreKey, directoryContainsSymlink, ensureManagedSessionRestoreStorageIsSecure, hasManagedSessionRestoreProjectIdentity, ensureOwnerOnlyDirectory, getManagedRestoreSessionsDirectory, isManagedSessionRestoreKey, resolveManagedSessionRestoreCheckoutRoot, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
+import { directoryContainsSymlink, ensureManagedSessionRestoreStorageIsSecure, ensureOwnerOnlyDirectory, getManagedRestoreSessionsDirectory, isManagedSessionRestoreKey, resolveManagedSessionRestoreCheckoutRoot, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
 const OWNED_RESTORE_SNAPSHOT_FAMILIES_TO_KEEP = 2;
 const OWNED_RESTORE_SNAPSHOT_MAX_RECORDS = 256;
 const OWNED_RESTORE_SNAPSHOT_RECORD_MAX_BYTES = 16 * 1_024;
@@ -286,10 +286,8 @@ function scanOwnedSnapshots(options) {
 export function pruneOwnedManagedSessionRestoreSnapshots(options) {
     const parentEnv = options.parentEnv ?? process.env;
     const platform = options.platform ?? process.platform;
-    const restoreKey = options.restoreKey === undefined
-        ? hasManagedSessionRestoreProjectIdentity(options.cwd) ? createManagedSessionRestoreKey(options.cwd) : undefined
-        : isManagedSessionRestoreKey(options.restoreKey) ? options.restoreKey : undefined;
-    if (!restoreKey)
+    const restoreKey = options.restoreKey;
+    if (!isManagedSessionRestoreKey(restoreKey))
         return 0;
     const home = resolveManagedSessionRestoreHome(parentEnv, platform);
     if (!home)

package/dist/extensions/agent-browser/lib/orchestration/browser-run/artifact-paths.js

@@ -2,8 +2,7 @@ import { lstatSync, readlinkSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { foldAgentBrowserFilesystemIdentity } from "../../argv-grammar.js";
 import { parseWaitCommandTokens } from "../../argv-descriptor.js";
-const SCREENSHOT_BOOLEAN_FLAGS = new Set(["--annotate", "--full", "-f"]);
-const SCREENSHOT_VALUE_FLAGS = new Set(["--screenshot-dir", "--screenshot-format", "--screenshot-quality"]);
+import { getRecordCommandOperands } from "../../command-taxonomy.js";
 const SCREENSHOT_IMAGE_EXTENSIONS = [".jpeg", ".jpg", ".png", ".webp"];
 function isSingleScreenshotPathToken(token) {
     const explicitlyRelative = token.startsWith("./") || token.startsWith("../");
@@ -17,11 +16,7 @@ function getScreenshotPositionalIndices(commandTokens) {
     const positionalIndices = [];
     for (let index = 1; index < commandTokens.length; index += 1) {
         const token = commandTokens[index];
-        if (SCREENSHOT_VALUE_FLAGS.has(token)) {
-            index += 1;
-            continue;
-        }
-        if (SCREENSHOT_BOOLEAN_FLAGS.has(token))
+        if (token === "--full" || token === "-f")
             continue;
         positionalIndices.push(index);
     }
@@ -54,9 +49,6 @@ function getDiffScreenshotOutputPath(commandTokens) {
     }
     return outputPath;
 }
-function foldArtifactPath(path, platform) {
-    return foldAgentBrowserFilesystemIdentity(path, platform);
-}
 function canonicalizeArtifactPath(absolutePath, platform, seenSymlinks) {
     let cursor = absolutePath;
     const suffix = [];
@@ -71,7 +63,7 @@ function canonicalizeArtifactPath(absolutePath, platform, seenSymlinks) {
             catch {
                 // The destination does not exist yet; canonical ancestry still catches aliases.
             }
-            return foldArtifactPath(canonicalPath, platform);
+            return foldAgentBrowserFilesystemIdentity(canonicalPath, platform);
         }
         catch {
             let symlinkTarget;
@@ -90,7 +82,7 @@ function canonicalizeArtifactPath(absolutePath, platform, seenSymlinks) {
             }
             const parent = dirname(cursor);
             if (parent === cursor)
-                return foldArtifactPath(absolutePath, platform);
+                return foldAgentBrowserFilesystemIdentity(absolutePath, platform);
             suffix.unshift(basename(cursor));
             cursor = parent;
         }
@@ -120,7 +112,7 @@ export function getExplicitArtifactDestination(commandTokens) {
         return commandTokens[3];
     if ((command === "trace" || command === "profiler") && subcommand === "stop")
         return commandTokens[2];
-    if (command === "record" && (subcommand === "start" || subcommand === "restart"))
-        return commandTokens[2];
+    if (command === "record")
+        return getRecordCommandOperands(commandTokens).path;
     return undefined;
 }

package/dist/extensions/agent-browser/lib/orchestration/browser-run/diagnostics.js

@@ -1,17 +1,18 @@
 import { stat } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { isCloseCommand, isOpenNavigationCommand } from "../../command-taxonomy.js";
+import { isBrowserIndependentRead } from "../../command-policy.js";
 import { boundElectronProbeString } from "../../electron/cdp.js";
 import { executableExistsOnPath } from "../../executable-path.js";
 import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
 import { buildInspectOverlayStateAction, buildNextToolAction, withOptionalSessionArgs } from "../../results/next-actions.js";
 import { buildVisibleRefFallbackDiagnosticFromSnapshot, getVisibleRefFallbackTarget } from "../../results/selector-recovery.js";
 import { extractRefSnapshotFromData, isAboutBlankUrl, normalizeComparableUrl } from "../../session-page-state.js";
-import { extractUpstreamCommandTokens, parseWaitCommandTokens, redactInvocationArgs, redactSensitiveText } from "../../runtime.js";
+import { redactInvocationArgs, redactSensitiveText } from "../../runtime.js";
 import { isRecord } from "../../parsing.js";
 import { extractBatchResultCommand, extractNavigationSummaryFromData, extractStringResultField, findElectronLaunchRecordForSession, runSessionCommandData, } from "./session-state.js";
-import { parseValidBatchStepEntries } from "../batch-stdin.js";
-import { getScreenshotPathTokenIndex } from "./artifact-paths.js";
+import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
+import { getExplicitArtifactDestination } from "./artifact-paths.js";
 const ELECTRON_FILL_VERIFICATION_TIMEOUT_MS = 2_000;
 export function sleepMs(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -227,7 +228,7 @@ export async function collectRecordingDependencyWarning(options) {
         return undefined;
     if (await executableExistsOnPath("ffmpeg"))
         return undefined;
-    return { command: recordCommand, dependency: "ffmpeg", message: `${recordCommand} can begin recording, but record stop needs ffmpeg on PATH to encode the WebM output.`, reason: "ffmpeg-missing-for-recording", recommendations: ["Install ffmpeg before relying on this recording workflow; on macOS with Homebrew, brew install ffmpeg or brew install ffmpeg-full.", "If ffmpeg was just installed, restart pi or ensure the PATH visible to pi includes the ffmpeg binary before running record stop."] };
+    return { command: recordCommand, dependency: "ffmpeg", message: `${recordCommand} reported a pending recording, but ffmpeg is not on PATH. Its output is unverified; install ffmpeg before starting a new recording.`, reason: "ffmpeg-missing-for-recording", recommendations: ["Install ffmpeg before recording; on macOS with Homebrew, brew install ffmpeg or brew install ffmpeg-full.", "Stop this recording, check the result, and start a new recording after ensuring Pi can find ffmpeg on PATH."] };
 }
 export function formatRecordingDependencyWarningText(warning) {
     if (!warning)
@@ -711,12 +712,10 @@ export async function collectElectronHandoff(options) {
     }
     return { handoff: "snapshot", refSnapshot, snapshot, ...(snapshotRetryCount > 0 ? { snapshotRetryCount } : {}), tabs };
 }
-function getTimeoutProgressSteps(compiledJob, command, stdin) {
+function getTimeoutProgressSteps(compiledJob, commandTokens, stdin) {
     if (compiledJob)
         return compiledJob.steps.map((step, index) => ({ args: step.args, generatedFrom: step.generatedFrom, index: index + 1 }));
-    if (command !== "batch" || !stdin)
-        return [];
-    return parseValidBatchStepEntries(stdin).map(({ index, step }) => ({ args: step, index: index + 1 }));
+    return getUpstreamEffectiveBatchSteps(commandTokens, stdin).map((args, index) => ({ args, index: index + 1 }));
 }
 function getLastPositionalToken(args, startIndex = 1) {
     for (let index = args.length - 1; index >= startIndex; index -= 1) {
@@ -726,20 +725,8 @@ function getLastPositionalToken(args, startIndex = 1) {
     }
     return undefined;
 }
-function getTimeoutStepArtifactPath(args) {
-    const commandArgs = extractUpstreamCommandTokens(args);
-    const [command] = commandArgs;
-    if (command === "screenshot") {
-        const index = getScreenshotPathTokenIndex(commandArgs);
-        return index === undefined ? undefined : commandArgs[index];
-    }
-    if (command === "pdf")
-        return getLastPositionalToken(commandArgs);
-    if (command === "download")
-        return getLastPositionalToken(commandArgs, 2);
-    if (command === "wait")
-        return parseWaitCommandTokens(commandArgs).downloadPath;
-    return undefined;
+function getTimeoutStepArtifactPath(commandTokens) {
+    return ["screenshot", "pdf", "download", "wait"].includes(commandTokens[0]) ? getExplicitArtifactDestination(commandTokens) : undefined;
 }
 async function statTimeoutArtifactPath(absolutePath) {
     for (let attempt = 0; attempt < 3; attempt += 1) {
@@ -795,7 +782,7 @@ const TIMEOUT_RETRYABLE_COMMANDS = new Set([
 ]);
 function getTimeoutStepRetry(step) {
     const command = step.args[0];
-    return command && TIMEOUT_RETRYABLE_COMMANDS.has(command) ? { args: step.args } : undefined;
+    return command && TIMEOUT_RETRYABLE_COMMANDS.has(command) ? { args: ["batch"], stdin: JSON.stringify([step.args]) } : undefined;
 }
 function normalizeUrlForTimeoutComparison(url) {
     if (!url)
@@ -873,7 +860,9 @@ function buildTimeoutProgressSteps(options) {
     };
 }
 export async function collectTimeoutPartialProgress(options) {
-    const rawSteps = getTimeoutProgressSteps(options.compiledJob, options.command, options.stdin);
+    if ((options.commandTokens[0] === "session" && options.commandTokens[1] === "info") || isBrowserIndependentRead(options.commandTokens, options.stdin))
+        return undefined;
+    const rawSteps = getTimeoutProgressSteps(options.compiledJob, options.commandTokens, options.stdin);
     const artifacts = await collectTimeoutArtifactEvidence(options.cwd, rawSteps);
     const urlData = await runSessionCommandData({ args: ["get", "url"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName });
     const recoveredUrl = extractStringResultField(urlData, "result") ?? extractStringResultField(urlData, "url");
@@ -930,7 +919,7 @@ export function formatTimeoutPartialProgressText(progress, pageTargetUnknown = f
             lines.push(`- ... ${progress.steps.length - shownSteps.length} more step${progress.steps.length - shownSteps.length === 1 ? "" : "s"} omitted`);
     }
     if (progress.retryStep?.retry?.args) {
-        const payload = JSON.stringify({ args: redactInvocationArgs(progress.retryStep.retry.args) });
+        const payload = JSON.stringify({ ...progress.retryStep.retry, stdin: JSON.stringify([redactInvocationArgs(progress.retryStep.args)]) });
         lines.push(pageTargetUnknown
             ? `Retry candidate for step ${progress.retryStep.index}: ${payload}. Verify the current URL before running it.`
             : `Retry failed step: ${payload}`);

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

@@ -86,7 +86,7 @@ export function redactRecoveryHint(recoveryHint) {
 }
 export function buildJsonVisibleContent(options) {
     const { error, presentation, succeeded, warnings } = options;
-    const payload = redactSensitiveValue({ artifacts: presentation.artifacts, data: presentation.data, error, success: succeeded, warnings: warnings && warnings.length > 0 ? warnings : undefined });
+    const payload = redactSensitiveValue({ artifacts: presentation.artifacts, data: presentation.data, error, recordingRecovery: presentation.recordingRecovery, readConfirmation: presentation.readConfirmation, success: succeeded, warnings: warnings && warnings.length > 0 ? warnings : undefined });
     if (isRecord(payload) && isRecord(payload.data) && isRecord(presentation.data) && typeof presentation.data.wsUrl === "string")
         payload.data.wsUrl = presentation.data.wsUrl;
     const images = presentation.content.filter((item) => item.type === "image");
@@ -205,7 +205,9 @@ export async function prepareFinalResultRecoveryState(options) {
     return { categoryDetails, currentRefSnapshot, currentRefSnapshotInvalidation, noActivePageSnapshotFailure, richInputRecoveryDiagnostic, visibleRefFallbackDiagnostic, visibleRefFallbackSessionName };
 }
 function buildTimeoutPartialProgressNextActions(options) {
-    const retryArgs = options.timeoutPartialProgress?.retryStep?.retry?.args;
+    if (options.executionPlan.commandInfo.command === "session" && options.executionPlan.commandInfo.subcommand === "info")
+        return [];
+    const retry = options.timeoutPartialProgress?.retryStep?.retry;
     const stepIndex = options.timeoutPartialProgress?.retryStep?.index;
     const freshSessionAbandoned = options.sessionMode === "fresh" && options.timeoutPartialProgress?.liveUrlRecovered !== true;
     if (options.currentSessionTabTargetUnknown && !freshSessionAbandoned && options.executionPlan.sessionName) {
@@ -220,12 +222,12 @@ function buildTimeoutPartialProgressNextActions(options) {
                 tool: "agent_browser",
             }];
     }
-    if (retryArgs) {
+    if (retry) {
         return [{
                 id: "retry-timeout-step",
                 params: freshSessionAbandoned
-                    ? { args: retryArgs, sessionMode: "fresh" }
-                    : { args: withOptionalSessionArgs(options.executionPlan.sessionName, retryArgs) },
+                    ? { ...retry, sessionMode: "fresh" }
+                    : { ...retry, args: withOptionalSessionArgs(options.executionPlan.sessionName, retry.args) },
                 reason: freshSessionAbandoned
                     ? `Retry the first incomplete timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} in a fresh browser session because the timed-out fresh session was not proven live.`
                     : `Retry the first incomplete timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} against the current browser session.`,
@@ -271,6 +273,8 @@ function buildDialogTimeoutNextActions(options) {
     ];
 }
 function buildResultNextActions(options) {
+    if (options.presentation.recordingRecovery || options.presentation.readConfirmation)
+        return options.presentation.nextActions;
     let nextActions = options.presentation.nextActions ? [...options.presentation.nextActions] : [];
     const append = (actions) => {
         if (actions && actions.length > 0)
@@ -371,7 +375,7 @@ function formatReadExecutionText(options, lifecycle) {
     const source = getReadSource(options);
     if (!source)
         return undefined;
-    return `Read execution: source ${source}; CLI started: ${options.processResult.agentBrowserStarted ? "yes" : "no"}; managed browser lifecycle active: ${lifecycle?.effectiveLaunch.browserLaunched === true ? "yes" : "no"}; managed session outcome: ${options.managedSessionOutcome?.status ?? "not managed"}.`;
+    return `Read execution: source ${source}; CLI started: ${options.processResult.agentBrowserStarted ? "yes" : "no"}; reported browserLaunched: ${lifecycle ? String(lifecycle.effectiveLaunch.browserLaunched) : "unknown"}; managed session outcome: ${options.managedSessionOutcome?.status ?? "not managed"}. An HTTP read does not establish shared-browser liveness; use session info for that.`;
 }
 function buildBrowserWindowStatus(options, lifecycle) {
     if (!options.headedLaunch || options.preserveAttachedBrowserSession || options.providerLaunch || !options.succeeded || lifecycle?.effectiveLaunch.browserLaunched !== true || !options.executionPlan.managedSessionName || !options.managedSessionOutcome || !["created", "replaced"].includes(options.managedSessionOutcome.status))
@@ -417,6 +421,8 @@ function buildAgentBrowserResultDetails(options, nextActions) {
         browserWindow,
         lifecycle,
         readSource: getReadSource(options),
+        recordingRecovery: options.presentation.recordingRecovery,
+        readConfirmation: options.presentation.readConfirmation,
         aboutBlankSessionMismatch: options.aboutBlankSessionMismatch,
         electronPostCommandHealth: options.electronPostCommandHealth,
         electronRefFreshness: options.electronRefFreshnessDiagnostic,

package/dist/extensions/agent-browser/lib/orchestration/browser-run/index.js

@@ -31,6 +31,7 @@ async function runAgentBrowserToolInContext(options) {
             const artifactRunStartedAtMs = Date.now();
             const processResult = await runAgentBrowserProcess({
                 args: prepared.processArgs,
+                browserIndependentReadConfirmation: prepared.readConfirmation !== undefined,
                 cwd: options.cwd,
                 env: ownedManagedSession
                     ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs }

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/wait-timeouts.js

@@ -1,5 +1,6 @@
 import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS } from "../../../argv-grammar.js";
 import { isOpenNavigationCommand } from "../../../command-taxonomy.js";
+import { getExplicitReadUrl, isBrowserIndependentRead } from "../../../command-policy.js";
 import { getAgentBrowserProcessTimeoutMs } from "../../../process.js";
 import { getUpstreamEffectiveBatchSteps } from "../../batch-stdin.js";
 const POSITIONAL_VALUE_FLAGS = new Set([...VALUE_FLAGS, "--llms"]);
@@ -44,10 +45,10 @@ export function findFirstPositionalArgument(commandTokens) {
     return undefined;
 }
 function readUsesActivePageUrl(commandTokens) {
-    return findFirstPositionalArgument(commandTokens) === undefined && commandTokens.some((token) => token === "--require-md" || token === "--llms" || token.startsWith("--llms="));
+    return !isBrowserIndependentRead(commandTokens) && commandTokens.some((token) => token === "--require-md" || token === "--llms" || token.startsWith("--llms="));
 }
 function readRequestBudget(commandTokens, activePageUrl) {
-    const target = findFirstPositionalArgument(commandTokens) ?? activePageUrl;
+    const target = getExplicitReadUrl(commandTokens) ?? activePageUrl;
     if (target === undefined)
         return 1;
     let url;