pi-agent-browser-native 0.6.16 → 0.7.0

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

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -5,30 +6,35 @@ import { Text } from "@earendil-works/pi-tui";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./lib/batch-lifecycle.js";
 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 { appendBrowserTransition, getBrowserResultMessage } from "./lib/browser-transcript.js";
+import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractUpstreamCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, redactInvocationArgs, redactSensitiveText, redactSensitiveValue, isPlainTextInspectionArgs, } from "./lib/runtime.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, 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 { getAgentBrowserProcessTimeoutMs, runAgentBrowserProcess } from "./lib/process.js";
+import { getCommandAwareProcessTimeoutMs } from "./lib/orchestration/browser-run/prepare/wait-timeouts.js";
+import { getAgentBrowserProcessEnvironment, withAgentBrowserProcessEnvironment, 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";
 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 { AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS, AGENT_BROWSER_SCRIPT_NAMESPACE, bindBrowserCodeCall, isAgentBrowserScriptSessionName, runAgentBrowserScript, } from "./lib/input-modes/script.js";
 import { canonicalizeExplicitArtifactDestination, getExplicitArtifactDestination, getRecordContactSheetDestination } from "./lib/orchestration/browser-run/artifact-paths.js";
-import { findElectronLaunchRecordForSession, getActiveElectronRecords, getSessionContextKey } from "./lib/orchestration/browser-run/session-state.js";
+import { findElectronLaunchRecordForSession, getActiveElectronRecords, getPersistentSessionArtifactStore, 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";
 import { applyAgentBrowserOutputPath, canWriteAgentBrowserOutput, normalizeRequestedOutputPath } from "./lib/orchestration/output-file.js";
-import { appendScriptSessionLease, buildScriptBrowserEnvelope, buildScriptToolResult, getScriptSessionLeasesFromBranch } from "./lib/orchestration/script-mode.js";
+import { appendScriptSessionLease, createBrowserCodeOutput, getScriptSessionLeasesFromBranch } from "./lib/orchestration/script-mode.js";
+import { resolveBrowserExecutionIdentity, withBrowserExecutionLock, withBrowserExecutionLocks } from "./lib/managed-session-policy-lock.js";
+import { registerAgentBrowserToolSurface } from "./lib/tool-surface.js";
 import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingCommand, isSessionArtifactManifest, mergeSessionArtifactManifest, retirePendingRecordingManifestEntries } from "./lib/results/artifact-manifest.js";
 import { appendUniqueAgentBrowserNextActions, applyNamespaceToNextActions, applySessionToNextActions, buildNextToolAction } from "./lib/results/next-actions.js";
 import { canRegisterWebSearchTool, loadAgentBrowserConfigSync } from "./lib/config.js";
@@ -37,6 +43,12 @@ import { createAgentBrowserWebSearchTool } from "./lib/web-search.js";
 import { scopeReadConfirmationArgs } from "./lib/read-confirmation.js";
 import { isDirectAgentBrowserBashAllowed, isHarmlessAgentBrowserInspectionCommand, looksLikeDirectAgentBrowserBash, } from "./lib/bash-guard.js";
 import { AgentBrowserResultComponent, buildAgentBrowserToolResultPatch, formatAgentBrowserRenderCall, formatAgentBrowserRenderResult, } from "./lib/pi-tool-rendering.js";
+function browserExecutionFailure(error, signal, fallbackCategory = "upstream-error") {
+    const timeout = error instanceof Error && error.name === "TimeoutError";
+    const summary = redactSensitiveText(error instanceof Error ? error.message : String(error));
+    const failureCategory = timeout ? "timeout" : signal?.aborted ? "aborted" : fallbackCategory;
+    return { content: [{ type: "text", text: summary }], details: { error: summary, summary, resultCategory: "failure", failureCategory }, isError: true };
+}
 function isBashToolCallEvent(event) {
     if (!isRecord(event) || event.toolName !== "bash" || !isRecord(event.input))
         return false;
@@ -165,10 +177,8 @@ function getResultFileArtifacts(result) {
 function restoreArtifactManifestFromBranch(branch) {
     let restoredManifest;
     for (const entry of branch) {
-        if (!isRecord(entry) || entry.type !== "message")
-            continue;
-        const message = isRecord(entry.message) ? entry.message : undefined;
-        if (!message || message.toolName !== "agent_browser")
+        const message = getBrowserResultMessage(entry);
+        if (!message)
             continue;
         const details = isRecord(message.details) ? message.details : undefined;
         if (isSessionArtifactManifest(details?.artifactManifest) && (!restoredManifest || details.artifactManifest.updatedAtMs >= restoredManifest.updatedAtMs)) {
@@ -187,10 +197,8 @@ function restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, sessionN
     let restored;
     const targetKey = getSessionContextKey(sessionName, namespace);
     for (const entry of branch) {
-        if (!isRecord(entry) || entry.type !== "message")
-            continue;
-        const message = isRecord(entry.message) ? entry.message : undefined;
-        if (!message || message.toolName !== "agent_browser")
+        const message = getBrowserResultMessage(entry);
+        if (!message)
             continue;
         const details = isRecord(message.details) ? message.details : undefined;
         if (!details)
@@ -220,10 +228,8 @@ function restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, sessionNa
     let restored = false;
     const targetKey = getSessionContextKey(sessionName, namespace);
     for (const entry of branch) {
-        if (!isRecord(entry) || entry.type !== "message")
-            continue;
-        const message = isRecord(entry.message) ? entry.message : undefined;
-        if (!message || message.toolName !== "agent_browser")
+        const message = getBrowserResultMessage(entry);
+        if (!message)
             continue;
         const details = isRecord(message.details) ? message.details : undefined;
         if (!details)
@@ -244,10 +250,8 @@ function restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, sessionNa
     let restored;
     const targetKey = getSessionContextKey(sessionName, namespace);
     for (const entry of branch) {
-        if (!isRecord(entry) || entry.type !== "message")
-            continue;
-        const message = isRecord(entry.message) ? entry.message : undefined;
-        if (!message || message.toolName !== "agent_browser")
+        const message = getBrowserResultMessage(entry);
+        if (!message)
             continue;
         const details = isRecord(message.details) ? message.details : undefined;
         if (!details)
@@ -291,10 +295,8 @@ function isAttachedBrowserInvocation(args, env = getAgentBrowserProcessEnvironme
 function restoreAttachedSessionKeysFromBranch(branch) {
     const attachedSessionKeys = new Set();
     for (const entry of branch) {
-        if (!isRecord(entry) || entry.type !== "message")
-            continue;
-        const message = isRecord(entry.message) ? entry.message : undefined;
-        if (!message || message.toolName !== "agent_browser")
+        const message = getBrowserResultMessage(entry);
+        if (!message)
             continue;
         const details = isRecord(message.details) ? message.details : undefined;
         if (!details)
@@ -537,10 +539,8 @@ function collectBranchManagedResourceEvents(branch) {
     };
     let eventRank = 0;
     for (const entry of branch) {
-        if (!isRecord(entry) || entry.type !== "message")
-            continue;
-        const message = isRecord(entry.message) ? entry.message : undefined;
-        if (!message || message.toolName !== "agent_browser")
+        const message = getBrowserResultMessage(entry);
+        if (!message)
             continue;
         const details = isRecord(message.details) ? message.details : undefined;
         if (!details)
@@ -659,36 +659,56 @@ function shouldSerializeBrowserCommand(options) {
 // Serializes managed-session read/modify/write work so overlapping tool calls cannot promote stale state or close an in-use session.
 class AsyncExecutionQueue {
     tail = Promise.resolve();
-    run(work) {
+    active = new AsyncLocalStorage();
+    isCurrent() { return this.active.getStore()?.active === true; }
+    run(work, signal, barrier = Promise.resolve()) {
+        if (this.isCurrent()) {
+            signal?.throwIfAborted();
+            return work();
+        }
         const previous = this.tail;
         let release;
         this.tail = new Promise((resolve) => {
             release = resolve;
         });
-        return (async () => {
-            await previous;
+        let rejectWaiting;
+        const cancelled = new Promise((_resolve, reject) => { rejectWaiting = reject; });
+        const abortWaiting = () => rejectWaiting(signal?.reason);
+        signal?.addEventListener("abort", abortWaiting, { once: true });
+        if (signal?.aborted)
+            abortWaiting();
+        const execution = (async () => {
+            await Promise.all([previous, barrier]);
+            signal?.removeEventListener("abort", abortWaiting);
             try {
-                return await work();
+                signal?.throwIfAborted();
+                const scope = { active: true };
+                try {
+                    return await this.active.run(scope, work);
+                }
+                finally {
+                    scope.active = false;
+                }
             }
             finally {
                 release();
             }
         })();
+        return signal ? Promise.race([execution, cancelled]) : execution;
     }
 }
 export class KeyedAsyncExecutionQueue {
     barriers = new Map();
     entries = new Map();
-    async run(key, namespace, work) {
+    async run(key, namespace, work, signal) {
         const entry = this.entries.get(key) ?? { queue: new AsyncExecutionQueue(), users: 0 };
+        if (entry.queue.isCurrent())
+            return work();
         const barrier = this.barriers.get(getAgentBrowserSessionIdentityKey("", namespace)) ?? Promise.resolve();
         entry.users += 1;
         this.entries.set(key, entry);
         try {
-            return await entry.queue.run(async () => {
-                await barrier;
-                return await work();
-            });
+            return await entry.queue.run(work, signal, barrier);
         }
         finally {
             entry.users -= 1;
@@ -1108,7 +1128,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 +1179,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 +1188,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 +1204,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),
@@ -1226,31 +1246,32 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             cwd: ctx.cwd,
             includeProjectConfig: shouldIncludeProjectConfig(ctx),
         }));
-        await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(async () => {
+        await managedSessionExecutionQueue.run(() => artifactExecutionQueue.run(async () => {
             await recoverScriptSessionLeasesWithinQueue(ctx);
             flushRecordingReservations();
             notifyRecordingPersistence(ctx);
         }));
     });
     pi.on("session_tree", async (_event, ctx) => {
+        branchRestoreGeneration += 1;
         for (const controller of activeScriptControllers)
             controller.abort();
         await Promise.allSettled([...activeScriptExecutions]);
-        await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(async () => {
+        await managedSessionExecutionQueue.run(() => artifactExecutionQueue.run(async () => {
             restoreBranchBackedState(ctx, { resetRuntimeOwnership: false });
             await recoverScriptSessionLeasesWithinQueue(ctx);
             flushRecordingReservations();
             notifyRecordingPersistence(ctx);
         }));
     });
-    // Additive native checkpoint event; the package's 0.84 validation types predate it.
-    // Pi owns awaited tools/events (including their execution queues). Only script
-    // children and retained browser/recording resources need extension-side checks.
+    // Fork-only checkpoint event; official Pi validation types do not declare it.
+    // Pi owns awaited tools/events (including their execution queues). Detached code
+    // children and retained browser/recording resources still 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");
+            return blocked("Browser code execution is pending");
         flushRecordingReservations();
         if (recordingReservationsDirty)
             return blocked("Browser recording journal persistence is dirty");
@@ -1276,9 +1297,10 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         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")
+            const message = getBrowserResultMessage(entry);
+            if (!message)
                 continue;
-            const details = isRecord(entry.message.details) ? entry.message.details : undefined;
+            const details = isRecord(message.details) ? 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
@@ -1322,7 +1344,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         branchRestoreGeneration += 1;
         branchStateGeneration += 1;
         let preservedElectronProfileDirs = [];
-        await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(async () => {
+        await managedSessionExecutionQueue.run(() => artifactExecutionQueue.run(async () => {
             const shutdownCwd = ctx?.cwd ?? managedSessionCwd;
             const quitting = event?.reason === "quit";
             preservedElectronProfileDirs = quitting
@@ -1396,9 +1418,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         const runtimeConfigPrompt = browserGuidance.length > 0
             ? `\n\nProject agent_browser config guidance:\n${browserGuidance.map((line) => `- ${line}`).join("\n")}`
             : "";
-        return {
-            systemPrompt: `${event.systemPrompt}\n\n${PROJECT_RULE_PROMPT}${runtimeConfigPrompt}`,
-        };
+        event.systemPromptOptions.sections.agent_browser = `${PROJECT_RULE_PROMPT}${runtimeConfigPrompt}`;
     });
     pi.on("tool_call", async (event, ctx) => {
         const promptPolicy = buildPromptPolicy(getLatestUserPrompt(ctx.sessionManager.getBranch()));
@@ -1415,12 +1435,6 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
     });
     pi.on("tool_result", async (event) => buildAgentBrowserToolResultPatch(event));
     const agentBrowserTool = {
-        name: "agent_browser",
-        label: "Agent Browser",
-        description: "Browse and interact with websites using agent-browser. Use this for reading live pages, opening known URLs, taking snapshots or screenshots, clicking links, filling forms, extracting page content, and authenticated/profile-based browser work. Input choice: `script` for one-shot JavaScript orchestration; default `args` for open → snapshot -i → click/fill @refs; `semanticAction` for stable role/text/label targets; `job` or `qa` for multi-step checks; `electron` only for desktop apps; experimental `sourceLookup` / `networkSourceLookup` for candidates only.",
-        promptSnippet: "Browse websites, read live docs, click and fill pages, extract browser content, take screenshots, and automate real web workflows.",
-        promptGuidelines: toolPromptGuidelines,
-        parameters: AGENT_BROWSER_PARAMS,
         renderCall(args, theme, context) {
             const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
             text.setText(formatAgentBrowserRenderCall(args, theme, context.expanded));
@@ -1433,479 +1447,598 @@ 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, modelVisible = true) {
+            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 !== "electron"
+                && !extractExplicitSessionName(admittedInput.toolArgs) && !explicitConfig;
+            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.",
-                        });
+                const executionTimeoutMs = (resolvedInput.kind === "electron" && "timeoutMs" in resolvedInput.compiledElectron ? resolvedInput.compiledElectron.timeoutMs : undefined) ?? params.timeoutMs ?? getCommandAwareProcessTimeoutMs(extractUpstreamCommandTokens(resolvedInput.toolArgs), resolvedInput.toolStdin) ?? getAgentBrowserProcessTimeoutMs();
+                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 artifactExecutionQueue.run(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 (!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);
-                                }));
+                    const { toolArgs } = resolvedInput;
+                    const compiledElectron = resolvedInput.kind === "electron" ? resolvedInput.compiledElectron : undefined;
+                    const redactedCompiledElectron = resolvedInput.kind === "electron" ? resolvedInput.redactedCompiledElectron : undefined;
+                    const runElectronHostInput = async (executionSignal = signal) => {
+                        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: executionSignal,
+                        });
+                        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);
+                                }
                             }
-                            catch {
-                                cleanupError = "The isolated script session cleanup operation failed.";
-                                try {
-                                    appendScriptSessionLease(pi, sessionName, "failed");
+                            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 { }
                             }
-                        }
-                        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),
-                            },
-                        };
-                    }
-                    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);
+                            if (artifactManifest) {
+                                electronHostResult = {
+                                    ...electronHostResult,
+                                    details: {
+                                        ...(isRecord(electronHostResult.details) ? electronHostResult.details : {}),
+                                        artifactManifest: redactSensitiveValue(artifactManifest),
+                                        artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
+                                    },
+                                };
                             }
                         }
-                        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 (electronHostResult && executionSignal?.aborted) {
+                            const failure = browserExecutionFailure(executionSignal.reason, executionSignal);
+                            return { ...electronHostResult, ...failure, details: { ...(isRecord(electronHostResult.details) ? electronHostResult.details : {}), ...(isRecord(failure.details) ? failure.details : {}) } };
                         }
-                        if (artifactManifest) {
-                            electronHostResult = {
-                                ...electronHostResult,
-                                details: {
-                                    ...(isRecord(electronHostResult.details) ? electronHostResult.details : {}),
-                                    artifactManifest: redactSensitiveValue(artifactManifest),
-                                    artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
-                                },
-                            };
+                        return electronHostResult;
+                    };
+                    const runCoordinatedElectronHostInput = async () => {
+                        const execute = (executionSignal = signal) => compiledElectron?.action === "cleanup"
+                            ? artifactExecutionQueue.run(async () => {
+                                flushRecordingReservations();
+                                const error = outputPath ? getArtifactPreflightValidationError({ activeRecordingReservations: activeRecordingReservations.values(), args: [], cwd: operationCwd, outputPath }) : undefined;
+                                if (error)
+                                    return warnRecordingPersistence(buildValidationFailureResult({ ...resolvedInput, attemptedKind: resolvedInput.kind, kind: "invalid", status: "invalid", validationError: error }));
+                                const result = await runElectronHostInput(executionSignal);
+                                return result ? applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, result: warnRecordingPersistence(result) }) : result;
+                            }) : runElectronHostInput(executionSignal);
+                        if (!shouldSerializeElectronHostInput(compiledElectron))
+                            return execute();
+                        const records = getElectronHostLaunchRecordsForInput({ branchRecords: electronLaunchRecords, compiledElectron, ownedRecords: ownedElectronLaunchRecords });
+                        const launchId = compiledElectron && "launchId" in compiledElectron ? compiledElectron.launchId : undefined;
+                        const selected = launchId ? [records.get(launchId)].filter((record) => record !== undefined) : getActiveElectronRecords(records);
+                        const sessions = selected.flatMap(record => record.sessionName ? [{ sessionName: record.sessionName, namespace: record.namespace }] : []);
+                        if (compiledElectron?.action === "probe" && !launchId && managedSessionActive)
+                            sessions.push({ sessionName: managedSessionName, namespace: managedSessionNamespace });
+                        if (sessions.length === 0)
+                            return execute();
+                        try {
+                            const identities = await Promise.all(sessions.map(session => resolveBrowserExecutionIdentity({ ...session, ownedManagedSession: true })));
+                            return await withBrowserExecutionLocks({ identities, signal, deadline: Date.now() + executionTimeoutMs, waitOnly: true }, execute);
                         }
-                    }
-                    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: 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 }));
+                        catch (error) {
+                            return browserExecutionFailure(error, signal);
                         }
-                        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) => {
-                    // 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,
+                    };
+                    const electronHostResult = await (shouldSerializeElectronHostInput(compiledElectron)
+                        ? managedSessionExecutionQueue.run(runCoordinatedElectronHostInput, signal)
+                        : runCoordinatedElectronHostInput());
+                    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, executionSignal = signal) => {
+                        // 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,
+                            modelVisible,
+                            onUpdate,
+                            params,
+                            establishAttachedBrowserSession: attachedSessionRequested && !attachedSessionKnown,
+                            preserveAttachedBrowserSession: attachedSessionRequested || attachedSessionKnown,
+                            promptPolicy,
+                            sessionPageStateUpdate,
+                            signal: executionSignal,
+                            state: browserRunState,
+                        });
+                        const branchRestoreStillCurrent = branchRestoreGenerationAtStart === branchRestoreGeneration;
+                        const resultDetails = isRecord(result.details) ? result.details : undefined;
+                        if (typeof resultDetails?.sessionName === "string" && browserRunState.managedSessionActive
+                            && getAgentBrowserSessionIdentityKey(resultDetails.sessionName, typeof resultDetails.namespace === "string" ? resultDetails.namespace : undefined) === getAgentBrowserSessionIdentityKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace)) {
+                            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);
+                        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;
                         }
-                        if (artifactManifest) {
-                            result = {
-                                ...result,
-                                details: {
-                                    ...(isRecord(result.details) ? result.details : {}),
-                                    artifactManifest: redactSensitiveValue(artifactManifest),
-                                    artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
-                                },
-                            };
+                        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 = async () => {
+                        // Electron's browser identity is known before its host process supplies the CDP port.
+                        const plan = buildExecutionPlan(compiledElectron?.action === "launch" ? ["connect"] : toolArgs, {
+                            freshSessionName: createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1),
+                            managedSessionActive, managedSessionCompatibilityWorkaround, managedSessionName, managedSessionNamespace,
+                            sessionMode: compiledElectron?.action === "launch" ? "fresh" : params.sessionMode ?? "auto",
+                            stdin: resolvedInput.toolStdin,
+                        });
+                        const run = (executionSignal = signal) => {
+                            const execute = () => withLaunchDefaults
+                                ? withLaunchDefaults(inactive => runBrowserCommand(inactive, executionSignal), executionSignal)
+                                : runBrowserCommand(undefined, executionSignal);
+                            if (!commandTouchesArtifactLifecycle(toolArgs, resolvedInput.toolStdin, outputPath))
+                                return execute();
+                            return artifactExecutionQueue.run(async () => {
+                                const error = getArtifactPreflightValidationError({ activeRecordingReservations: activeRecordingReservations.values(), args: toolArgs, cwd: operationCwd, outputPath, stdin: resolvedInput.toolStdin });
+                                if (!error)
+                                    return execute();
+                                flushRecordingReservations();
+                                return warnRecordingPersistence(buildValidationFailureResult({ ...resolvedInput, attemptedKind: resolvedInput.kind, kind: "invalid", status: "invalid", validationError: error }));
+                            });
+                        };
+                        if (plan.validationError || (!plan.sessionName && plan.commandInfo.command !== "read" && !closesAllSessions))
+                            return run();
+                        try {
+                            const owned = plan.managedSessionName !== undefined || ownedManagedSessions.has(getAgentBrowserSessionIdentityKey(plan.sessionName ?? "default", plan.namespace));
+                            const identities = [await resolveBrowserExecutionIdentity({ namespace: plan.namespace, ownedManagedSession: owned, sessionName: closesAllSessions ? undefined : plan.sessionName ?? "default" })];
+                            if (managedSessionActive && (params.sessionMode === "fresh" || compiledElectron?.action === "launch") && !explicitSessionName) {
+                                identities.push(await resolveBrowserExecutionIdentity({ namespace: managedSessionNamespace, ownedManagedSession: true, sessionName: managedSessionName }));
+                            }
+                            const activePageUrl = sessionPageState.get(getAgentBrowserSessionIdentityKey(plan.sessionName ?? "default", plan.namespace)).tabTarget?.url;
+                            const deadline = Date.now() + (params.timeoutMs ?? getCommandAwareProcessTimeoutMs(extractUpstreamCommandTokens(toolArgs), resolvedInput.toolStdin, activePageUrl) ?? getAgentBrowserProcessTimeoutMs());
+                            return await withBrowserExecutionLocks({ identities, signal, deadline, waitOnly: true }, run);
                         }
-                    }
-                    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);
+                        catch (error) {
+                            return browserExecutionFailure(error, signal);
                         }
-                        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,
+                    };
+                    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 callerOwnedSessionExecutionQueues.runExclusive(plan.namespace, runWithLaunchDefaults);
                             });
-                            return callerOwnedSessionExecutionQueues.runExclusive(plan.namespace, runWithLaunchDefaults);
-                        });
-                    if (serializeBrowserCommand)
-                        return managedSessionExecutionQueue.run(runWithLaunchDefaults);
-                    return callerOwnedSessionQueueKey
-                        ? callerOwnedSessionExecutionQueues.run(callerOwnedSessionQueueKey, callerOwnedSessionNamespace, runWithLaunchDefaults)
-                        : runWithLaunchDefaults();
-                };
-                if (!commandTouchesArtifactLifecycle(toolArgs, resolvedInput.toolStdin, outputPath))
+                        if (serializeBrowserCommand)
+                            return managedSessionExecutionQueue.run(runWithLaunchDefaults, signal);
+                        return callerOwnedSessionQueueKey
+                            ? callerOwnedSessionExecutionQueues.run(callerOwnedSessionQueueKey, callerOwnedSessionNamespace, runWithLaunchDefaults, signal)
+                            : runWithLaunchDefaults();
+                    };
                     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,
-                    }));
+                }, 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();
+            return managedSessionExecutionQueue.run(executeAdmitted, signal);
         },
     };
-    pi.registerTool(beforeExecute ? { ...agentBrowserTool, executionMode: "sequential" } : agentBrowserTool);
+    const executeCode = async (toolCallId, params, signal, _onUpdate, ctx) => {
+        if (!ctx.sessionManager.getSessionFile())
+            return browserExecutionFailure(new Error("agent_browser_code requires a persisted Pi session for ordered browser-state recovery; relaunch without --no-session."), signal, "validation-error");
+        let operationCwd;
+        try {
+            operationCwd = resolveExecutionCwd(pi, ctx);
+        }
+        catch (error) {
+            return browserExecutionFailure(error, signal, "validation-error");
+        }
+        const controller = new AbortController();
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        activeScriptControllers.add(controller);
+        let finish;
+        const execution = new Promise(resolve => { finish = resolve; });
+        activeScriptExecutions.add(execution);
+        const deadline = Date.now() + (params.timeoutMs ?? AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS);
+        const deadlineTimer = setTimeout(() => controller.abort(new DOMException("Browser code deadline exceeded.", "TimeoutError")), Math.max(0, deadline - Date.now()));
+        const generation = branchRestoreGeneration;
+        const output = createBrowserCodeOutput();
+        const nativeEnvironment = getAgentBrowserProcessEnvironment();
+        try {
+            const args = [
+                ...(params.namespace !== undefined ? ["--namespace", params.namespace] : []),
+                ...(params.session !== undefined ? ["--session", params.session] : []),
+                "get", "url",
+            ];
+            const input = resolveAgentBrowserInput({ params: { args }, getBatchPreflightValidationError: () => undefined });
+            if (input.status === "invalid")
+                return buildValidationFailureResult(input);
+            const config = loadAgentBrowserConfigSync({ cwd: ctx.cwd, includeProjectConfig: shouldIncludeProjectConfig(ctx) });
+            const profile = config.trustedBrowserDefaultProfile;
+            const rootId = process.env.PI_SUBAGENT_CHILD === "1" && process.env.PI_SUBAGENT_ROOT_SESSION_ID
+                ? process.env.PI_SUBAGENT_ROOT_SESSION_ID : ctx.sessionManager.getSessionId();
+            const runAdmitted = async () => {
+                const owner = params.session ? ownedManagedSessions.get(getAgentBrowserSessionIdentityKey(params.session, params.namespace ?? nativeEnvironment.AGENT_BROWSER_NAMESPACE)) : undefined;
+                const browserCwd = nativeEnvironment.AGENT_BROWSER_CONFIG !== undefined ? operationCwd
+                    : params.session ? owner?.cwd ?? ctx.cwd : managedSessionActive ? managedSessionCwd : ctx.cwd;
+                const cwdError = getBrowserCwdError(browserCwd);
+                if (cwdError)
+                    return browserExecutionFailure(new Error(cwdError), controller.signal, "validation-error");
+                return withNativeSessionDefaults(input, browserCwd, controller.signal, async (input) => {
+                    const plan = buildExecutionPlan(input.toolArgs, { freshSessionName: managedSessionName, managedSessionActive, managedSessionName, managedSessionNamespace, sessionMode: "auto" });
+                    const sessionName = plan.sessionName ?? "default";
+                    const namespace = plan.namespace || undefined;
+                    const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+                    const owned = plan.managedSessionName !== undefined || ownedManagedSessions.has(key);
+                    const run = async () => {
+                        const identity = await resolveBrowserExecutionIdentity({ sessionName, namespace, ownedManagedSession: owned });
+                        return withBrowserExecutionLock({ identity, deadline, signal: controller.signal }, async (executionSignal) => {
+                            let journalFailed = false;
+                            const run = await runAgentBrowserScript({
+                                code: params.code, signal: executionSignal, timeoutMs: Math.max(1, deadline - Date.now()),
+                                emitImage: output.emitImage,
+                                dispatch: async (inner, innerSignal) => {
+                                    if (journalFailed)
+                                        throw new Error("Browser-state persistence failed. Inspect the current page before continuing in another tool call.");
+                                    const { args } = bindBrowserCodeCall(inner, { sessionName, namespace });
+                                    if (plan.usedImplicitSession && !managedSessionActive && managedSessionName === sessionName && extractExplicitSessionName(inner.args) === undefined)
+                                        args.splice(args.indexOf("--session"), 2);
+                                    const pending = { args: redactInvocationArgs(args), sessionName, namespace, resultCategory: "failure", sessionTabTargetUnknown: true };
+                                    try {
+                                        appendBrowserTransition(pi, toolCallId, pending, true);
+                                    }
+                                    catch {
+                                        journalFailed = true;
+                                        throw new Error("Could not persist browser-state intent; the browser command was not run.");
+                                    }
+                                    // Resolve launch defaults from the real command, never the routing-only get-url probe.
+                                    const result = await withAgentBrowserProcessEnvironment({ AGENT_BROWSER_SESSION: nativeEnvironment.AGENT_BROWSER_SESSION }, () => agentBrowserTool.execute(toolCallId, { args, stdin: inner.stdin, timeoutMs: Math.min(inner.timeoutMs ?? deadline - Date.now(), Math.max(1, deadline - Date.now())) }, innerSignal, undefined, ctx, toolCallId, operationCwd, false));
+                                    const page = sessionPageState.get(key);
+                                    const details = { ...(isRecord(result.details) ? result.details : {}), sessionName, namespace, sessionTabTarget: page.tabTarget, sessionTabTargetUnknown: page.tabTargetUnknown, sessionTabReopenPending: page.tabReopenPending, refSnapshot: page.refSnapshot, refSnapshotInvalidation: page.refSnapshotInvalidation };
+                                    if (generation === branchRestoreGeneration) {
+                                        try {
+                                            appendBrowserTransition(pi, toolCallId, details, result.isError === true);
+                                        }
+                                        catch {
+                                            journalFailed = true;
+                                            throw new Error("The browser command finished, but its state could not be persisted. Inspect before retrying; changes may already have happened.");
+                                        }
+                                    }
+                                    return output.observe(result);
+                                },
+                            });
+                            const result = await output.finish(run, sessionName, namespace);
+                            if (artifactManifest && isRecord(result.details))
+                                result.details.artifactManifest = redactSensitiveValue(artifactManifest);
+                            if (!params.outputPath)
+                                return result;
+                            return artifactExecutionQueue.run(async () => {
+                                const error = getArtifactPreflightValidationError({ args: [], cwd: operationCwd, outputPath: params.outputPath, activeRecordingReservations: activeRecordingReservations.values() });
+                                if (error) {
+                                    const failure = browserExecutionFailure(new Error(error), undefined, "validation-error");
+                                    return { ...result, isError: true, content: [...failure.content, ...result.content], details: { ...(isRecord(result.details) ? result.details : {}), ...(isRecord(failure.details) ? failure.details : {}) } };
+                                }
+                                return applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath: params.outputPath, preserveTextContent: true, result });
+                            });
+                        });
+                    };
+                    return shouldSerializeBrowserCommand({ namespace, explicitSessionName: sessionName, managedSessionName, ownedElectronLaunchRecords, ownedManagedSessions })
+                        ? managedSessionExecutionQueue.run(run, controller.signal)
+                        : callerOwnedSessionExecutionQueues.run(key, namespace, run, controller.signal);
+                }, managedSessionActive || freshSessionOrdinal > 0 ? undefined : { id: rootId, profile: profile?.policy === "always" && !/[\\/~]/.test(profile.name) ? profile.name : undefined, executablePath: config.trustedBrowserExecutablePath });
+            };
+            return await (!params.session && nativeEnvironment.AGENT_BROWSER_CONFIG === undefined
+                ? managedSessionExecutionQueue.run(runAdmitted, controller.signal) : runAdmitted());
+        }
+        catch (error) {
+            return browserExecutionFailure(error, controller.signal);
+        }
+        finally {
+            clearTimeout(deadlineTimer);
+            activeScriptControllers.delete(controller);
+            signal?.removeEventListener("abort", abort);
+            activeScriptExecutions.delete(execution);
+            finish();
+        }
+    };
+    const finalizeObservation = async (result, params, ctx) => {
+        if ("args" in params && params.args && isPlainTextInspectionArgs(params.args))
+            return result;
+        const { renderAgentBrowserObservation } = await import("./lib/results/presentation/large-output.js");
+        const details = isRecord(result.details) ? result.details : {};
+        if (result.isError && details.error === undefined)
+            details.error = details.validationError ?? details.summary ?? result.content.filter(item => item.type === "text").map(item => item.text).join("\n");
+        const priorManifest = isSessionArtifactManifest(details.artifactManifest) ? details.artifactManifest : undefined;
+        const rendered = await renderAgentBrowserObservation({ content: result.content, details, json: "code" in params || params.args?.includes("--json") === true, succeeded: result.isError !== true, persistentArtifactStore: getPersistentSessionArtifactStore(ctx) });
+        artifactManifest = mergeBrowserRunArtifactManifest(artifactManifest, priorManifest, rendered.artifactManifest);
+        return { ...result, content: rendered.content, details: { ...details, ...(artifactManifest ? { artifactManifest: redactSensitiveValue(artifactManifest) } : {}) } };
+    };
+    registerAgentBrowserToolSurface(pi, {
+        async execute(id, params, signal, onUpdate, ctx) {
+            let result;
+            try {
+                result = await agentBrowserTool.execute(id, params, signal, onUpdate, ctx);
+            }
+            catch (error) {
+                result = browserExecutionFailure(error, signal);
+            }
+            return finalizeObservation(result, params, ctx);
+        },
+        async executeCode(id, params, signal, onUpdate, ctx) {
+            const result = await executeCode(id, params, signal, onUpdate, ctx);
+            return finalizeObservation(result, params, ctx);
+        },
+        executionMode: beforeExecute ? "sequential" : undefined,
+        renderCodeCall(args, theme, context) {
+            const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+            text.setText(formatAgentBrowserRenderCall(args, theme, context.expanded));
+            return text;
+        },
+        promptGuidelines: toolPromptGuidelines,
+        renderCall: agentBrowserTool.renderCall, renderResult: agentBrowserTool.renderResult,
+    });
     registerWebSearchToolIfAvailable(agentBrowserConfig);
 }