pi-agent-browser-native 0.6.15 → 0.6.17

package/dist/extensions/agent-browser/index.js

@@ -6,14 +6,17 @@ import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./
 import { PROJECT_RULE_PROMPT, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
 import { SessionPageState } from "./lib/session-page-state.js";
 import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractUpstreamCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, redactSensitiveText, redactSensitiveValue, isPlainTextInspectionArgs, } from "./lib/runtime.js";
-import { deleteIdentityKeysInNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace } from "./lib/argv-grammar.js";
+import { deleteIdentityKeysInNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences } from "./lib/argv-grammar.js";
 import { parseArgvDescriptor } from "./lib/argv-descriptor.js";
 import { needsManagedSession } from "./lib/command-policy.js";
-import { ManagedSessionRestoreState } from "./lib/managed-session-restore.js";
+import { ManagedSessionRestoreState, resolveOwnedManagedSessionContext, withOwnedManagedSessionContext } from "./lib/managed-session-restore.js";
 import { isRecord } from "./lib/parsing.js";
 import { runAgentBrowserProcess } from "./lib/process.js";
 import { getAgentBrowserProcessEnvironment, withIsolatedAgentBrowserEnvironment } from "./lib/process-environment.js";
 import { withNativeSessionDefaults } from "./lib/orchestration/native-session-defaults.js";
+import { getBrowserCwdError, resolveExecutionCwd, restoreManagedSessionCwd } from "./lib/execution-cwd.js";
+import { resolveOperationPaths } from "./lib/orchestration/operation-paths.js";
+import { closeManagedSession, inspectManagedSessionDaemon } from "./lib/orchestration/browser-run/managed-session-daemon-policy.js";
 import { MINIMUM_AGENT_BROWSER_VERSION, SUPPORTED_AGENT_BROWSER_VERSION_LABEL, TARGET_AGENT_BROWSER_VERSION, getAgentBrowserVersionValidationError, parseAgentBrowserVersionOutput, } from "./lib/upstream-version.js";
 import { buildPromptPolicy, getLatestUserPrompt, shouldAppendBrowserSystemPrompt } from "./lib/prompt-policy.js";
 import { isCloseAllCommand, isCloseCommand } from "./lib/command-taxonomy.js";
@@ -21,9 +24,8 @@ import { hasLaunchScopedFlagToken } from "./lib/launch-scoped-flags.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
 import { AGENT_BROWSER_PARAMS } from "./lib/input-modes/params.js";
 import { AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS, AGENT_BROWSER_SCRIPT_NAMESPACE, createAgentBrowserScriptSessionName, isAgentBrowserScriptSessionName, runAgentBrowserScript, } from "./lib/input-modes/script.js";
-import { closeManagedSession, getSessionContextKey, runAgentBrowserTool } from "./lib/orchestration/browser-run/index.js";
 import { canonicalizeExplicitArtifactDestination, getExplicitArtifactDestination, getRecordContactSheetDestination } from "./lib/orchestration/browser-run/artifact-paths.js";
-import { findElectronLaunchRecordForSession, getActiveElectronRecords } from "./lib/orchestration/browser-run/session-state.js";
+import { findElectronLaunchRecordForSession, getActiveElectronRecords, getSessionContextKey } from "./lib/orchestration/browser-run/session-state.js";
 import { parseBatchCommandArgument, parseUserBatchStdin } from "./lib/orchestration/batch-stdin.js";
 import { ELECTRON_POST_COMMAND_STATUS_SETTLE_MS, ELECTRON_PROFILE_ISOLATION_DETAILS, cleanupActiveElectronHostLaunches, handleElectronHostInput, restoreElectronLaunchRecordsFromBranch, } from "./lib/orchestration/electron-host/index.js";
 import { buildValidationFailureResult, resolveAgentBrowserInput } from "./lib/orchestration/input-plan.js";
@@ -571,7 +573,7 @@ function collectBranchManagedResourceEvents(branch) {
             const replacedSessionNamespace = typeof outcome.replacedSessionNamespace === "string" ? outcome.replacedSessionNamespace : namespace;
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(typeof outcome.replacedSessionName === "string" ? outcome.replacedSessionName : undefined, replacedSessionNamespace), eventRank);
         }
-        if (succeeded && !isCloseCommand(command) && sessionName && (usedImplicitSession || sessionMode === "fresh" || details.managedSessionHeadedAutosaveDisabled === true || typeof details.managedSessionHeadedAutosaveInterval === "string")) {
+        if (succeeded && !isCloseCommand(command) && sessionName && ((!explicitSessionName && (usedImplicitSession || sessionMode === "fresh")) || details.managedSessionHeadedAutosaveDisabled === true || typeof details.managedSessionHeadedAutosaveInterval === "string")) {
             setBranchManagedSessionActive(events, sessionName, namespace, eventRank);
         }
         if (succeeded && isCloseCommand(command)) {
@@ -1108,7 +1110,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         managedSessionHeadedAutosaveInterval = managedSessionActive
             ? restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, managedSessionName, managedSessionNamespace)
             : undefined;
-        managedSessionCwd = ctx.cwd;
+        managedSessionCwd = restoreManagedSessionCwd(branch, managedSessionName, managedSessionNamespace, ctx.cwd);
         freshSessionOrdinal = nextFreshSessionOrdinal;
         sessionPageState = SessionPageState.fromBranch(branch);
         traceOwners = new Map();
@@ -1159,7 +1161,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                 continue;
             if (!isRestorableManagedSessionName(identity.sessionName, managedSessionBaseName))
                 continue;
-            trackOwnedManagedSession(ownedManagedSessions, identity.sessionName, ctx.cwd, {
+            trackOwnedManagedSession(ownedManagedSessions, identity.sessionName, restoreManagedSessionCwd(branch, identity.sessionName, identity.namespace, ctx.cwd), {
                 branchOwned: true,
                 compatibilityWorkaround: restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, identity.sessionName, identity.namespace),
                 headedManagedAutosaveDisabled: restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, identity.sessionName, identity.namespace),
@@ -1168,7 +1170,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             });
         }
         if (restoredState.active) {
-            trackOwnedManagedSession(ownedManagedSessions, restoredState.sessionName, ctx.cwd, {
+            trackOwnedManagedSession(ownedManagedSessions, restoredState.sessionName, managedSessionCwd, {
                 branchOwned: true,
                 compatibilityWorkaround: managedSessionCompatibilityWorkaround,
                 headedManagedAutosaveDisabled: managedSessionHeadedAutosaveDisabled,
@@ -1184,7 +1186,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             const closeRank = branchResourceEvents.managedSessionCloseRanks.get(sessionKey);
             if (activeRank === undefined || (closeRank !== undefined && closeRank >= activeRank))
                 continue;
-            trackOwnedManagedSession(ownedManagedSessions, record.sessionName, ctx.cwd, {
+            trackOwnedManagedSession(ownedManagedSessions, record.sessionName, restoreManagedSessionCwd(branch, record.sessionName, undefined, ctx.cwd), {
                 branchOwned: true,
                 headedManagedAutosaveDisabled: restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, record.sessionName),
                 headedManagedAutosaveInterval: restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, record.sessionName),
@@ -1243,6 +1245,78 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             notifyRecordingPersistence(ctx);
         }));
     });
+    // Fork-only checkpoint event; official Pi validation types do not declare it.
+    // Pi owns awaited tools/events (including their execution queues). Only script
+    // children and retained browser/recording resources need extension-side checks.
+    const checkpointPi = pi;
+    checkpointPi.on("session_checkpoint", async (event, ctx) => {
+        const blocked = (reason) => ({ sleepReady: false, reason });
+        if (activeScriptControllers.size || activeScriptExecutions.size)
+            return blocked("Browser script execution or cleanup is pending");
+        flushRecordingReservations();
+        if (recordingReservationsDirty)
+            return blocked("Browser recording journal persistence is dirty");
+        if (activeRecordingReservations.size)
+            return blocked("Browser recording is pending; finish it explicitly before sleep");
+        const entries = ctx.sessionManager.getEntries();
+        if ([...getScriptSessionLeasesFromBranch(entries).values()].some(lease => lease.cleanup !== "closed")
+            || [...ownedManagedSessions.values()].some(owner => isAgentBrowserScriptSessionName(owner.sessionName))) {
+            return blocked("Browser script cleanup lease is unresolved");
+        }
+        if (getActiveElectronRecords(ownedElectronLaunchRecords).length || getActiveElectronRecords(electronLaunchRecords).length
+            || [...electronChildProcesses.values()].some(child => child.exitCode === null && child.signalCode === null)) {
+            return blocked("Electron launch is still active");
+        }
+        if (attachedSessionKeys.size || restoreAttachedSessionKeysFromBranch(entries).size)
+            return blocked("Attached browser state is caller-owned and not checkpointed");
+        if (traceOwners.size || [...networkRoutesBySession.values()].some(routes => routes.length))
+            return blocked("Browser trace or network routes are still active");
+        // Include off-branch and caller-owned/root identities, without acquiring
+        // cleanup ownership. Transcript page/ref details do not serialize a browser.
+        const historicalResources = collectBranchManagedResourceEvents(entries);
+        const sessions = new Map(ownedManagedSessions);
+        if (managedSessionActive)
+            trackOwnedManagedSession(sessions, managedSessionName, managedSessionCwd, { namespace: managedSessionNamespace });
+        for (const entry of entries) {
+            if (entry.type !== "message" || entry.message.role !== "toolResult" || entry.message.toolName !== "agent_browser")
+                continue;
+            const details = isRecord(entry.message.details) ? entry.message.details : undefined;
+            // Helpers can launch before a main-process failure. Conversely, native
+            // launch flags on sessionless reads can open the unnamed default browser.
+            const sessionName = typeof details?.sessionName === "string" ? details.sessionName
+                : details?.agentBrowserStarted === true ? "default" : undefined;
+            if (!sessionName)
+                continue;
+            const namespace = typeof details?.namespace === "string" ? details.namespace : undefined;
+            const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
+            if (!sessions.has(key))
+                trackOwnedManagedSession(sessions, sessionName, ctx.cwd, { namespace });
+        }
+        for (const [key, owner] of sessions) {
+            event.signal.throwIfAborted();
+            // An abnormal restart can leave a wrapper-created browser only off-branch.
+            // Reuse native ownership events for inspection, never cleanup ownership.
+            // A later close can refer to the same identity in a different socket root.
+            const historicalIdentity = historicalResources.managedSessionActiveIdentities.get(key);
+            const historicallyOwned = historicalIdentity && isRestorableManagedSessionName(historicalIdentity.sessionName, managedSessionBaseName);
+            const context = resolveOwnedManagedSessionContext({
+                ...owner,
+                currentManagedSessionName: managedSessionActive ? managedSessionName : undefined,
+                currentManagedSessionNamespace: managedSessionNamespace,
+                recordedOwnedSession: ownedManagedSessions.get(key) ?? (historicallyOwned ? { ...historicalIdentity, cwd: ctx.cwd } : undefined),
+                restoreState: managedSessionRestoreState,
+            });
+            // Owned routing must not mask an explicit caller's same-name ambient daemon.
+            for (const inspectionContext of context ? [{ ...context, reuseOnly: true }, undefined] : [undefined]) {
+                const daemon = await withOwnedManagedSessionContext(inspectionContext, () => inspectManagedSessionDaemon({ ...owner, signal: event.signal, timeoutMs: 2_000 }));
+                if (daemon.status !== "inactive")
+                    return blocked("Browser daemon is live or unverified; finish browser work explicitly before sleep");
+            }
+        }
+        // No detached writer remains to pause/resume. Native ingress stays held;
+        // checkpoint never closes a browser or changes ordinary shutdown ownership.
+        return { sleepReady: true };
+    });
     pi.on("session_shutdown", async (event, ctx) => {
         for (const controller of activeScriptControllers)
             controller.abort();
@@ -1361,474 +1435,514 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             component.setState(formatAgentBrowserRenderResult(result, options, theme, context.isError), options.expanded, theme);
             return component;
         },
-        async execute(toolCallId, params, signal, onUpdate, ctx, nativeToolCallId = toolCallId) {
+        async execute(toolCallId, params, signal, onUpdate, ctx, nativeToolCallId = toolCallId, capturedCwd) {
+            let operationCwd;
+            try {
+                operationCwd = capturedCwd ?? resolveExecutionCwd(pi, ctx);
+            }
+            catch (error) {
+                return buildValidationFailureResult({ kind: "invalid", status: "invalid", redactedArgs: [], toolArgs: [], validationError: error instanceof Error ? error.message : String(error) });
+            }
             const promptPolicy = buildPromptPolicy(getLatestUserPrompt(ctx.sessionManager.getBranch()));
             const outputPath = isRecord(params) && typeof params.outputPath === "string" ? params.outputPath : undefined;
-            const resolvedInput = resolveAgentBrowserInput({
-                getBatchPreflightValidationError: (args, stdin) => getArtifactPreflightValidationError({ args, cwd: ctx.cwd, outputPath, stdin }),
+            const admittedInput = resolveAgentBrowserInput({
+                getBatchPreflightValidationError: (args, stdin) => getArtifactPreflightValidationError({ args, cwd: operationCwd, outputPath, stdin }),
                 params,
             });
-            if (resolvedInput.status === "invalid") {
-                return buildValidationFailureResult(resolvedInput);
+            if (admittedInput.status === "invalid") {
+                return buildValidationFailureResult(admittedInput);
             }
-            if (resolvedInput.kind !== "script")
-                await beforeExecute?.(nativeToolCallId, { ...ctx, signal });
-            const runtimeBrowserConfig = loadAgentBrowserConfigSync({ cwd: ctx.cwd, includeProjectConfig: shouldIncludeProjectConfig(ctx) });
-            const rootProfile = runtimeBrowserConfig.trustedBrowserDefaultProfile;
-            const pendingReadConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE));
-            const rootSessionId = process.env.PI_SUBAGENT_CHILD === "1" && process.env.PI_SUBAGENT_ROOT_SESSION_ID
-                ? process.env.PI_SUBAGENT_ROOT_SESSION_ID : ctx.sessionManager.getSessionId();
-            return withNativeSessionDefaults(resolvedInput, ctx.cwd, signal, async (resolvedInput, withLaunchDefaults) => {
-                const readConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE));
-                if (readConfirmation)
-                    resolvedInput = { ...resolvedInput, toolArgs: scopeReadConfirmationArgs(resolvedInput.toolArgs, readConfirmation) };
-                if (resolvedInput.kind === "qa" && resolvedInput.compiledQaPreset.checks.attached && !managedSessionActive && !extractExplicitSessionName(resolvedInput.toolArgs)) {
-                    return buildValidationFailureResult({ ...resolvedInput, attemptedKind: "qa", kind: "invalid", status: "invalid", validationError: "qa.attached requires an active attached session. Run electron.launch or connect to an Electron debug port first, or configure a native shared session." });
+            const explicitConfig = scanUpstreamGlobalFlagOccurrences(admittedInput.toolArgs, "--config").length > 0 || getAgentBrowserProcessEnvironment().AGENT_BROWSER_CONFIG !== undefined;
+            // Managed selection must follow earlier queued fresh launches, while file paths keep their admission snapshot.
+            const managedAtAdmission = admittedInput.kind !== "script" && admittedInput.kind !== "electron"
+                && !extractExplicitSessionName(admittedInput.toolArgs) && !explicitConfig;
+            const artifactsAtAdmission = managedAtAdmission && commandTouchesArtifactLifecycle(admittedInput.toolArgs, admittedInput.toolStdin, outputPath);
+            const withManagedQueue = (run) => managedAtAdmission ? run() : managedSessionExecutionQueue.run(run);
+            const withArtifactQueue = (run) => artifactsAtAdmission ? run() : artifactExecutionQueue.run(run);
+            const executeAdmitted = async () => {
+                let resolvedInput = admittedInput;
+                const requestedSession = extractExplicitSessionName(resolvedInput.toolArgs);
+                const requestedNamespace = resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+                const requestedOwner = requestedSession ? ownedManagedSessions.get(getSessionContextKey(requestedSession, requestedNamespace) ?? requestedSession) : undefined;
+                const browserCwd = (params.sessionMode === "fresh" && !requestedSession) || explicitConfig ? operationCwd
+                    : requestedSession ? requestedOwner?.cwd ?? ctx.cwd : managedSessionActive ? managedSessionCwd : ctx.cwd;
+                const browserCwdError = resolvedInput.kind === "electron" ? undefined : getBrowserCwdError(browserCwd);
+                if (browserCwdError)
+                    return buildValidationFailureResult({ ...resolvedInput, attemptedKind: resolvedInput.kind, kind: "invalid", status: "invalid", validationError: browserCwdError });
+                if (!isPlainTextInspectionArgs(resolvedInput.toolArgs) && (operationCwd !== browserCwd || operationCwd !== ctx.cwd)) {
+                    const bound = resolveOperationPaths(resolvedInput.toolArgs, resolvedInput.toolStdin, operationCwd);
+                    resolvedInput = { ...resolvedInput, toolArgs: bound.args, toolStdin: bound.stdin };
                 }
-                const applyUnserializedOutputPath = async (result, preserveTextContent = false) => {
-                    if (!outputPath || !canWriteAgentBrowserOutput(result))
-                        return warnRecordingPersistence(result);
-                    return artifactExecutionQueue.run(async () => {
-                        flushRecordingReservations();
-                        const reservationError = getArtifactPreflightValidationError({
-                            activeRecordingReservations: activeRecordingReservations.values(),
-                            args: [],
-                            cwd: ctx.cwd,
-                            outputPath,
-                        });
-                        if (reservationError) {
-                            return warnRecordingPersistence(buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError }));
-                        }
-                        return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent, result: warnRecordingPersistence(result) });
-                    });
-                };
-                const versionCheckCommand = extractUpstreamCommandTokens(resolvedInput.toolArgs)[0];
-                const electronHostOnlyAction = resolvedInput.kind === "electron" && ["cleanup", "list", "status"].includes(resolvedInput.compiledElectron.action);
-                const browserBackedVersionCheck = readConfirmation?.capabilities?.readRequiresConfirmation !== true && needsManagedSession(parseArgvDescriptor(resolvedInput.toolArgs), resolvedInput.toolStdin);
-                if (resolvedInput.kind !== "script" && !electronHostOnlyAction && browserBackedVersionCheck && !isPlainTextInspectionArgs(resolvedInput.toolArgs) && !isCloseCommand(versionCheckCommand) && signal?.aborted !== true) {
-                    const versionFailure = await validateUpstreamVersion(ctx.cwd, signal);
-                    if (versionFailure)
-                        return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result: versionFailure });
-                }
-                if (resolvedInput.kind === "script") {
-                    if (!ctx.sessionManager.getSessionFile()) {
-                        return buildValidationFailureResult({
-                            attemptedKind: "script",
-                            kind: "invalid",
-                            redactedArgs: [],
-                            status: "invalid",
-                            toolArgs: [],
-                            validationError: "script requires a persisted Pi session so its isolated browser-session cleanup lease survives restart; relaunch Pi without --no-session.",
-                        });
+                if (resolvedInput.kind !== "script")
+                    await beforeExecute?.(nativeToolCallId, { ...ctx, signal });
+                const runtimeBrowserConfig = loadAgentBrowserConfigSync({ cwd: ctx.cwd, includeProjectConfig: shouldIncludeProjectConfig(ctx) });
+                const rootProfile = runtimeBrowserConfig.trustedBrowserDefaultProfile;
+                const pendingReadConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE));
+                const rootSessionId = process.env.PI_SUBAGENT_CHILD === "1" && process.env.PI_SUBAGENT_ROOT_SESSION_ID
+                    ? process.env.PI_SUBAGENT_ROOT_SESSION_ID : ctx.sessionManager.getSessionId();
+                return withNativeSessionDefaults(resolvedInput, browserCwd, signal, async (resolvedInput, withLaunchDefaults) => {
+                    const readConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE));
+                    if (readConfirmation)
+                        resolvedInput = { ...resolvedInput, toolArgs: scopeReadConfirmationArgs(resolvedInput.toolArgs, readConfirmation) };
+                    if (resolvedInput.kind === "qa" && resolvedInput.compiledQaPreset.checks.attached && !managedSessionActive && !extractExplicitSessionName(resolvedInput.toolArgs)) {
+                        return buildValidationFailureResult({ ...resolvedInput, attemptedKind: "qa", kind: "invalid", status: "invalid", validationError: "qa.attached requires an active attached session. Run electron.launch or connect to an Electron debug port first, or configure a native shared session." });
                     }
-                    const sessionName = createAgentBrowserScriptSessionName();
-                    const innerResults = [];
-                    const scriptTimeoutMs = params.timeoutMs ?? AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS;
-                    const deadline = Date.now() + scriptTimeoutMs;
-                    let leased = false;
-                    let cleanupError;
-                    let run = {
-                        callCount: 0,
-                        emitCount: 0,
-                        error: "Script sandbox execution failed.",
-                        failureCategory: "upstream-error",
-                        ok: false,
-                        rejectedCallCount: 0,
-                        steps: [],
+                    const applyUnserializedOutputPath = async (result, preserveTextContent = false) => {
+                        if (!outputPath || !canWriteAgentBrowserOutput(result))
+                            return warnRecordingPersistence(result);
+                        return withArtifactQueue(async () => {
+                            flushRecordingReservations();
+                            const reservationError = getArtifactPreflightValidationError({
+                                activeRecordingReservations: activeRecordingReservations.values(),
+                                args: [],
+                                cwd: operationCwd,
+                                outputPath,
+                            });
+                            if (reservationError) {
+                                return warnRecordingPersistence(buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError }));
+                            }
+                            return applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, preserveTextContent, result: warnRecordingPersistence(result) });
+                        });
                     };
-                    const scriptController = new AbortController();
-                    const abortScript = () => scriptController.abort();
-                    signal?.addEventListener("abort", abortScript, { once: true });
-                    if (signal?.aborted)
-                        scriptController.abort();
-                    activeScriptControllers.add(scriptController);
-                    let finishScriptExecution;
-                    const scriptExecution = new Promise((resolve) => {
-                        finishScriptExecution = resolve;
-                    });
-                    activeScriptExecutions.add(scriptExecution);
-                    try {
-                        // Keep preflight inside shutdown tracking so quit cannot race into starting the sandbox afterward.
-                        const versionFailure = await withIsolatedAgentBrowserEnvironment(() => validateUpstreamVersion(ctx.cwd, scriptController.signal));
+                    const versionCheckCommand = extractUpstreamCommandTokens(resolvedInput.toolArgs)[0];
+                    const electronHostOnlyAction = resolvedInput.kind === "electron" && ["cleanup", "list", "status"].includes(resolvedInput.compiledElectron.action);
+                    const browserBackedVersionCheck = readConfirmation?.capabilities?.readRequiresConfirmation !== true && needsManagedSession(parseArgvDescriptor(resolvedInput.toolArgs), resolvedInput.toolStdin);
+                    if (resolvedInput.kind !== "script" && !electronHostOnlyAction && browserBackedVersionCheck && !isPlainTextInspectionArgs(resolvedInput.toolArgs) && !isCloseCommand(versionCheckCommand) && signal?.aborted !== true) {
+                        const versionFailure = await validateUpstreamVersion(browserCwd, signal);
                         if (versionFailure)
-                            return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result: versionFailure });
-                        const pendingRun = runAgentBrowserScript({
-                            beforeFirstCall() {
-                                appendScriptSessionLease(pi, sessionName, "active");
-                                trackOwnedManagedSession(ownedManagedSessions, sessionName, ctx.cwd, { namespace: AGENT_BROWSER_SCRIPT_NAMESPACE });
-                                managedSessionRestoreState.disable(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE);
-                                // This fresh, unselectable lease owns any daemon its first read starts.
-                                managedSessionRestoreState.recordDaemonRestoreKey(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE, null);
-                                leased = true;
-                            },
-                            code: resolvedInput.compiledScript.code,
-                            dispatch: async (innerParams, innerSignal) => {
-                                const remainingMs = Math.max(1, deadline - Date.now());
-                                const innerTimeoutMs = Math.min(innerParams.timeoutMs ?? remainingMs, remainingMs);
-                                const innerResult = await withIsolatedAgentBrowserEnvironment(() => agentBrowserTool.execute(`${toolCallId}:script:${innerResults.length + 1}`, {
-                                    args: ["--namespace", AGENT_BROWSER_SCRIPT_NAMESPACE, "--session", sessionName, ...innerParams.args],
-                                    stdin: innerParams.stdin,
-                                    timeoutMs: innerTimeoutMs,
-                                }, innerSignal, undefined, ctx, nativeToolCallId));
-                                innerResults.push(innerResult);
-                                return await buildScriptBrowserEnvelope(innerResult, innerParams.args, sessionName);
-                            },
-                            signal: scriptController.signal,
-                            timeoutMs: scriptTimeoutMs,
-                        });
-                        run = await pendingRun;
+                            return applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, result: versionFailure });
                     }
-                    catch { }
-                    finally {
-                        activeScriptControllers.delete(scriptController);
-                        signal?.removeEventListener("abort", abortScript);
-                        if (leased) {
-                            try {
-                                cleanupError = await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(() => {
-                                    flushRecordingReservations();
-                                    return closeScriptSessionLeaseWithinQueue(sessionName, ctx.cwd);
-                                }));
-                            }
-                            catch {
-                                cleanupError = "The isolated script session cleanup operation failed.";
-                                try {
-                                    appendScriptSessionLease(pi, sessionName, "failed");
-                                }
-                                catch { }
-                            }
+                    if (resolvedInput.kind === "script") {
+                        if (!ctx.sessionManager.getSessionFile()) {
+                            return buildValidationFailureResult({
+                                attemptedKind: "script",
+                                kind: "invalid",
+                                redactedArgs: [],
+                                status: "invalid",
+                                toolArgs: [],
+                                validationError: "script requires a persisted Pi session so its isolated browser-session cleanup lease survives restart; relaunch Pi without --no-session.",
+                            });
                         }
-                        activeScriptExecutions.delete(scriptExecution);
-                        finishScriptExecution();
-                    }
-                    let scriptResult = buildScriptToolResult({ cleanupError, innerResults, run, sessionName: leased ? sessionName : undefined });
-                    if (artifactManifest) {
-                        scriptResult = {
-                            ...scriptResult,
-                            details: {
-                                ...(isRecord(scriptResult.details) ? scriptResult.details : {}),
-                                artifactManifest: redactSensitiveValue(artifactManifest),
-                                artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
-                            },
+                        const sessionName = createAgentBrowserScriptSessionName();
+                        const innerResults = [];
+                        const scriptTimeoutMs = params.timeoutMs ?? AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS;
+                        const deadline = Date.now() + scriptTimeoutMs;
+                        let leased = false;
+                        let cleanupError;
+                        let run = {
+                            callCount: 0,
+                            emitCount: 0,
+                            error: "Script sandbox execution failed.",
+                            failureCategory: "upstream-error",
+                            ok: false,
+                            rejectedCallCount: 0,
+                            steps: [],
                         };
-                    }
-                    return applyUnserializedOutputPath(scriptResult);
-                }
-                const { toolArgs } = resolvedInput;
-                const compiledElectron = resolvedInput.kind === "electron" ? resolvedInput.compiledElectron : undefined;
-                const redactedCompiledElectron = resolvedInput.kind === "electron" ? resolvedInput.redactedCompiledElectron : undefined;
-                const runElectronHostInput = async () => {
-                    const electronHostLaunchRecords = getElectronHostLaunchRecordsForInput({
-                        branchRecords: electronLaunchRecords,
-                        compiledElectron,
-                        ownedRecords: ownedElectronLaunchRecords,
-                    });
-                    let electronHostResult = await handleElectronHostInput({
-                        attachedSessionKeys,
-                        compiledElectron,
-                        cwd: ctx.cwd,
-                        electronChildProcesses,
-                        electronLaunchRecords: electronHostLaunchRecords,
-                        implicitSessionCloseTimeoutMs,
-                        managedSessionActive,
-                        managedSessionName,
-                        managedSessionNamespace,
-                        managedSessionRestoreState,
-                        ownedManagedSessions,
-                        redactedCompiledElectron,
-                        sessionPageState,
-                        signal,
-                    });
-                    if (electronHostResult && compiledElectron?.action === "cleanup") {
-                        branchStateGeneration += 1;
-                        const cleanupRecords = isRecord(electronHostResult.details)
-                            && isRecord(electronHostResult.details.electron)
-                            && isRecord(electronHostResult.details.electron.cleanup)
-                            && Array.isArray(electronHostResult.details.electron.cleanup.results)
-                            ? electronHostResult.details.electron.cleanup.results
-                            : [];
-                        const cleanedLaunchIds = new Set();
-                        for (const cleanupResult of cleanupRecords) {
-                            if (isRecord(cleanupResult) && isElectronLaunchRecord(cleanupResult.record)) {
-                                cleanedLaunchIds.add(cleanupResult.record.launchId);
-                            }
+                        const scriptController = new AbortController();
+                        const abortScript = () => scriptController.abort();
+                        signal?.addEventListener("abort", abortScript, { once: true });
+                        if (signal?.aborted)
+                            scriptController.abort();
+                        activeScriptControllers.add(scriptController);
+                        let finishScriptExecution;
+                        const scriptExecution = new Promise((resolve) => {
+                            finishScriptExecution = resolve;
+                        });
+                        activeScriptExecutions.add(scriptExecution);
+                        try {
+                            // Keep preflight inside shutdown tracking so quit cannot race into starting the sandbox afterward.
+                            const versionFailure = await withIsolatedAgentBrowserEnvironment(() => validateUpstreamVersion(browserCwd, scriptController.signal));
+                            if (versionFailure)
+                                return applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, result: versionFailure });
+                            const pendingRun = runAgentBrowserScript({
+                                beforeFirstCall() {
+                                    appendScriptSessionLease(pi, sessionName, "active");
+                                    trackOwnedManagedSession(ownedManagedSessions, sessionName, ctx.cwd, { namespace: AGENT_BROWSER_SCRIPT_NAMESPACE });
+                                    managedSessionRestoreState.disable(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE);
+                                    // This fresh, unselectable lease owns any daemon its first read starts.
+                                    managedSessionRestoreState.recordDaemonRestoreKey(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE, null);
+                                    leased = true;
+                                },
+                                code: resolvedInput.compiledScript.code,
+                                dispatch: async (innerParams, innerSignal) => {
+                                    const remainingMs = Math.max(1, deadline - Date.now());
+                                    const innerTimeoutMs = Math.min(innerParams.timeoutMs ?? remainingMs, remainingMs);
+                                    const innerResult = await withIsolatedAgentBrowserEnvironment(() => agentBrowserTool.execute(`${toolCallId}:script:${innerResults.length + 1}`, {
+                                        args: ["--namespace", AGENT_BROWSER_SCRIPT_NAMESPACE, "--session", sessionName, ...innerParams.args],
+                                        stdin: innerParams.stdin,
+                                        timeoutMs: innerTimeoutMs,
+                                    }, innerSignal, undefined, ctx, nativeToolCallId, operationCwd));
+                                    innerResults.push(innerResult);
+                                    return await buildScriptBrowserEnvelope(innerResult, innerParams.args, sessionName);
+                                },
+                                signal: scriptController.signal,
+                                timeoutMs: scriptTimeoutMs,
+                            });
+                            run = await pendingRun;
                         }
-                        replaceWithActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronHostLaunchRecords, branchOwnedElectronLaunchIds, cleanedLaunchIds);
-                        mergeElectronCleanupRecords(electronLaunchRecords, cleanupRecords);
-                        const cleanupNamespace = isRecord(electronHostResult.details) && typeof electronHostResult.details.namespace === "string"
-                            ? electronHostResult.details.namespace
-                            : undefined;
-                        const closedSessionIdentities = getCleanupResultsClosedManagedSessionIdentities(cleanupRecords, cleanupNamespace);
-                        syncElectronCleanupManagedSessions(ownedManagedSessions, cleanupRecords, cleanupNamespace);
-                        for (const identity of closedSessionIdentities) {
-                            retireRecordingSession(identity.sessionName, identity.namespace);
-                            const closedSessionKey = getSessionContextKey(identity.sessionName, identity.namespace) ?? identity.sessionName;
-                            clearSessionScopedBrowserState(closedSessionKey);
-                            if (closedSessionKey === (getSessionContextKey(managedSessionName, managedSessionNamespace) ?? managedSessionName)) {
-                                managedSessionActive = false;
-                                managedSessionCompatibilityWorkaround = undefined;
-                                managedSessionHeadedAutosaveDisabled = false;
-                                managedSessionHeadedAutosaveInterval = undefined;
-                                managedSessionNamespace = undefined;
-                                freshSessionOrdinal += 1;
-                                managedSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal);
+                        catch { }
+                        finally {
+                            activeScriptControllers.delete(scriptController);
+                            signal?.removeEventListener("abort", abortScript);
+                            if (leased) {
+                                try {
+                                    cleanupError = await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(() => {
+                                        flushRecordingReservations();
+                                        return closeScriptSessionLeaseWithinQueue(sessionName, ctx.cwd);
+                                    }));
+                                }
+                                catch {
+                                    cleanupError = "The isolated script session cleanup operation failed.";
+                                    try {
+                                        appendScriptSessionLease(pi, sessionName, "failed");
+                                    }
+                                    catch { }
+                                }
                             }
+                            activeScriptExecutions.delete(scriptExecution);
+                            finishScriptExecution();
                         }
+                        let scriptResult = buildScriptToolResult({ cleanupError, innerResults, run, sessionName: leased ? sessionName : undefined });
                         if (artifactManifest) {
-                            electronHostResult = {
-                                ...electronHostResult,
+                            scriptResult = {
+                                ...scriptResult,
                                 details: {
-                                    ...(isRecord(electronHostResult.details) ? electronHostResult.details : {}),
+                                    ...(isRecord(scriptResult.details) ? scriptResult.details : {}),
                                     artifactManifest: redactSensitiveValue(artifactManifest),
                                     artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
                                 },
                             };
                         }
+                        return applyUnserializedOutputPath(scriptResult);
                     }
-                    return electronHostResult;
-                };
-                const runSerializedElectronHostInput = () => shouldSerializeElectronHostInput(compiledElectron)
-                    ? managedSessionExecutionQueue.run(runElectronHostInput)
-                    : runElectronHostInput();
-                const electronHostResult = compiledElectron?.action === "cleanup"
-                    ? await artifactExecutionQueue.run(async () => {
-                        flushRecordingReservations();
-                        const reservationError = outputPath ? getArtifactPreflightValidationError({
-                            activeRecordingReservations: activeRecordingReservations.values(),
-                            args: [],
+                    const { toolArgs } = resolvedInput;
+                    const compiledElectron = resolvedInput.kind === "electron" ? resolvedInput.compiledElectron : undefined;
+                    const redactedCompiledElectron = resolvedInput.kind === "electron" ? resolvedInput.redactedCompiledElectron : undefined;
+                    const runElectronHostInput = async () => {
+                        const electronHostLaunchRecords = getElectronHostLaunchRecordsForInput({
+                            branchRecords: electronLaunchRecords,
+                            compiledElectron,
+                            ownedRecords: ownedElectronLaunchRecords,
+                        });
+                        let electronHostResult = await handleElectronHostInput({
+                            attachedSessionKeys,
+                            compiledElectron,
                             cwd: ctx.cwd,
-                            outputPath,
-                        }) : undefined;
-                        if (reservationError) {
-                            return warnRecordingPersistence(buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError }));
+                            electronChildProcesses,
+                            electronLaunchRecords: electronHostLaunchRecords,
+                            implicitSessionCloseTimeoutMs,
+                            managedSessionActive,
+                            managedSessionName,
+                            managedSessionNamespace,
+                            managedSessionRestoreState,
+                            ownedManagedSessions,
+                            redactedCompiledElectron,
+                            sessionPageState,
+                            signal,
+                        });
+                        if (electronHostResult && compiledElectron?.action === "cleanup") {
+                            branchStateGeneration += 1;
+                            const cleanupRecords = isRecord(electronHostResult.details)
+                                && isRecord(electronHostResult.details.electron)
+                                && isRecord(electronHostResult.details.electron.cleanup)
+                                && Array.isArray(electronHostResult.details.electron.cleanup.results)
+                                ? electronHostResult.details.electron.cleanup.results
+                                : [];
+                            const cleanedLaunchIds = new Set();
+                            for (const cleanupResult of cleanupRecords) {
+                                if (isRecord(cleanupResult) && isElectronLaunchRecord(cleanupResult.record)) {
+                                    cleanedLaunchIds.add(cleanupResult.record.launchId);
+                                }
+                            }
+                            replaceWithActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronHostLaunchRecords, branchOwnedElectronLaunchIds, cleanedLaunchIds);
+                            mergeElectronCleanupRecords(electronLaunchRecords, cleanupRecords);
+                            const cleanupNamespace = isRecord(electronHostResult.details) && typeof electronHostResult.details.namespace === "string"
+                                ? electronHostResult.details.namespace
+                                : undefined;
+                            const closedSessionIdentities = getCleanupResultsClosedManagedSessionIdentities(cleanupRecords, cleanupNamespace);
+                            syncElectronCleanupManagedSessions(ownedManagedSessions, cleanupRecords, cleanupNamespace);
+                            for (const identity of closedSessionIdentities) {
+                                retireRecordingSession(identity.sessionName, identity.namespace);
+                                const closedSessionKey = getSessionContextKey(identity.sessionName, identity.namespace) ?? identity.sessionName;
+                                clearSessionScopedBrowserState(closedSessionKey);
+                                if (closedSessionKey === (getSessionContextKey(managedSessionName, managedSessionNamespace) ?? managedSessionName)) {
+                                    managedSessionActive = false;
+                                    managedSessionCompatibilityWorkaround = undefined;
+                                    managedSessionHeadedAutosaveDisabled = false;
+                                    managedSessionHeadedAutosaveInterval = undefined;
+                                    managedSessionNamespace = undefined;
+                                    freshSessionOrdinal += 1;
+                                    managedSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal);
+                                }
+                            }
+                            if (artifactManifest) {
+                                electronHostResult = {
+                                    ...electronHostResult,
+                                    details: {
+                                        ...(isRecord(electronHostResult.details) ? electronHostResult.details : {}),
+                                        artifactManifest: redactSensitiveValue(artifactManifest),
+                                        artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
+                                    },
+                                };
+                            }
                         }
-                        const result = await runSerializedElectronHostInput();
-                        return result ? applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result: warnRecordingPersistence(result) }) : result;
-                    })
-                    : await runSerializedElectronHostInput();
-                if (electronHostResult) {
-                    return compiledElectron?.action === "cleanup" ? electronHostResult : applyUnserializedOutputPath(electronHostResult);
-                }
-                const explicitSessionName = extractExplicitSessionName(toolArgs);
-                const callerOwnedSessionNamespace = explicitSessionName
-                    ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
-                    : undefined;
-                const serializeBrowserCommand = shouldSerializeBrowserCommand({
-                    namespace: callerOwnedSessionNamespace,
-                    explicitSessionName,
-                    managedSessionName,
-                    ownedElectronLaunchRecords,
-                    ownedManagedSessions,
-                });
-                const callerOwnedSessionQueueKey = !serializeBrowserCommand && explicitSessionName
-                    ? getSessionContextKey(explicitSessionName, callerOwnedSessionNamespace) ?? explicitSessionName
-                    : undefined;
-                const runBrowserCommand = async (daemonInactive) => {
-                    flushRecordingReservations();
-                    const branchRestoreGenerationAtStart = branchRestoreGeneration;
-                    const generationAtStart = branchStateGeneration;
-                    const sessionPageStateUpdate = sessionPageState.beginUpdate();
-                    const browserRunState = {
-                        activeRecordingReservations,
-                        artifactManifest,
-                        attachedSessionKeys,
-                        closedManagedSessionNames: new Set(),
-                        electronChildProcesses,
-                        electronLaunchRecords,
-                        ephemeralSessionSeed,
-                        freshSessionOrdinal,
-                        managedSessionActive,
-                        managedSessionBaseName,
-                        managedSessionCompatibilityWorkaround,
-                        managedSessionHeadedAutosaveDisabled,
-                        managedSessionHeadedAutosaveInterval,
-                        managedSessionCwd,
+                        return electronHostResult;
+                    };
+                    const runSerializedElectronHostInput = () => shouldSerializeElectronHostInput(compiledElectron)
+                        ? managedSessionExecutionQueue.run(runElectronHostInput)
+                        : runElectronHostInput();
+                    const electronHostResult = compiledElectron?.action === "cleanup"
+                        ? await artifactExecutionQueue.run(async () => {
+                            flushRecordingReservations();
+                            const reservationError = outputPath ? getArtifactPreflightValidationError({
+                                activeRecordingReservations: activeRecordingReservations.values(),
+                                args: [],
+                                cwd: operationCwd,
+                                outputPath,
+                            }) : undefined;
+                            if (reservationError) {
+                                return warnRecordingPersistence(buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError }));
+                            }
+                            const result = await runSerializedElectronHostInput();
+                            return result ? applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, result: warnRecordingPersistence(result) }) : result;
+                        })
+                        : await runSerializedElectronHostInput();
+                    if (electronHostResult) {
+                        return compiledElectron?.action === "cleanup" ? electronHostResult : applyUnserializedOutputPath(electronHostResult);
+                    }
+                    const explicitSessionName = extractExplicitSessionName(toolArgs);
+                    const callerOwnedSessionNamespace = explicitSessionName
+                        ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
+                        : undefined;
+                    const serializeBrowserCommand = shouldSerializeBrowserCommand({
+                        namespace: callerOwnedSessionNamespace,
+                        explicitSessionName,
                         managedSessionName,
-                        managedSessionNamespace,
-                        managedSessionRestoreState,
-                        networkRoutesBySession,
+                        ownedElectronLaunchRecords,
                         ownedManagedSessions,
-                        sessionPageState,
-                        traceOwners,
-                    };
-                    const selectedPlan = buildExecutionPlan(toolArgs, {
-                        freshSessionName: createFreshSessionName(browserRunState.managedSessionBaseName, browserRunState.ephemeralSessionSeed, browserRunState.freshSessionOrdinal + 1),
-                        managedSessionActive: browserRunState.managedSessionActive,
-                        managedSessionCompatibilityWorkaround: browserRunState.managedSessionCompatibilityWorkaround,
-                        managedSessionName: browserRunState.managedSessionName,
-                        managedSessionNamespace: browserRunState.managedSessionNamespace,
-                        sessionMode: compiledElectron?.action === "launch" ? "fresh" : params.sessionMode ?? "auto",
-                        stdin: resolvedInput.toolStdin,
-                        browserIndependentReadConfirmation: readConfirmation?.capabilities?.readRequiresConfirmation === true,
                     });
-                    const initialArtifactManifest = browserRunState.artifactManifest;
-                    const initialNetworkRoutesBySession = browserRunState.networkRoutesBySession;
-                    const attachedSessionRequested = isAttachedBrowserInvocation(toolArgs)
-                        || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch");
-                    const allocatesFreshManagedSession = explicitSessionName === undefined
-                        && (params.sessionMode === "fresh" || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch"));
-                    const reusableSessionKey = allocatesFreshManagedSession
-                        ? undefined
-                        : getSessionContextKey(selectedPlan.sessionName, selectedPlan.namespace)
-                            ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
-                    const attachedSessionKnown = reusableSessionKey !== undefined && attachedSessionKeys.has(reusableSessionKey);
-                    let result = await runAgentBrowserTool({
-                        daemonInactive,
-                        ctx,
-                        cwd: ctx.cwd,
-                        electronPostCommandStatusSettleMs: ELECTRON_POST_COMMAND_STATUS_SETTLE_MS,
-                        electronProfileIsolationDetails: ELECTRON_PROFILE_ISOLATION_DETAILS,
-                        implicitSessionCloseTimeoutMs,
-                        implicitSessionIdleTimeoutMs,
-                        input: resolvedInput,
-                        onUpdate,
-                        params,
-                        establishAttachedBrowserSession: attachedSessionRequested && !attachedSessionKnown,
-                        preserveAttachedBrowserSession: attachedSessionRequested || attachedSessionKnown,
-                        promptPolicy,
-                        sessionPageStateUpdate,
-                        signal,
-                        state: browserRunState,
-                    });
-                    const branchRestoreStillCurrent = branchRestoreGenerationAtStart === branchRestoreGeneration;
-                    const resultDetails = isRecord(result.details) ? result.details : undefined;
-                    const resultSessionName = typeof resultDetails?.sessionName === "string"
-                        ? resultDetails.sessionName
-                        : extractExplicitSessionName(toolArgs);
-                    const resultNamespace = typeof resultDetails?.namespace === "string"
-                        ? resultDetails.namespace
-                        : selectedPlan.namespace;
-                    if (branchRestoreStillCurrent) {
-                        const resultBatchCloseLifecycle = getSuccessfulBatchCloseLifecycle(resultDetails?.batchSteps);
-                        const resultSessionKey = getSessionContextKey(resultSessionName, resultNamespace) ?? resultSessionName;
-                        const managedSessionOutcome = isRecord(resultDetails?.managedSessionOutcome) ? resultDetails.managedSessionOutcome : undefined;
-                        const closeAllApplied = resultDetails?.closeAllApplied === true;
-                        const attachedSessionRemainsActive = result.isError !== true
-                            || ((attachedSessionRequested || attachedSessionKnown) && managedSessionOutcome?.activeAfter === true);
-                        const closesAttachedSession = (result.isError !== true && isCloseCommand(extractUpstreamCommandTokens(toolArgs)[0]))
-                            || resultBatchCloseLifecycle?.endsClosed === true;
-                        if (closeAllApplied) {
-                            deleteIdentityKeysInNamespace(attachedSessionKeys, resultNamespace);
-                            if (resultSessionKey && attachedSessionRemainsActive && (attachedSessionRequested || attachedSessionKnown) && resultBatchCloseLifecycle?.endsClosed === false) {
+                    const callerOwnedSessionQueueKey = !serializeBrowserCommand && explicitSessionName
+                        ? getSessionContextKey(explicitSessionName, callerOwnedSessionNamespace) ?? explicitSessionName
+                        : undefined;
+                    const runBrowserCommand = async (daemonInactive) => {
+                        // Load execution-only preparation/output code inside the existing session queue,
+                        // before capturing state. Registration, rendering, and restore stay synchronous/eager.
+                        const { runAgentBrowserTool } = await import("./lib/orchestration/browser-run/index.js");
+                        flushRecordingReservations();
+                        const branchRestoreGenerationAtStart = branchRestoreGeneration;
+                        const generationAtStart = branchStateGeneration;
+                        const sessionPageStateUpdate = sessionPageState.beginUpdate();
+                        const browserRunState = {
+                            activeRecordingReservations,
+                            artifactManifest,
+                            attachedSessionKeys,
+                            closedManagedSessionNames: new Set(),
+                            electronChildProcesses,
+                            electronLaunchRecords,
+                            ephemeralSessionSeed,
+                            freshSessionOrdinal,
+                            managedSessionActive,
+                            managedSessionBaseName,
+                            managedSessionCompatibilityWorkaround,
+                            managedSessionHeadedAutosaveDisabled,
+                            managedSessionHeadedAutosaveInterval,
+                            managedSessionCwd,
+                            managedSessionName,
+                            managedSessionNamespace,
+                            managedSessionRestoreState,
+                            networkRoutesBySession,
+                            ownedManagedSessions,
+                            sessionPageState,
+                            traceOwners,
+                        };
+                        const selectedPlan = buildExecutionPlan(toolArgs, {
+                            freshSessionName: createFreshSessionName(browserRunState.managedSessionBaseName, browserRunState.ephemeralSessionSeed, browserRunState.freshSessionOrdinal + 1),
+                            managedSessionActive: browserRunState.managedSessionActive,
+                            managedSessionCompatibilityWorkaround: browserRunState.managedSessionCompatibilityWorkaround,
+                            managedSessionName: browserRunState.managedSessionName,
+                            managedSessionNamespace: browserRunState.managedSessionNamespace,
+                            sessionMode: compiledElectron?.action === "launch" ? "fresh" : params.sessionMode ?? "auto",
+                            stdin: resolvedInput.toolStdin,
+                            browserIndependentReadConfirmation: readConfirmation?.capabilities?.readRequiresConfirmation === true,
+                        });
+                        const initialArtifactManifest = browserRunState.artifactManifest;
+                        const initialNetworkRoutesBySession = browserRunState.networkRoutesBySession;
+                        const attachedSessionRequested = isAttachedBrowserInvocation(toolArgs)
+                            || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch");
+                        const allocatesFreshManagedSession = explicitSessionName === undefined
+                            && (params.sessionMode === "fresh" || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch"));
+                        const reusableSessionKey = allocatesFreshManagedSession
+                            ? undefined
+                            : getSessionContextKey(selectedPlan.sessionName, selectedPlan.namespace)
+                                ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
+                        const attachedSessionKnown = reusableSessionKey !== undefined && attachedSessionKeys.has(reusableSessionKey);
+                        let result = await runAgentBrowserTool({
+                            daemonInactive,
+                            ctx,
+                            cwd: browserCwd,
+                            operationCwd,
+                            electronPostCommandStatusSettleMs: ELECTRON_POST_COMMAND_STATUS_SETTLE_MS,
+                            electronProfileIsolationDetails: ELECTRON_PROFILE_ISOLATION_DETAILS,
+                            implicitSessionCloseTimeoutMs,
+                            implicitSessionIdleTimeoutMs,
+                            input: resolvedInput,
+                            onUpdate,
+                            params,
+                            establishAttachedBrowserSession: attachedSessionRequested && !attachedSessionKnown,
+                            preserveAttachedBrowserSession: attachedSessionRequested || attachedSessionKnown,
+                            promptPolicy,
+                            sessionPageStateUpdate,
+                            signal,
+                            state: browserRunState,
+                        });
+                        const branchRestoreStillCurrent = branchRestoreGenerationAtStart === branchRestoreGeneration;
+                        const resultDetails = isRecord(result.details) ? result.details : undefined;
+                        if (resultDetails?.sessionName === browserRunState.managedSessionName && resultDetails.namespace === browserRunState.managedSessionNamespace && browserRunState.managedSessionActive) {
+                            resultDetails.managedSessionCwd = browserRunState.managedSessionCwd;
+                        }
+                        const resultSessionName = typeof resultDetails?.sessionName === "string"
+                            ? resultDetails.sessionName
+                            : extractExplicitSessionName(toolArgs);
+                        const resultNamespace = typeof resultDetails?.namespace === "string"
+                            ? resultDetails.namespace
+                            : selectedPlan.namespace;
+                        if (branchRestoreStillCurrent) {
+                            const resultBatchCloseLifecycle = getSuccessfulBatchCloseLifecycle(resultDetails?.batchSteps);
+                            const resultSessionKey = getSessionContextKey(resultSessionName, resultNamespace) ?? resultSessionName;
+                            const managedSessionOutcome = isRecord(resultDetails?.managedSessionOutcome) ? resultDetails.managedSessionOutcome : undefined;
+                            const closeAllApplied = resultDetails?.closeAllApplied === true;
+                            const attachedSessionRemainsActive = result.isError !== true
+                                || ((attachedSessionRequested || attachedSessionKnown) && managedSessionOutcome?.activeAfter === true);
+                            const closesAttachedSession = (result.isError !== true && isCloseCommand(extractUpstreamCommandTokens(toolArgs)[0]))
+                                || resultBatchCloseLifecycle?.endsClosed === true;
+                            if (closeAllApplied) {
+                                deleteIdentityKeysInNamespace(attachedSessionKeys, resultNamespace);
+                                if (resultSessionKey && attachedSessionRemainsActive && (attachedSessionRequested || attachedSessionKnown) && resultBatchCloseLifecycle?.endsClosed === false) {
+                                    attachedSessionKeys.add(resultSessionKey);
+                                    result = { ...result, details: { ...(resultDetails ?? {}), attachedBrowserSession: true } };
+                                }
+                            }
+                            else if (resultSessionKey && closesAttachedSession)
+                                attachedSessionKeys.delete(resultSessionKey);
+                            else if (resultSessionKey && attachedSessionRemainsActive && (attachedSessionRequested || attachedSessionKnown)) {
                                 attachedSessionKeys.add(resultSessionKey);
                                 result = { ...result, details: { ...(resultDetails ?? {}), attachedBrowserSession: true } };
                             }
                         }
-                        else if (resultSessionKey && closesAttachedSession)
-                            attachedSessionKeys.delete(resultSessionKey);
-                        else if (resultSessionKey && attachedSessionRemainsActive && (attachedSessionRequested || attachedSessionKnown)) {
-                            attachedSessionKeys.add(resultSessionKey);
-                            result = { ...result, details: { ...(resultDetails ?? {}), attachedBrowserSession: true } };
-                        }
-                    }
-                    if (branchRestoreStillCurrent) {
-                        networkRoutesBySession = mergeBrowserRunMap(networkRoutesBySession, initialNetworkRoutesBySession, browserRunState.networkRoutesBySession);
-                        artifactManifest = mergeBrowserRunArtifactManifest(artifactManifest, initialArtifactManifest, browserRunState.artifactManifest);
-                        const handledBatchCloseKeys = syncRecordingReservationsFromResult(result);
-                        if (resultDetails?.closeAllApplied === true) {
-                            for (const [sessionKey, reservation] of [...activeRecordingReservations]) {
-                                if (isAgentBrowserSessionIdentityKeyInNamespace(sessionKey, resultNamespace)) {
-                                    retireRecordingSession(reservation.sessionName, reservation.namespace);
+                        if (branchRestoreStillCurrent) {
+                            networkRoutesBySession = mergeBrowserRunMap(networkRoutesBySession, initialNetworkRoutesBySession, browserRunState.networkRoutesBySession);
+                            artifactManifest = mergeBrowserRunArtifactManifest(artifactManifest, initialArtifactManifest, browserRunState.artifactManifest);
+                            const handledBatchCloseKeys = syncRecordingReservationsFromResult(result);
+                            if (resultDetails?.closeAllApplied === true) {
+                                for (const [sessionKey, reservation] of [...activeRecordingReservations]) {
+                                    if (isAgentBrowserSessionIdentityKeyInNamespace(sessionKey, resultNamespace)) {
+                                        retireRecordingSession(reservation.sessionName, reservation.namespace);
+                                    }
                                 }
                             }
+                            for (const closedSessionKey of browserRunState.closedManagedSessionNames) {
+                                if (handledBatchCloseKeys.has(closedSessionKey))
+                                    continue;
+                                const reservation = activeRecordingReservations.get(closedSessionKey);
+                                if (reservation)
+                                    retireRecordingSession(reservation.sessionName, reservation.namespace);
+                            }
+                            if (resultSessionName) {
+                                const reservation = activeRecordingReservations.get(getAgentBrowserSessionIdentityKey(resultSessionName, resultNamespace));
+                                if (reservation)
+                                    result = appendActiveRecordingCleanupAction(result, reservation);
+                            }
+                            if (artifactManifest) {
+                                result = {
+                                    ...result,
+                                    details: {
+                                        ...(isRecord(result.details) ? result.details : {}),
+                                        artifactManifest: redactSensitiveValue(artifactManifest),
+                                        artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
+                                    },
+                                };
+                            }
                         }
-                        for (const closedSessionKey of browserRunState.closedManagedSessionNames) {
-                            if (handledBatchCloseKeys.has(closedSessionKey))
-                                continue;
-                            const reservation = activeRecordingReservations.get(closedSessionKey);
-                            if (reservation)
-                                retireRecordingSession(reservation.sessionName, reservation.namespace);
-                        }
-                        if (resultSessionName) {
-                            const reservation = activeRecordingReservations.get(getAgentBrowserSessionIdentityKey(resultSessionName, resultNamespace));
-                            if (reservation)
-                                result = appendActiveRecordingCleanupAction(result, reservation);
-                        }
-                        if (artifactManifest) {
-                            result = {
-                                ...result,
-                                details: {
-                                    ...(isRecord(result.details) ? result.details : {}),
-                                    artifactManifest: redactSensitiveValue(artifactManifest),
-                                    artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
-                                },
-                            };
-                        }
-                    }
-                    const branchStateStillCurrent = generationAtStart === branchStateGeneration;
-                    if (serializeBrowserCommand || branchStateStillCurrent) {
-                        freshSessionOrdinal = Math.max(freshSessionOrdinal, browserRunState.freshSessionOrdinal);
-                        managedSessionActive = browserRunState.managedSessionActive;
-                        managedSessionCompatibilityWorkaround = browserRunState.managedSessionCompatibilityWorkaround;
-                        managedSessionHeadedAutosaveDisabled = browserRunState.managedSessionHeadedAutosaveDisabled === true;
-                        managedSessionHeadedAutosaveInterval = browserRunState.managedSessionHeadedAutosaveInterval;
-                        managedSessionCwd = browserRunState.managedSessionCwd;
-                        managedSessionName = browserRunState.managedSessionName;
-                        managedSessionNamespace = browserRunState.managedSessionNamespace;
-                        for (const closedSessionName of browserRunState.closedManagedSessionNames) {
-                            untrackOwnedManagedSession(ownedManagedSessions, closedSessionName);
+                        const branchStateStillCurrent = generationAtStart === branchStateGeneration;
+                        if (serializeBrowserCommand || branchStateStillCurrent) {
+                            freshSessionOrdinal = Math.max(freshSessionOrdinal, browserRunState.freshSessionOrdinal);
+                            managedSessionActive = browserRunState.managedSessionActive;
+                            managedSessionCompatibilityWorkaround = browserRunState.managedSessionCompatibilityWorkaround;
+                            managedSessionHeadedAutosaveDisabled = browserRunState.managedSessionHeadedAutosaveDisabled === true;
+                            managedSessionHeadedAutosaveInterval = browserRunState.managedSessionHeadedAutosaveInterval;
+                            managedSessionCwd = browserRunState.managedSessionCwd;
+                            managedSessionName = browserRunState.managedSessionName;
+                            managedSessionNamespace = browserRunState.managedSessionNamespace;
+                            for (const closedSessionName of browserRunState.closedManagedSessionNames) {
+                                untrackOwnedManagedSession(ownedManagedSessions, closedSessionName);
+                            }
+                            syncOwnedManagedSessionsFromResult(ownedManagedSessions, result, browserRunState.managedSessionCwd);
+                            mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
+                                branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
+                                touchedLaunchIds: !result.isError
+                                    ? getTouchedElectronLaunchIds(explicitSessionName ?? browserRunState.managedSessionName, electronLaunchRecords, resultNamespace)
+                                    : undefined,
+                            });
+                            if (serializeBrowserCommand)
+                                branchStateGeneration += 1;
                         }
-                        syncOwnedManagedSessionsFromResult(ownedManagedSessions, result, browserRunState.managedSessionCwd);
-                        mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
-                            branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
-                            touchedLaunchIds: !result.isError
-                                ? getTouchedElectronLaunchIds(explicitSessionName ?? browserRunState.managedSessionName, electronLaunchRecords, resultNamespace)
-                                : undefined,
-                        });
-                        if (serializeBrowserCommand)
-                            branchStateGeneration += 1;
-                    }
-                    return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result: warnRecordingPersistence(result) });
-                };
-                const closesAllSessions = commandClosesAllSessions(toolArgs, resolvedInput.toolStdin);
-                const runWithLaunchDefaults = () => withLaunchDefaults ? withLaunchDefaults(runBrowserCommand) : runBrowserCommand();
-                const runWithinSessionQueue = () => {
-                    if (closesAllSessions)
-                        return managedSessionExecutionQueue.run(() => {
-                            const plan = buildExecutionPlan(toolArgs, {
-                                freshSessionName: createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1),
-                                managedSessionActive,
-                                managedSessionCompatibilityWorkaround,
-                                managedSessionName,
-                                managedSessionNamespace,
-                                sessionMode: params.sessionMode ?? "auto",
-                                stdin: resolvedInput.toolStdin,
+                        return applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result: warnRecordingPersistence(result) });
+                    };
+                    const closesAllSessions = commandClosesAllSessions(toolArgs, resolvedInput.toolStdin);
+                    const runWithLaunchDefaults = () => withLaunchDefaults ? withLaunchDefaults(runBrowserCommand) : runBrowserCommand();
+                    const runWithinSessionQueue = () => {
+                        if (closesAllSessions)
+                            return withManagedQueue(() => {
+                                const plan = buildExecutionPlan(toolArgs, {
+                                    freshSessionName: createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1),
+                                    managedSessionActive,
+                                    managedSessionCompatibilityWorkaround,
+                                    managedSessionName,
+                                    managedSessionNamespace,
+                                    sessionMode: params.sessionMode ?? "auto",
+                                    stdin: resolvedInput.toolStdin,
+                                });
+                                return callerOwnedSessionExecutionQueues.runExclusive(plan.namespace, runWithLaunchDefaults);
                             });
-                            return callerOwnedSessionExecutionQueues.runExclusive(plan.namespace, runWithLaunchDefaults);
+                        if (serializeBrowserCommand)
+                            return withManagedQueue(runWithLaunchDefaults);
+                        return callerOwnedSessionQueueKey
+                            ? callerOwnedSessionExecutionQueues.run(callerOwnedSessionQueueKey, callerOwnedSessionNamespace, runWithLaunchDefaults)
+                            : runWithLaunchDefaults();
+                    };
+                    if (!commandTouchesArtifactLifecycle(toolArgs, resolvedInput.toolStdin, outputPath))
+                        return runWithinSessionQueue();
+                    return withArtifactQueue(async () => {
+                        const artifactValidationError = getArtifactPreflightValidationError({
+                            activeRecordingReservations: activeRecordingReservations.values(),
+                            args: toolArgs,
+                            cwd: operationCwd,
+                            outputPath,
+                            stdin: resolvedInput.toolStdin,
                         });
-                    if (serializeBrowserCommand)
-                        return managedSessionExecutionQueue.run(runWithLaunchDefaults);
-                    return callerOwnedSessionQueueKey
-                        ? callerOwnedSessionExecutionQueues.run(callerOwnedSessionQueueKey, callerOwnedSessionNamespace, runWithLaunchDefaults)
-                        : runWithLaunchDefaults();
-                };
-                if (!commandTouchesArtifactLifecycle(toolArgs, resolvedInput.toolStdin, outputPath))
-                    return runWithinSessionQueue();
-                return artifactExecutionQueue.run(async () => {
-                    const artifactValidationError = getArtifactPreflightValidationError({
-                        activeRecordingReservations: activeRecordingReservations.values(),
-                        args: toolArgs,
-                        cwd: ctx.cwd,
-                        outputPath,
-                        stdin: resolvedInput.toolStdin,
+                        if (!artifactValidationError)
+                            return runWithinSessionQueue();
+                        flushRecordingReservations();
+                        return warnRecordingPersistence(buildValidationFailureResult({
+                            attemptedKind: resolvedInput.kind,
+                            kind: "invalid",
+                            redactedArgs: resolvedInput.redactedArgs,
+                            status: "invalid",
+                            toolArgs: resolvedInput.toolArgs,
+                            toolStdin: resolvedInput.toolStdin,
+                            validationError: artifactValidationError,
+                        }));
                     });
-                    if (!artifactValidationError)
-                        return runWithinSessionQueue();
-                    flushRecordingReservations();
-                    return warnRecordingPersistence(buildValidationFailureResult({
-                        attemptedKind: resolvedInput.kind,
-                        kind: "invalid",
-                        redactedArgs: resolvedInput.redactedArgs,
-                        status: "invalid",
-                        toolArgs: resolvedInput.toolArgs,
-                        toolStdin: resolvedInput.toolStdin,
-                        validationError: artifactValidationError,
-                    }));
+                }, managedSessionActive || freshSessionOrdinal > 0 || params.sessionMode === "fresh" || pendingReadConfirmation ? undefined : {
+                    id: rootSessionId,
+                    profile: rootProfile?.policy === "always" && !/[\\/~]/.test(rootProfile.name) ? rootProfile.name : undefined,
+                    executablePath: runtimeBrowserConfig.trustedBrowserExecutablePath,
                 });
-            }, managedSessionActive || freshSessionOrdinal > 0 || params.sessionMode === "fresh" || pendingReadConfirmation ? undefined : {
-                id: rootSessionId,
-                profile: rootProfile?.policy === "always" && !/[\\/~]/.test(rootProfile.name) ? rootProfile.name : undefined,
-                executablePath: runtimeBrowserConfig.trustedBrowserExecutablePath,
-            });
+            };
+            if (!managedAtAdmission)
+                return executeAdmitted();
+            const executeManaged = () => managedSessionExecutionQueue.run(executeAdmitted);
+            return artifactsAtAdmission ? artifactExecutionQueue.run(executeManaged) : executeManaged();
         },
     };
     pi.registerTool(beforeExecute ? { ...agentBrowserTool, executionMode: "sequential" } : agentBrowserTool);