pi-agent-browser-native 0.2.77 → 0.5.0

package/dist/extensions/agent-browser/lib/json-schema.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Build the small JSON Schema subset used by Pi tool schemas without importing TypeBox at runtime.
- * Responsibilities: Preserve plain JSON Schema objects Pi consumes while keeping extension startup cheap.
- * Scope: Schema construction only; runtime validation still belongs to Pi and the tool input compilers.
- */
 const OPTIONAL_SCHEMA = Symbol("pi-agent-browser-optional-schema");
 function withOptions(schema, options) {
     return { ...schema, ...(options ?? {}) };

package/dist/extensions/agent-browser/lib/launch-scoped-flags.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Canonical launch-scoped agent-browser flag metadata shared by runtime planning and agent-facing guidance.
- * Responsibilities: Define which upstream flags require a fresh launch, explain why, expose stable guidance labels, and share launch-token detection used by runtime and managed restore policy.
- * Scope: Launch-scoped metadata and token classification; broader execution planning lives in runtime.ts.
- */
 import { findCommandStartIndex } from "./argv-descriptor.js";
 import { isBooleanFlagEnabled, optionalGlobalValueFlagConsumesNext } from "./argv-grammar.js";
 export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
@@ -42,6 +37,18 @@ export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
         flag: "--idle-timeout",
         reason: "configures background browser lifecycle for the launched session",
     },
+    {
+        flag: "--args",
+        reason: "selects raw Chrome arguments for the browser launch",
+    },
+    {
+        flag: "--user-agent",
+        reason: "selects the browser user agent at launch time",
+    },
+    {
+        flag: "--headed",
+        reason: "selects whether the launched browser has a visible window",
+    },
     {
         flag: "--device",
         reason: "selects the provider device for the upstream launch",

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

@@ -1,5 +1,3 @@
-// Purpose: Identify and redact wrapper-owned managed restore capabilities.
-// Scope: Pure string helpers shared by storage, policy, and presentation paths.
 const MANAGED_SESSION_RESTORE_KEY_PATTERN = /piab-r(?:2)?-[a-f\d]{32}/gi;
 const MANAGED_SESSION_RESTORE_KEY_EXACT_PATTERN = /^piab-r2-[a-f\d]{32}$/i;
 const WRAPPER_MANAGED_SESSION_PREFIX = "piab-";

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

@@ -1,6 +1,3 @@
-// Purpose: Serialize wrapper-owned daemon policy decisions across cooperating Pi processes.
-// Responsibilities: Elect one live claim, bridge the pre-update v2 path, recover proven-dead current-protocol artifacts, and release only the caller's immutable token.
-// Scope: Wrapper coordination only; agent-browser never reads these claims.
 import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -15,7 +12,9 @@ const LOCK_TICKET_FILE = "ticket.json";
 function getCoordinationDirectory(platform = process.platform) {
     if (platform !== "win32") {
         const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
-        return `/tmp/pi-agent-browser-policy${uid === undefined ? "" : `-${uid}`}`;
+        return platform === "android"
+            ? join(tmpdir(), `pi-agent-browser-policy${uid === undefined ? "" : `-${uid}`}`)
+            : `/tmp/pi-agent-browser-policy${uid === undefined ? "" : `-${uid}`}`;
     }
     const user = process.env.USERNAME ?? process.env.USER ?? "unknown";
     const suffix = createHash("sha256").update(user).digest("hex").slice(0, 12);

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

@@ -1,18 +1,13 @@
-/**
- * Purpose: Own automatic restore policy for wrapper-managed browser sessions.
- * Responsibilities: Resolve owned session identity, isolate per-call policy, reject incompatible argv/env/config, and persist sticky restore-disable state.
- * Scope: Restore policy only; storage identity and snapshot retention live in focused sibling modules.
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { chmodSync, lstatSync, readFileSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { extractCommandTokens, parseCommandInfo } from "./argv-descriptor.js";
-import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, extractRequestedRestoreKey, getAgentBrowserSessionIdentityKey, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
+import { extractUpstreamCommandTokens, parseCommandInfo } from "./argv-descriptor.js";
+import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, extractRequestedRestoreKey, getAgentBrowserSessionIdentityKey, isUpstreamEnvFlagEnabled, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
 import { hasLaunchScopedFlagToken, MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS, MANAGED_RESTORE_INCOMPATIBLE_ENVS, MANAGED_RESTORE_INCOMPATIBLE_FLAGS, } from "./launch-scoped-flags.js";
-import { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure, getManagedSessionRestoreProtectedStorageEnv, hasManagedSessionRestoreProjectIdentity, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
+import { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure, getManagedSessionRestoreScope, getManagedSessionRestoreProtectedStorageEnv, hasManagedSessionRestoreProjectIdentity, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
 import { parseUserBatchStdin } from "./orchestration/batch-stdin.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
 import { writeSecureTempFile } from "./temp.js";
-export { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure } from "./managed-session-storage.js";
+export { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure, getManagedSessionRestoreScope } from "./managed-session-storage.js";
 export { pruneOwnedManagedSessionRestoreSnapshots } from "./managed-session-snapshots.js";
 const AGENT_BROWSER_CONFIG_ENV = "AGENT_BROWSER_CONFIG";
 const AGENT_BROWSER_RESTORE_ENV = "AGENT_BROWSER_RESTORE";
@@ -28,10 +23,6 @@ function isDisabledEnvFlag(value) {
         return false;
     return ["0", "false", "no", "off"].includes(value.trim().toLowerCase());
 }
-/** Match upstream env_var_is_truthy exactly: lowercase only, without trimming or accepting "off". */
-function isUpstreamEnvFlagEnabled(value) {
-    return value !== undefined && !["", "0", "false", "no"].includes(value.toLowerCase());
-}
 function hasUpstreamEnvValue(env, name) {
     return env?.[name] !== undefined;
 }
@@ -70,7 +61,7 @@ export class ManagedSessionRestoreState {
         if (sessionName)
             this.#daemonRestoreKeys.set(getAgentBrowserSessionIdentityKey(sessionName, namespace), restoreKey);
     }
-    replace(identities, options = {}) {
+    replace(identities = [], options = {}) {
         if (!options.preserveDaemonRestoreKeys)
             this.#daemonRestoreKeys.clear();
         this.#disabled.clear();
@@ -82,6 +73,9 @@ const ownedManagedSessionStorage = new AsyncLocalStorage();
 export async function withOwnedManagedSessionContext(context, run) {
     return await ownedManagedSessionStorage.run(context, run);
 }
+export function getOwnedManagedSessionRestoreKey() {
+    return ownedManagedSessionStorage.getStore()?.restoreKey;
+}
 export function resolveOwnedManagedSessionContext(options) {
     const namespace = canonicalizeAgentBrowserNamespace(options.namespace);
     const currentNamespace = canonicalizeAgentBrowserNamespace(options.currentManagedSessionNamespace);
@@ -105,33 +99,18 @@ function ownedContextMatches(sessionName, namespace) {
 export function isOwnedManagedSessionTarget(args) {
     return ownedContextMatches(extractExplicitSessionName(args), extractExplicitNamespace(args)) !== undefined;
 }
-function pathExistsOrIsUnreadable(path) {
-    try {
-        lstatSync(path);
-        return true;
-    }
-    catch (error) {
-        return error.code !== "ENOENT";
-    }
-}
 function hasExplicitConfigArg(args) {
     return scanUpstreamGlobalFlagOccurrences(args, "--config").length > 0;
 }
 function closesBrowserSession(args) {
     return ["close", "exit", "quit"].includes(parseCommandInfo(args).command ?? "");
 }
-export function agentBrowserConfigIsPresent(cwd, parentEnv = process.env, args = [], platform = process.platform) {
-    if (hasExplicitConfigArg(args) || hasUpstreamEnvValue(parentEnv, AGENT_BROWSER_CONFIG_ENV))
-        return true;
-    const paths = [join(cwd, "agent-browser.json")];
-    const home = resolveManagedSessionRestoreHome(parentEnv, platform);
-    if (home)
-        paths.push(join(home, ".agent-browser", "config.json"));
-    return paths.some(pathExistsOrIsUnreadable);
+export function agentBrowserExplicitConfigIsPresent(parentEnv = getAgentBrowserProcessEnvironment(), args = []) {
+    return hasExplicitConfigArg(args) || hasUpstreamEnvValue(parentEnv, AGENT_BROWSER_CONFIG_ENV);
 }
-/** Any upstream config disables automatic restore; content inspection would add parser and resource-exhaustion gaps. */
-export function agentBrowserConfigBlocksManagedRestore(cwd, parentEnv = process.env, args = [], platform = process.platform) {
-    return !resolveManagedSessionRestoreHome(parentEnv, platform) || agentBrowserConfigIsPresent(cwd, parentEnv, args, platform);
+/** Explicit config overrides disable restore; passive files are ignored because every browser-backed subprocess pins a protected empty config. */
+export function agentBrowserConfigBlocksManagedRestore(_cwd, parentEnv = getAgentBrowserProcessEnvironment(), args = [], platform = process.platform) {
+    return !resolveManagedSessionRestoreHome(parentEnv, platform) || agentBrowserExplicitConfigIsPresent(parentEnv, args);
 }
 function omitWrapperInjectedUserAgent(args, enabled) {
     if (!enabled)
@@ -140,7 +119,7 @@ function omitWrapperInjectedUserAgent(args, enabled) {
     return index < 0 ? args : [...args.slice(0, index), ...args.slice(index + 2)];
 }
 function batchHasManagedSessionRestoreConflict(args, stdin) {
-    const [command, ...commandArgs] = extractCommandTokens(args);
+    const [command, ...commandArgs] = extractUpstreamCommandTokens(args);
     if (command !== "batch")
         return false;
     if (commandArgs.some((token) => token !== "--bail"))
@@ -151,7 +130,7 @@ function batchHasManagedSessionRestoreConflict(args, stdin) {
     return parsed.steps.some((step) => ["connect", "batch"].includes(parseCommandInfo(step).command ?? ""));
 }
 function hasManagedSessionRestoreLaunchConflict(options) {
-    const parentEnv = options.parentEnv ?? process.env;
+    const parentEnv = options.parentEnv ?? getAgentBrowserProcessEnvironment();
     const effectiveEnv = { ...parentEnv, ...options.env };
     const args = omitWrapperInjectedUserAgent(options.args, options.wrapperInjectedUserAgent);
     if (MANAGED_RESTORE_INCOMPATIBLE_ENVS.some((name) => hasUpstreamEnvValue(effectiveEnv, name)))
@@ -165,7 +144,7 @@ function hasManagedSessionRestoreLaunchConflict(options) {
     return hasExplicitConfigArg(args) || hasUpstreamEnvValue({ ...parentEnv, ...options.env }, AGENT_BROWSER_CONFIG_ENV);
 }
 function managedSessionRestoreOptedOut(options) {
-    const effectiveEnv = { ...(options.parentEnv ?? process.env), ...options.env };
+    const effectiveEnv = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
     return isDisabledEnvFlag(effectiveEnv[MANAGED_SESSION_RESTORE_ENV]);
 }
 function isManagedSessionRestoreIncompatible(options) {
@@ -173,7 +152,7 @@ function isManagedSessionRestoreIncompatible(options) {
         return true;
     if (managedSessionRestoreOptedOut(options))
         return false;
-    const effectiveEnv = { ...(options.parentEnv ?? process.env), ...options.env };
+    const effectiveEnv = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
     const args = omitWrapperInjectedUserAgent(options.args, options.wrapperInjectedUserAgent);
     if (options.cwd && !hasManagedSessionRestoreProjectIdentity(options.cwd))
         return true;
@@ -182,7 +161,7 @@ function isManagedSessionRestoreIncompatible(options) {
     return !ensureManagedSessionRestoreStorageIsSecure(effectiveEnv, process.platform, extractExplicitNamespace(args));
 }
 function resolveManagedSessionRestorePolicy(options) {
-    const parentEnv = options.parentEnv ?? process.env;
+    const parentEnv = options.parentEnv ?? getAgentBrowserProcessEnvironment();
     const sessionName = extractExplicitSessionName(options.args);
     const namespace = extractExplicitNamespace(options.args);
     const ownedContext = ownedContextMatches(sessionName, namespace);
@@ -194,11 +173,35 @@ export function getOwnedManagedSessionNamespaceEnv(options) {
     const { namespace, owned, ownedContext } = resolveManagedSessionRestorePolicy(options);
     return owned ? { AGENT_BROWSER_NAMESPACE: ownedContext?.namespace ?? namespace ?? "" } : {};
 }
+const DEFAULT_AUTOSAVE_INTERVAL_MS = "30000";
+const MAX_U64 = 18446744073709551615n;
+export function resolveExplicitAutosaveInterval(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\+?\d+$/.test(value))
+        return DEFAULT_AUTOSAVE_INTERVAL_MS;
+    try {
+        const parsed = BigInt(value);
+        return parsed <= MAX_U64 ? parsed.toString() : DEFAULT_AUTOSAVE_INTERVAL_MS;
+    }
+    catch {
+        return DEFAULT_AUTOSAVE_INTERVAL_MS;
+    }
+}
 export function getOwnedManagedSessionCompatibilityEnv(options) {
     const { owned, ownedContext } = resolveManagedSessionRestorePolicy(options);
-    return owned && ownedContext?.compatibilityUserAgent
-        ? { AGENT_BROWSER_USER_AGENT: ownedContext.compatibilityUserAgent }
-        : {};
+    if (!owned || !ownedContext)
+        return {};
+    const parentEnv = options.parentEnv ?? getAgentBrowserProcessEnvironment();
+    const callEnv = options.env ?? {};
+    const explicitRawInterval = Object.hasOwn(callEnv, "AGENT_BROWSER_AUTOSAVE_INTERVAL_MS")
+        ? callEnv.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS
+        : parentEnv.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS;
+    const explicitIntervalMatches = resolveExplicitAutosaveInterval(explicitRawInterval) === ownedContext.headedManagedAutosaveInterval;
+    return {
+        ...(ownedContext.compatibilityUserAgent ? { AGENT_BROWSER_USER_AGENT: ownedContext.compatibilityUserAgent } : {}),
+        ...(ownedContext.headedManagedAutosaveInterval !== undefined && !explicitIntervalMatches ? { AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: ownedContext.headedManagedAutosaveInterval } : {}),
+    };
 }
 export function shouldOmitOwnedManagedSessionRestoreEnv(options) {
     return resolveManagedSessionRestorePolicy(options).owned && closesBrowserSession(options.args);
@@ -280,7 +283,7 @@ export function getManagedSessionRestoreProtectedEnv(options, restoreEnv) {
         return {};
     if (ownedContext?.protectedStorageEnv)
         return { ...ownedContext.protectedStorageEnv };
-    const effectiveEnv = { ...(options.parentEnv ?? process.env), ...options.env };
+    const effectiveEnv = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
     return getManagedSessionRestoreProtectedStorageEnv(true, effectiveEnv);
 }
 export function validateManagedSessionRestoreContextForSpawn(options) {
@@ -288,7 +291,7 @@ export function validateManagedSessionRestoreContextForSpawn(options) {
     if (closesBrowserSession(options.args) || ownedContext?.restoreDecision !== "enabled")
         return true;
     const ownedCwd = ownedContext.cwd ?? options.cwd;
-    if (!ownedContext.restoreKey || createManagedSessionRestoreKey(ownedCwd) !== ownedContext.restoreKey || !hasManagedSessionRestoreProjectIdentity(ownedCwd))
+    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]))
@@ -315,7 +318,7 @@ export function getManagedSessionRestoreEnv(options) {
         return {};
     if (restoreState.isDisabled(sessionName, namespace) || !sessionName)
         return {};
-    return { [AGENT_BROWSER_RESTORE_ENV]: createManagedSessionRestoreKey(options.cwd) };
+    return { [AGENT_BROWSER_RESTORE_ENV]: createManagedSessionRestoreKey(options.cwd, getManagedSessionRestoreScope(sessionName)) };
 }
 /** Commit sticky suppression only after an owned-context subprocess has actually started. */
 export function commitManagedSessionRestoreSuppression(options) {
@@ -360,15 +363,19 @@ export function buildOwnedManagedSessionRestoreContext(options) {
     const projectIdentityAvailable = !optedOut && hasManagedSessionRestoreProjectIdentity(ownedCwd);
     const incompatible = !optedOut && isManagedSessionRestoreIncompatible(policyOptions);
     const enabled = !optedOut && !incompatible;
-    const effectiveEnv = { ...(options.parentEnv ?? process.env), ...options.env };
-    const restoreKey = projectIdentityAvailable ? createManagedSessionRestoreKey(ownedCwd) : undefined;
+    const effectiveEnv = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
+    const restoreScope = getManagedSessionRestoreScope(owned.sessionName);
+    const restoreKey = projectIdentityAvailable ? createManagedSessionRestoreKey(ownedCwd, restoreScope) : undefined;
     return {
         ...owned,
         compatibilityUserAgent: options.compatibilityUserAgent,
+        headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
         expectedDaemonRestoreKey: enabled ? restoreKey : extractRequestedRestoreKey(options.args, owned.sessionName, effectiveEnv[AGENT_BROWSER_RESTORE_ENV]),
         protectedStorageEnv: enabled ? getManagedSessionRestoreProtectedStorageEnv(true, effectiveEnv) : undefined,
         restoreDecision: optedOut ? "opted-out" : incompatible ? "incompatible" : "enabled",
         restoreKey,
+        restoreScope,
         restoreSuppressed: optedOut || incompatible,
     };
 }

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

@@ -1,12 +1,7 @@
-/**
- * Purpose: Retain only wrapper-owned managed-restore snapshots after successful close operations.
- * Responsibilities: Persist atomic per-snapshot ownership records, self-heal malformed records, and apply per-key plus superseded-generation retention without deleting unproven paths.
- * Scope: Snapshot ownership and pruning only; restore eligibility and daemon policy live in sibling modules.
- */
 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, ensureOwnerOnlyDirectory, getManagedRestoreSessionsDirectory, hasManagedSessionRestoreProjectIdentity, isManagedSessionRestoreKey, resolveManagedSessionRestoreCheckoutRoot, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
+import { createManagedSessionRestoreKey, directoryContainsSymlink, ensureManagedSessionRestoreStorageIsSecure, hasManagedSessionRestoreProjectIdentity, 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;
@@ -349,9 +344,7 @@ export function pruneOwnedManagedSessionRestoreSnapshots(options) {
         if (!changed)
             break;
     }
-    const protectedRestoreKey = hasManagedSessionRestoreProjectIdentity(options.cwd)
-        ? createManagedSessionRestoreKey(options.cwd)
-        : restoreKey;
+    const protectedRestoreKey = restoreKey;
     if (!lineage)
         return removed;
     removed += pruneExpiredOtherRestoreKeys({

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

@@ -1,24 +1,23 @@
-// Purpose: Prevent native tool calls from crossing wrapper-owned managed-state boundaries.
-// Responsibilities: Guard destructive global state operations, foreign checkout restore/state references, and browser file access to local agent-browser state.
-// Scope: Pre-spawn policy only; result redaction and managed snapshot retention live elsewhere.
 import { realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgvDescriptor } from "./argv-descriptor.js";
 import { needsManagedSession } from "./command-policy.js";
 import { getScreenshotPathTokenIndex } from "./orchestration/browser-run/artifact-paths.js";
-import { parseBatchCommandArgument, parseUserBatchStdin } from "./orchestration/batch-stdin.js";
+import { getUpstreamEffectiveBatchSteps, parseBatchCommandArgument, parseUserBatchStdin } from "./orchestration/batch-stdin.js";
 import { isUnverifiedPageTransitionCommand } from "./command-taxonomy.js";
-import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, extractExplicitSessionName, optionalGlobalValueFlagConsumesNext, } from "./argv-grammar.js";
+import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, extractExplicitSessionName, isUpstreamEnvFlagEnabled, optionalGlobalValueFlagConsumesNext, } from "./argv-grammar.js";
 import { extractManagedSessionRestoreKeys, isWrapperManagedSessionName } from "./managed-session-capabilities.js";
-import { agentBrowserConfigIsPresent } from "./managed-session-restore.js";
-import { createManagedSessionRestoreKey, hasManagedSessionRestoreProjectIdentity } from "./managed-session-storage.js";
+import { agentBrowserExplicitConfigIsPresent } from "./managed-session-restore.js";
+import { hasManagedSessionRestoreProjectIdentity } from "./managed-session-storage.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
 const BLOCKED_GLOBAL_STATE_MESSAGE = "This operation could read or modify wrapper-owned browser state outside the current checkout. Use a caller-owned state name or path instead.";
 const BLOCKED_MANAGED_BROWSER_FILE_MESSAGE = "Browser access to local .agent-browser storage is blocked because state files can contain authenticated cookies and storage. Use guarded state commands instead.";
 const BLOCKED_MANAGED_SESSION_MESSAGE = "This session name is reserved for a browser managed by this extension instance. Use the current managed session or a caller-owned session name instead.";
 const FILE_ACCESS_FLAG_MESSAGE = "Browser file-access enablement is blocked because a local page could read and exfiltrate authenticated .agent-browser state.";
-const UPSTREAM_CONFIG_MESSAGE = "Upstream agent-browser config is blocked for browser-backed native calls because it can load protected state, profiles, extensions, or file-access settings. Remove the config and pass safe settings explicitly.";
+const UPSTREAM_CONFIG_MESSAGE = "Explicit upstream agent-browser config from --config or AGENT_BROWSER_CONFIG is blocked for browser-backed native calls because it can load protected state, profiles, extensions, or file-access settings. Remove that override and pass safe settings explicitly. Passive agent-browser.json files are ignored through the wrapper's protected empty config.";
 const UNVERIFIED_PAGE_MESSAGE = "The active page became unverified after a tab, attachment, history, script, or state-load transition. Run get url or navigate explicitly to a safe URL before page-content inspection.";
+const BATCH_UNVERIFIED_PAGE_MESSAGE = `${UNVERIFIED_PAGE_MESSAGE} In a batch, put get url after the transition before later content steps, or split the batch at that boundary.`;
 const UNSAFE_BATCH_ARGUMENT_MESSAGE = "Batch command arguments could not be safely inspected. Use batch stdin JSON command arrays instead.";
 const NESTED_BATCH_ARGUMENT_MESSAGE = "Nested batch commands are blocked by the wrapper's page-state safety policy. Flatten the batch steps instead.";
 const NON_BAIL_BATCH_NAVIGATION_MESSAGE = "Batches that navigate before page-content access must use exact batch --bail so a failed navigation cannot expose the prior page.";
@@ -62,7 +61,8 @@ function hasAgentBrowserPathComponent(value) {
 function getFileUrlPath(value) {
     if (!value)
         return undefined;
-    const nestedFileUrl = /^(?:(?:blob|filesystem|view-source):)*(file:.*)$/i.exec(value)?.[1];
+    const trimmedValue = value.replaceAll(/[\t\n\r]/g, "").trim();
+    const nestedFileUrl = /^(?:(?:blob|filesystem|view-source):)*(file:.*)$/i.exec(trimmedValue)?.[1];
     if (!nestedFileUrl)
         return undefined;
     try {
@@ -73,7 +73,7 @@ function getFileUrlPath(value) {
             return decodeUrlComponent(new URL(nestedFileUrl).pathname);
         }
         catch {
-            return value;
+            return trimmedValue;
         }
     }
 }
@@ -151,7 +151,7 @@ function getPositionalOperands(commandTokens) {
 }
 function getExplicitNavigationTarget(args) {
     const descriptor = parseArgvDescriptor(args);
-    const positionals = getPositionalOperands(descriptor.commandTokens);
+    const positionals = getPositionalOperands(descriptor.upstreamCommandTokens);
     if (EXPLICIT_NAVIGATION_COMMANDS.has(descriptor.commandInfo.command ?? ""))
         return positionals[0];
     if (descriptor.commandInfo.command === "tab" && descriptor.commandInfo.subcommand === "new")
@@ -182,11 +182,11 @@ function getResultingExplicitNavigationTarget(args, currentPageUrl) {
 function getBrowserContentUrlOperands(args) {
     const descriptor = parseArgvDescriptor(args);
     const command = descriptor.commandInfo.command;
-    const positionals = getPositionalOperands(descriptor.commandTokens);
+    const positionals = getPositionalOperands(descriptor.upstreamCommandTokens);
     if (["a11y", "read", "vitals", "web-vitals"].includes(command ?? ""))
         return positionals.slice(0, 1);
     if (command === "auth" && descriptor.commandInfo.subcommand === "login")
-        return getFlagValues(descriptor.commandTokens, "--url", true);
+        return getFlagValues(descriptor.upstreamCommandTokens, "--url", true);
     if (command === "diff" && descriptor.commandInfo.subcommand === "url")
         return positionals.slice(1, 3);
     if (command === "record" && ["start", "restart"].includes(descriptor.commandInfo.subcommand ?? ""))
@@ -224,7 +224,7 @@ function getBrowserFileOperands(args, env) {
     const descriptor = parseArgvDescriptor(args);
     const command = descriptor.commandInfo.command;
     const subcommand = descriptor.commandInfo.subcommand;
-    const positionals = getPositionalOperands(descriptor.commandTokens);
+    const positionals = getPositionalOperands(descriptor.upstreamCommandTokens);
     const values = [
         getExplicitNavigationTarget(args),
         ...getBrowserContentUrlOperands(args),
@@ -241,30 +241,27 @@ function getBrowserFileOperands(args, env) {
     if (command === "pdf")
         values.push(positionals[0]);
     if (command === "screenshot") {
-        const pathIndex = getScreenshotPathTokenIndex(descriptor.commandTokens);
-        values.push(pathIndex === undefined ? undefined : descriptor.commandTokens[pathIndex]);
+        const pathIndex = getScreenshotPathTokenIndex(descriptor.upstreamCommandTokens);
+        values.push(pathIndex === undefined ? undefined : descriptor.upstreamCommandTokens[pathIndex]);
     }
     if (["profiler", "trace"].includes(command ?? "") && subcommand === "stop")
         values.push(...positionals.slice(1));
     if (command === "network" && subcommand === "har")
         values.push(...positionals.slice(2));
     if (command === "wait")
-        values.push(...getFlagValues(descriptor.commandTokens, "--download", true), ...getFlagValues(descriptor.commandTokens, "-d", true));
+        values.push(...getFlagValues(descriptor.upstreamCommandTokens, "--download", true), ...getFlagValues(descriptor.upstreamCommandTokens, "-d", true));
     if (command === "cookies" && subcommand === "set")
-        values.push(...getFlagValues(descriptor.commandTokens, "--curl", true));
+        values.push(...getFlagValues(descriptor.upstreamCommandTokens, "--curl", true));
     if (command === "state" && ["load", "rename", "save", "show"].includes(subcommand ?? ""))
         values.push(...positionals.slice(1));
     if (command === "diff" && subcommand === "url")
         values.push(...positionals.slice(1));
     if (command === "diff")
-        values.push(...getFlagValues(descriptor.commandTokens, "--baseline", true), ...getFlagValues(descriptor.commandTokens, "--output", true), ...getFlagValues(descriptor.commandTokens, "-o", true));
+        values.push(...getFlagValues(descriptor.upstreamCommandTokens, "--baseline", true), ...getFlagValues(descriptor.upstreamCommandTokens, "--output", true), ...getFlagValues(descriptor.upstreamCommandTokens, "-o", true));
     if (command === "record" && ["start", "restart"].includes(subcommand ?? ""))
         values.push(...positionals.slice(1));
     return values.filter((value) => typeof value === "string" && value.length > 0);
 }
-function isUpstreamEnvFlagEnabled(value) {
-    return value !== undefined && !["", "0", "false", "no"].includes(value.toLowerCase());
-}
 function rawBrowserArgsEnableFileAccess(args, env) {
     return getRawBrowserArgsValues(args, env).some((value) => typeof value === "string" && /(?:^|[,\p{White_Space}])--(?:allow-file-access(?:-from-files)?|disable-web-security)(?=$|[=,\p{White_Space}])/iu.test(value));
 }
@@ -312,13 +309,21 @@ function getManagedBrowserFileAccessValidationError(options) {
         return BLOCKED_MANAGED_BROWSER_FILE_MESSAGE;
     return undefined;
 }
+// Deliberately unions raw argv steps AND parseable stdin steps even though
+// upstream executes argv steps exclusively when any exist: this pre-spawn
+// validator must stay a superset of anything upstream could run, so it fails
+// closed on unsafe content in either source. Stdin parse failures are fatal
+// only when upstream would actually read stdin (no argv steps); ignored
+// unparseable stdin cannot execute and must not reject a valid raw-argv call.
+// The upstream-exact selection lives in getUpstreamEffectiveBatchSteps
+// (batch-stdin.ts) for guard/folding paths.
 function getBatchCommandSteps(args, stdin) {
     const descriptor = parseArgvDescriptor(args);
     if (descriptor.commandInfo.command !== "batch")
         return { steps: [] };
     const steps = [];
-    for (const command of descriptor.commandTokens.slice(1)) {
-        if (command === "--bail" || command.startsWith("--bail="))
+    for (const command of descriptor.upstreamCommandTokens.slice(1)) {
+        if (command === "--bail")
             continue;
         if (decodeUrlComponent(command).toLowerCase().includes(".agent-browser"))
             return { error: BLOCKED_MANAGED_BROWSER_FILE_MESSAGE, steps: [] };
@@ -330,7 +335,7 @@ function getBatchCommandSteps(args, stdin) {
         steps.push(parsed.step);
     }
     const parsedStdin = parseUserBatchStdin(stdin);
-    if (parsedStdin.error)
+    if (parsedStdin.error && steps.length === 0)
         return { error: parsedStdin.error, steps: [] };
     for (const step of parsedStdin.steps ?? []) {
         if (parseArgvDescriptor(step).commandInfo.command === "batch")
@@ -339,9 +344,16 @@ function getBatchCommandSteps(args, stdin) {
     }
     return { steps };
 }
+export function invocationMayNavigateToLocalFile(args, stdin) {
+    if (isFileUrl(getResultingExplicitNavigationTarget(args)))
+        return true;
+    const descriptor = parseArgvDescriptor(args);
+    return getUpstreamEffectiveBatchSteps(descriptor.upstreamCommandTokens, stdin)
+        .some((step) => isFileUrl(getResultingExplicitNavigationTarget(step)));
+}
 function batchBailsOnFirstError(args) {
     const descriptor = parseArgvDescriptor(args);
-    return descriptor.commandInfo.command === "batch" && descriptor.commandTokens.slice(1).includes("--bail");
+    return descriptor.commandInfo.command === "batch" && descriptor.upstreamCommandTokens.slice(1).includes("--bail");
 }
 function commandMayChangePageTarget(args, trustedBatchTabSelection) {
     const descriptor = parseArgvDescriptor(args);
@@ -425,11 +437,11 @@ export function getCallerOwnedSessionLivePageVerificationRequirement(options) {
         trustedFirstBatchTabSelection: options.trustedFirstBatchTabSelection,
         trustedPinnedEmptyConfig: true,
     });
-    return validationError === UNVERIFIED_PAGE_MESSAGE || validationError === NON_BAIL_BATCH_NAVIGATION_MESSAGE
+    return validationError === UNVERIFIED_PAGE_MESSAGE || validationError === BATCH_UNVERIFIED_PAGE_MESSAGE || validationError === NON_BAIL_BATCH_NAVIGATION_MESSAGE
         ? UNVERIFIED_PAGE_MESSAGE
         : undefined;
 }
-export function getManagedSessionTargetAccessValidationError(args, ownedManagedSession, env = process.env) {
+export function getManagedSessionTargetAccessValidationError(args, ownedManagedSession, env = getAgentBrowserProcessEnvironment()) {
     const sessionName = extractExplicitSessionName(args) ?? env.AGENT_BROWSER_SESSION;
     return sessionName && isWrapperManagedSessionName(sessionName) && !ownedManagedSession
         ? BLOCKED_MANAGED_SESSION_MESSAGE
@@ -471,7 +483,7 @@ function getReferencedValues(args, cwd, env) {
         env.AGENT_BROWSER_STATE,
     ].filter((value) => typeof value === "string" && value.length > 0);
     if (descriptor.commandInfo.command === "state" && ["clear", "load", "rename", "save", "show"].includes(descriptor.commandInfo.subcommand ?? "")) {
-        values.push(...descriptor.commandTokens.slice(2));
+        values.push(...descriptor.upstreamCommandTokens.slice(2));
     }
     for (const value of [...values]) {
         const realPath = resolveExistingPath(cwd, value);
@@ -481,13 +493,13 @@ function getReferencedValues(args, cwd, env) {
     return values;
 }
 export function getManagedSessionStateAccessValidationError(options) {
-    const effectiveEnv = { ...(options.parentEnv ?? process.env), ...options.env };
+    const effectiveEnv = { ...(options.parentEnv ?? getAgentBrowserProcessEnvironment()), ...options.env };
     const descriptor = parseArgvDescriptor(options.args);
     const command = descriptor.commandInfo.command;
     const subcommand = descriptor.commandInfo.subcommand;
     if (["close", "exit", "quit"].includes(command ?? ""))
         return undefined;
-    if (!options.trustedPinnedEmptyConfig && needsManagedSession(descriptor) && agentBrowserConfigIsPresent(options.cwd, effectiveEnv, options.args))
+    if (!options.trustedPinnedEmptyConfig && needsManagedSession(descriptor) && agentBrowserExplicitConfigIsPresent(effectiveEnv, options.args))
         return UPSTREAM_CONFIG_MESSAGE;
     if (command === "batch") {
         const batch = getBatchCommandSteps(options.args, options.stdin);
@@ -526,7 +538,7 @@ export function getManagedSessionStateAccessValidationError(options) {
                 }
             }
             if (directError)
-                return directError;
+                return directError === UNVERIFIED_PAGE_MESSAGE ? BATCH_UNVERIFIED_PAGE_MESSAGE : directError;
             if (failedNavigationHazard)
                 return NON_BAIL_BATCH_NAVIGATION_MESSAGE;
             const mayChangePageTarget = commandMayChangePageTarget(step, trustedBatchTabSelection);
@@ -568,8 +580,8 @@ export function getManagedSessionStateAccessValidationError(options) {
     if (command === "state" && subcommand === "clean")
         return BLOCKED_GLOBAL_STATE_MESSAGE;
     if (command === "state" && subcommand === "clear") {
-        const target = descriptor.commandTokens.slice(2).find((token) => !token.startsWith("-"));
-        if (!target || descriptor.commandTokens.includes("--all") || descriptor.commandTokens.includes("-a") || isWrapperManagedSessionName(target)) {
+        const target = descriptor.upstreamCommandTokens.slice(2).find((token) => !token.startsWith("-"));
+        if (!target || descriptor.upstreamCommandTokens.includes("--all") || descriptor.upstreamCommandTokens.includes("-a") || isWrapperManagedSessionName(target)) {
             return BLOCKED_GLOBAL_STATE_MESSAGE;
         }
     }
@@ -582,8 +594,8 @@ export function getManagedSessionStateAccessValidationError(options) {
         return undefined;
     if (command === "state" && ["rename", "save"].includes(subcommand ?? ""))
         return BLOCKED_GLOBAL_STATE_MESSAGE;
-    if (!hasManagedSessionRestoreProjectIdentity(options.cwd))
+    if (!hasManagedSessionRestoreProjectIdentity(options.cwd) || !options.managedSessionRestoreKey)
         return BLOCKED_GLOBAL_STATE_MESSAGE;
-    const currentKey = createManagedSessionRestoreKey(options.cwd).toLowerCase();
+    const currentKey = options.managedSessionRestoreKey.toLowerCase();
     return referencedKeys.every((key) => key === currentKey) ? undefined : BLOCKED_GLOBAL_STATE_MESSAGE;
 }