pi-agent-browser-native 0.3.0 → 0.5.0

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

@@ -1,13 +1,13 @@
 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 { 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";
@@ -61,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();
@@ -73,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);
@@ -96,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)
@@ -131,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"))
@@ -142,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)))
@@ -156,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) {
@@ -164,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;
@@ -173,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);
@@ -204,7 +192,7 @@ export function getOwnedManagedSessionCompatibilityEnv(options) {
     const { owned, ownedContext } = resolveManagedSessionRestorePolicy(options);
     if (!owned || !ownedContext)
         return {};
-    const parentEnv = options.parentEnv ?? process.env;
+    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
@@ -295,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) {
@@ -303,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]))
@@ -330,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) {
@@ -375,8 +363,9 @@ 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,
@@ -386,6 +375,7 @@ export function buildOwnedManagedSessionRestoreContext(options) {
         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,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, 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;
@@ -344,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

@@ -4,18 +4,20 @@ 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, 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.";
@@ -59,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 {
@@ -70,7 +73,7 @@ function getFileUrlPath(value) {
             return decodeUrlComponent(new URL(nestedFileUrl).pathname);
         }
         catch {
-            return value;
+            return trimmedValue;
         }
     }
 }
@@ -148,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")
@@ -179,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 ?? ""))
@@ -221,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),
@@ -238,23 +241,23 @@ 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);
@@ -306,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: [] };
@@ -324,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")
@@ -333,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);
@@ -419,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
@@ -465,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);
@@ -475,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);
@@ -520,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);
@@ -562,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;
         }
     }
@@ -576,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;
 }

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

@@ -5,6 +5,7 @@ import { dirname, isAbsolute, join, parse, resolve, win32 } from "node:path";
 import { canonicalizeAgentBrowserNamespace } from "./argv-grammar.js";
 export { isManagedSessionRestoreKey } from "./managed-session-capabilities.js";
 const MANAGED_SESSION_NAME_PREFIX = "piab-r2-";
+const MANAGED_SESSION_FRESH_SUFFIX_PATTERN = /-fresh-[a-f\d]{10}$/i;
 const MANAGED_SESSION_RESTORE_KEY_HASH_LENGTH = 32;
 const PROJECT_GENERATION_MARKER_NAME = "pi-agent-browser-project-generation-v1.json";
 const PROJECT_GENERATION_MARKER_MAX_BYTES = 1_024;
@@ -15,7 +16,7 @@ function isAbsoluteHome(path, platform) {
 function currentUid() {
     return typeof process.getuid === "function" ? process.getuid() : undefined;
 }
-function isTrustedPosixDirectory(path, requireCurrentOwner) {
+function isTrustedPosixDirectory(path, requireCurrentOwner, platform = process.platform) {
     const uid = currentUid();
     if (uid === undefined)
         return false;
@@ -32,11 +33,13 @@ function isTrustedPosixDirectory(path, requireCurrentOwner) {
         }
         if (entry.isSymbolicLink() || !entry.isDirectory())
             return false;
-        if (entry.uid !== 0 && entry.uid !== uid)
+        const androidSystemAncestor = platform === "android" && (cursor === "/data" || cursor === "/data/data") && entry.uid === 1000 && (entry.mode & 0o002) === 0;
+        const androidAppDirectory = platform === "android" && entry.uid === uid && entry.gid === uid && (entry.mode & 0o002) === 0;
+        if (!androidSystemAncestor && entry.uid !== 0 && entry.uid !== uid)
             return false;
         const writableByOthers = (entry.mode & 0o022) !== 0;
         const rootOwnedStickyDirectory = entry.uid === 0 && (entry.mode & 0o1000) !== 0;
-        if (writableByOthers && !rootOwnedStickyDirectory)
+        if (writableByOthers && !rootOwnedStickyDirectory && !androidSystemAncestor && !androidAppDirectory)
             return false;
     }
     try {
@@ -56,7 +59,7 @@ export function resolveManagedSessionRestoreHome(parentEnv, platform = process.p
         return candidate;
     try {
         const canonical = realpathSync(candidate);
-        return isTrustedPosixDirectory(canonical, true) ? canonical : undefined;
+        return isTrustedPosixDirectory(canonical, true, platform) ? canonical : undefined;
     }
     catch {
         return undefined;
@@ -138,12 +141,15 @@ function readProjectGenerationMarker(path, platform) {
         return undefined;
     }
 }
-function getDirectoryFilesystemIdentity(path) {
+function getDirectoryFilesystemIdentity(path, platform) {
     try {
         const entry = statSync(path, { bigint: true });
-        return entry.isDirectory() && entry.dev > 0n && entry.ino > 0n && entry.birthtimeNs > 0n
-            ? `${entry.dev}:${entry.ino}:${entry.birthtimeNs}`
-            : undefined;
+        if (!entry.isDirectory() || entry.dev <= 0n || entry.ino <= 0n)
+            return undefined;
+        // ponytail: Android reports mutable ctime as birthtime; use statx birthtime/inode generation when Node exposes either reliably.
+        return platform === "android"
+            ? `${entry.dev}:${entry.ino}`
+            : entry.birthtimeNs > 0n ? `${entry.dev}:${entry.ino}:${entry.birthtimeNs}` : undefined;
     }
     catch {
         return undefined;
@@ -157,13 +163,13 @@ function resolveManagedSessionRestoreProjectCheckout(cwd, platform) {
     catch {
         return undefined;
     }
-    if (platform !== "win32" && !isTrustedPosixDirectory(canonicalCwd, false))
+    if (platform !== "win32" && !isTrustedPosixDirectory(canonicalCwd, false, platform))
         return undefined;
     const checkout = resolveGitCheckout(canonicalCwd, platform);
     if (!checkout)
         return undefined;
-    if (platform !== "win32" && (!isTrustedPosixDirectory(checkout.worktreeDirectory, true)
-        || !isTrustedPosixDirectory(checkout.gitDirectory, true)))
+    if (platform !== "win32" && (!isTrustedPosixDirectory(checkout.worktreeDirectory, true, platform)
+        || !isTrustedPosixDirectory(checkout.gitDirectory, true, platform)))
         return undefined;
     return { canonicalCwd, ...checkout };
 }
@@ -175,8 +181,8 @@ function resolveProjectGenerationIdentity(cwd, platform = process.platform) {
     if (!checkout)
         return undefined;
     const { canonicalCwd } = checkout;
-    const gitFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.gitDirectory);
-    const worktreeFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.worktreeDirectory);
+    const gitFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.gitDirectory, platform);
+    const worktreeFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.worktreeDirectory, platform);
     if (!gitFilesystemIdentity || !worktreeFilesystemIdentity)
         return undefined;
     const markerPath = join(checkout.gitDirectory, PROJECT_GENERATION_MARKER_NAME);
@@ -192,22 +198,35 @@ function resolveProjectGenerationIdentity(cwd, platform = process.platform) {
     projectGenerationCache.delete(canonicalCwd);
     try {
         if (!marker) {
-            const candidatePath = `${markerPath}.candidate-${process.pid}-${randomUUID()}`;
-            try {
-                writeFileSync(candidatePath, JSON.stringify({ id: randomUUID(), version: 1 }), { encoding: "utf8", flag: "wx", mode: 0o600 });
+            const content = JSON.stringify({ id: randomUUID(), version: 1 });
+            if (platform === "android") {
+                // ponytail: Android denies hard links in app storage; use renameat2(RENAME_NOREPLACE) if Node exposes it.
                 try {
-                    linkSync(candidatePath, markerPath);
+                    writeFileSync(markerPath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
                 }
                 catch (error) {
                     if (error.code !== "EEXIST")
                         return undefined;
                 }
             }
-            finally {
+            else {
+                const candidatePath = `${markerPath}.candidate-${process.pid}-${randomUUID()}`;
                 try {
-                    unlinkSync(candidatePath);
+                    writeFileSync(candidatePath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
+                    try {
+                        linkSync(candidatePath, markerPath);
+                    }
+                    catch (error) {
+                        if (error.code !== "EEXIST")
+                            return undefined;
+                    }
+                }
+                finally {
+                    try {
+                        unlinkSync(candidatePath);
+                    }
+                    catch { }
                 }
-                catch { }
             }
             marker = readProjectGenerationMarker(markerPath, platform);
         }
@@ -231,16 +250,23 @@ function resolveProjectGenerationIdentity(cwd, platform = process.platform) {
 export function hasManagedSessionRestoreProjectIdentity(cwd) {
     return resolveProjectGenerationIdentity(cwd) !== undefined;
 }
-/** Stable for one checkout generation; deliberately changes when a path is replaced by another checkout. */
-export function createManagedSessionRestoreKey(cwd) {
+/** Keep fresh rotations from one Pi transcript in one private upstream restore pool. */
+export function getManagedSessionRestoreScope(sessionName) {
+    return sessionName.replace(MANAGED_SESSION_FRESH_SUFFIX_PATTERN, "");
+}
+/** Stable for one Pi transcript and checkout generation; isolated from other concurrent transcripts. */
+export function createManagedSessionRestoreKey(cwd, restoreScope = "", platform = process.platform) {
     let canonicalCwd = resolve(cwd);
     try {
         canonicalCwd = realpathSync(canonicalCwd);
     }
     catch { }
-    const identity = resolveProjectGenerationIdentity(canonicalCwd);
+    const identity = resolveProjectGenerationIdentity(canonicalCwd, platform);
     const material = identity ?? `unavailable:${canonicalCwd}`;
-    const digest = createHash("sha256").update(`restore-v2:${material}`).digest("hex").slice(0, MANAGED_SESSION_RESTORE_KEY_HASH_LENGTH);
+    const digest = createHash("sha256")
+        .update(`restore-v3:${material}:scope:${restoreScope}`)
+        .digest("hex")
+        .slice(0, MANAGED_SESSION_RESTORE_KEY_HASH_LENGTH);
     return `${MANAGED_SESSION_NAME_PREFIX}${digest}`;
 }
 function hasValidEncryptionKey(parentEnv) {